diff --git a/README.md b/README.md
index 5cdbe3d..b3c2ca2 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,8 @@ Or run the `hello` action:
$ docker runx NAMESPACE/REPOSITORY hello
```
+See more examples in the [examples](/examples) directory.
+
## CLI Plugin Installation
### Manual Installation
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..fba733b
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,36 @@
+# `docker runx` examples
+
+This directory contains examples used to decorate some images with `runx`.
+
+## Build
+
+### [hello](hello)
+
+```
+$ cd hello
+$ docker runx decorate alpine -t NAMESPACE/hello
+```
+
+An already built image is available under `eunomie/runx-hello`.
+
+### [golangci](golangci)
+
+```
+$ cd golangci
+$ docker runx decorate golangci/golangci-lint:latest -t NAMESPACE/golangci
+```
+
+An already built image is available under `eunomie/runx-golangci`.
+
+### [go](go)
+
+```
+$ cd go
+$ docker runx decorate scratch -t NAMESPACE/go
+```
+
+An already built image is available under `eunomie/go`.
+
+## Usage
+
+Once you built your images, explore them using `--docs` and `--list` options.
diff --git a/examples/alpine-hello.readme.md b/examples/alpine-hello.readme.md
deleted file mode 100644
index a0d174c..0000000
--- a/examples/alpine-hello.readme.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Hello !
-
-If you run this image, it will be a simple `alpine` image.
-
-If you run this image using `docker runx` and by specifying the `hello` action, it will display a message.
-
-```console
-$ docker runx hello
-```
diff --git a/examples/go/Dockerfile b/examples/go/Dockerfile
new file mode 100644
index 0000000..acff615
--- /dev/null
+++ b/examples/go/Dockerfile
@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1.4
+
+ARG XX_VERSION=1.2.1
+ARG ALPINE_VERSION=3.20
+ARG GO_VERSION=1.23.1
+
+ARG BIN_NAME
+
+FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx
+
+FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS build-base
+COPY --from=xx / /
+RUN apk add --no-cache curl
+RUN sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
+RUN apk add --no-cache git ca-certificates openssh-client
+
+FROM build-base AS build
+ARG TARGETPLATFORM
+RUN xx-go --wrap
+WORKDIR /go/src/
+COPY go.mod ./
+COPY go.sum ./
+RUN --mount=type=ssh \
+ --mount=type=cache,target=/root/.cache \
+ --mount=type=cache,target=/go/pkg/mod \
+ go mod download
+COPY . ./
+
+FROM build AS binary
+ENV CGO_ENABLED=0
+ARG BIN_NAME
+RUN --mount=type=cache,target=/root/.cache \
+ --mount=type=cache,target=/go/pkg/mod \
+ GIT_VERSION=$(git describe --tags | cut -c 2-) && \
+ xx-go build \
+ -o dist/${BIN_NAME} \
+ -ldflags="-w -s \
+ -X {{.PKG_NAME}}/internal/constants.Version=$GIT_VERSION" \
+ ./cmd/${BIN_NAME} && \
+ xx-verify dist/${BIN_NAME}
+
+FROM scratch AS export-bin
+ARG BIN_NAME
+ARG TARGETOS
+ARG TARGETARCH
+COPY --from=binary /go/src/dist/${BIN_NAME} /${BIN_NAME}-${TARGETOS}-${TARGETARCH}
diff --git a/examples/go/README.md b/examples/go/README.md
new file mode 100644
index 0000000..015dc66
--- /dev/null
+++ b/examples/go/README.md
@@ -0,0 +1,36 @@
+# Go tools - runx version
+
+This is a set of multiple tools to work with Go codebases.
+
+## Usage
+
+### Linter
+
+`lint` action will run `golangci-lint` on the codebase.
+
+Go packages and cache are shared with `golangci-lint` to speed up the process.
+
+### Build
+
+`build` action will build the codebase using `docker buildx` and output as (multi-platform) binaries.
+
+By convention if the binary name is `tool`, it will try to build `cmd/tool/` and the output will be inside `dist` directory.
+
+To make it more convenient while working on a code base, create a file `.docker/runx.yaml` with the following content:
+
+```yaml
+ref: eunomie/go
+images:
+ eunomie/go:
+ actions:
+ build:
+ opts:
+ bin_name:
+ platforms:
+```
+
+That way you will be able to run `docker runx build` without to specify anything else.
+
+### Mocks
+
+`mocks` action will generate mocks for the codebase using `mockery`.
diff --git a/examples/alpine-hello.runx.yaml b/examples/go/runx.yaml
similarity index 71%
rename from examples/alpine-hello.runx.yaml
rename to examples/go/runx.yaml
index c1d7569..2722fa4 100644
--- a/examples/alpine-hello.runx.yaml
+++ b/examples/go/runx.yaml
@@ -1,25 +1,4 @@
-default: hello
actions:
- - id: hello:user
- desc: Say hello to the current user
- type: run
- env:
- - USER
- shell:
- uname: uname
- cmd: --rm {{.Ref}} echo hello {{env "USER"}} from {{sh "uname"}}
-
- - id: hello
- desc: Say hello!
- type: run
- opts:
- - name: name
- desc: User's name
- prompt: Please enter your name
- required: true
- cmd: >
- --rm {{.Ref}} echo hello {{opt "name"}}
-
- id: lint
desc: Run golangci-lint
type: run
@@ -55,3 +34,20 @@ actions:
--target export-bin
--output type=local,dest=dist/
.
+
+ - id: mocks
+ type: run
+ shell:
+ pwd: pwd
+ gopath: go env GOPATH
+ gocache: go env GOCACHE
+ cmd: >
+ --rm
+ -v {{sh "pwd"}}:/app
+ -v {{sh "gopath"}}/pkg:/go/pkg
+ -v {{sh "gocache"}}:/cache/go
+ -e GOCACHE=/cache/go
+ -v {{sh "pwd"}}:/src
+ -w /src
+ docker/mockery:v2.46
+ --keeptree -r --all
diff --git a/examples/golangci/README.md b/examples/golangci/README.md
new file mode 100644
index 0000000..77a3838
--- /dev/null
+++ b/examples/golangci/README.md
@@ -0,0 +1,801 @@
+
+
+
golangci-lint
+ Fast linters runner for Go
+
+
+---
+
+`golangci-lint` is a fast Go linters runner.
+
+It runs linters in parallel, uses caching, supports YAML configuration,
+integrates with all major IDEs, and includes over a hundred linters.
+
+## Install `golangci-lint`
+
+- [On my machine](https://golangci-lint.run/welcome/install/#local-installation);
+- [On CI/CD systems](https://golangci-lint.run/welcome/install/#ci-installation).
+
+## Documentation
+
+Documentation is hosted at https://golangci-lint.run.
+
+## Social Networks
+
+[![Join Slack](https://img.shields.io/badge/Slack-4285F4?logo=slack&logoColor=white)](https://gophers.slack.com/archives/CS0TBRKPC)
+[![Follow on Mastodon](https://img.shields.io/badge/mastodon-6364FF?logo=mastodon&logoColor=white)](https://fosstodon.org/@golangcilint)
+[![Follow on Twitter](https://img.shields.io/badge/twitter-1DA1F2?logo=twitter&logoColor=white)](https://twitter.com/golangci)
+
+## Supporting Us
+
+[![Open Collective backers and sponsors](https://img.shields.io/badge/OpenCollective-Donate-blue?logo=opencollective&style=for-the-badge)](https://opencollective.com/golangci-lint)
+[![GitHub Sponsors](https://img.shields.io/badge/GitHub-Donate-blue?logo=github&style=for-the-badge)](https://github.com/sponsors/golangci)
+[![Linter Authors](https://img.shields.io/badge/Linter_Authors-Donate-blue?style=for-the-badge)](https://golangci-lint.run/product/thanks/)
+
+`golangci-lint` is a free and open-source project built by volunteers.
+
+If you value it, consider supporting us, we appreciate it! :heart:
+
+## Badges
+
+![Build Status](https://github.com/golangci/golangci-lint/workflows/CI/badge.svg)
+[![License](https://img.shields.io/github/license/golangci/golangci-lint)](/LICENSE)
+[![Release](https://img.shields.io/github/release/golangci/golangci-lint.svg)](https://github.com/golangci/golangci-lint/releases/latest)
+[![Docker](https://img.shields.io/docker/pulls/golangci/golangci-lint)](https://hub.docker.com/r/golangci/golangci-lint)
+[![GitHub Releases Stats of golangci-lint](https://img.shields.io/github/downloads/golangci/golangci-lint/total.svg?logo=github)](https://somsubhra.github.io/github-release-stats/?username=golangci&repository=golangci-lint)
+
+## Contributors
+
+This project exists thanks to all the people who contribute. [How to contribute](https://golangci-lint.run/contributing/quick-start/).
+
+
+
+
+### Core Team
+
+
+About core team
+
+The GolangCI Core Team is a group of contributors who have demonstrated a lasting enthusiasm for the project and community.
+The GolangCI Core Team has GitHub admin privileges on the repo.
+
+#### Responsibilities
+
+The Core Team has the following responsibilities:
+
+1. Being available to answer high-level questions about vision and future.
+2. Being available to review longstanding/forgotten pull requests.
+3. Occasionally check issues, offer input, and categorize with GitHub issue labels.
+4. Looking out for up-and-coming members of the GolangCI community who might want to serve as Core Team members.
+5. Note that the Core Team – and all GolangCI contributors – are open-source volunteers; membership on the Core Team is expressly not an obligation. The Core Team is distinguished as leaders in the community and while they are a good group to turn to when someone needs an answer to a question, they are still volunteering their time, and may not be available to help immediately.
+
+
+
+
+
+### Team
+
+
+
+
+And 509 more our team members
+
+
+
+
+
+
+
+
+
+## Stargazers over time
+
+[![Stargazers over time](https://starchart.cc/golangci/golangci-lint.svg)](https://starchart.cc/golangci/golangci-lint)
\ No newline at end of file
diff --git a/examples/golangci/runx.yaml b/examples/golangci/runx.yaml
new file mode 100644
index 0000000..a674eba
--- /dev/null
+++ b/examples/golangci/runx.yaml
@@ -0,0 +1,44 @@
+default: lint
+actions:
+ - id: lint
+ desc: Run golangci-lint
+ type: run
+ shell:
+ pwd: pwd
+ gopath: go env GOPATH
+ gocache: go env GOCACHE
+ cmd: >
+ --rm
+ -v {{sh "pwd"}}:/app
+ -v {{sh "gopath"}}/pkg:/go/pkg
+ -v {{sh "gocache"}}:/cache/go
+ -e GOFLAGS=-buildvcs=false
+ -e GOCACHE=/cache/go
+ -e GOLANGCI_LINT_CACHE=/cache/go
+ -w /app
+ {{.Ref}}
+ golangci-lint run -v --timeout 5m
+
+ - id: with-config
+ desc: Run golangci-lint with a specific config file
+ type: run
+ shell:
+ pwd: pwd
+ gopath: go env GOPATH
+ gocache: go env GOCACHE
+ opts:
+ - name: config
+ prompt: Please enter the path to the config file
+ required: true
+ cmd: >
+ --rm
+ -v {{sh "pwd"}}:/app
+ -v {{sh "gopath"}}/pkg:/go/pkg
+ -v {{sh "gocache"}}:/cache/go
+ --mount type=bind,source={{sh "pwd"}}/{{opt "config"}},target=/.golangci.yml
+ -e GOFLAGS=-buildvcs=false
+ -e GOCACHE=/cache/go
+ -e GOLANGCI_LINT_CACHE=/cache/go
+ -w /app
+ {{.Ref}}
+ golangci-lint run -v -c /.golangci.yml --timeout 5m
diff --git a/examples/hello/README.md b/examples/hello/README.md
new file mode 100644
index 0000000..fdd08e0
--- /dev/null
+++ b/examples/hello/README.md
@@ -0,0 +1,43 @@
+# docker runx - hello example
+
+This is a simple example of `docker runx` usage.
+
+The main idea is to use an `alpine` image and create two actions:
+- one, `user` that will get the user name from the environment variable
+- the other, `ask` that will ask the user for its name
+
+## Creation of the image
+
+This `README.md` file will be used as the documentation for the image.
+
+The [`runx.yaml`](runx.yaml) file contains the definition of the actions.
+
+```
+$ docker runx decorate alpine --tag NAMESPACE/REPOSITORY
+```
+
+## Usage
+
+### Print this file
+
+```
+$ docker runx NAMESPACE/REPOSITORY --docs
+```
+
+### Run the `user` action
+
+```
+$ docker runx NAMESPACE/REPOSITORY user
+```
+
+### Run the `ask` action
+
+```
+$ docker runx NAMESPACE/REPOSITORY ask
+```
+
+You can also provide the user name as an argument:
+
+```
+$ docker runx NAMESPACE/REPOSITORY ask --opt name=John
+```
diff --git a/examples/hello/runx.yaml b/examples/hello/runx.yaml
new file mode 100644
index 0000000..74fe6e1
--- /dev/null
+++ b/examples/hello/runx.yaml
@@ -0,0 +1,20 @@
+actions:
+ - id: user
+ desc: Say hello to the current user
+ type: run
+ env:
+ - USER
+ shell:
+ uname: uname
+ cmd: --rm {{.Ref}} echo hello {{env "USER"}}
+
+ - id: ask
+ desc: Say hello!
+ type: run
+ opts:
+ - name: name
+ desc: User's name
+ prompt: Please enter your name
+ required: true
+ cmd: >
+ --rm {{.Ref}} echo hello {{opt "name"}}
diff --git a/examples/with-defaults/README.md b/examples/with-defaults/README.md
deleted file mode 100644
index a0d174c..0000000
--- a/examples/with-defaults/README.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Hello !
-
-If you run this image, it will be a simple `alpine` image.
-
-If you run this image using `docker runx` and by specifying the `hello` action, it will display a message.
-
-```console
-$ docker runx hello
-```
diff --git a/examples/with-defaults/runx.yaml b/examples/with-defaults/runx.yaml
deleted file mode 100644
index 092ef54..0000000
--- a/examples/with-defaults/runx.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-actions:
- - id: hello
- type: run
- cmd: --rm {{.Ref}} echo hello