docs(cli): describe deploy build, logs and prune as they now work

web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/index.mdx

@@ -31,10 +31,10 @@ App container lifecycle. Every verb targets containers labelled with the current
 | Flag | Description |
 |------|-------------|
 | `--release=<v>` | Required for boot/start/stop/remove. Optional for details. Ignored by containers/images/logs/live/maintenance. |
-| `--role=<name>` | Limit to one role. Default: all roles. |
+| `--role=<name>` | Limit to one role. Default: all roles. A name that `deploy.yml` doesn't define stops the command with an error that lists the roles it does define. |
 | `--destination=<name>` | Overlay destination config. |
 | `--dry-run` | Print commands without executing. |
 
 <Aside type="note" title="--release and --version">
-`--release=<v>` is the documented form. `--version=<v>` is accepted as an alias and reaches deploy dispatch on the current CLI runtime ([#2674](https://github.com/wheels-dev/wheels/issues/2674), closed). Purely numeric values such as `--release=1` work ([#3111](https://github.com/wheels-dev/wheels/issues/3111), closed).
+`--release=<v>` is the documented form; the space form `--release <v>` works too. `--version=<v>` is accepted as an alias and reaches deploy dispatch on the current CLI runtime ([#2674](https://github.com/wheels-dev/wheels/issues/2674), closed). Purely numeric values such as `--release=1` work ([#3111](https://github.com/wheels-dev/wheels/issues/3111), closed).
 </Aside>

web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/logs.mdx

@@ -7,7 +7,7 @@ sidebar:
   order: 7
 ---
 
-`docker logs` fanned out across every host, prefixed by host. Follows and per-container targeting supported.
+`docker logs` fanned out across every host, prefixed by host. Reads each role's newest container by default; `--container` picks one by name.
 
 ## Synopsis
 
@@ -21,22 +21,30 @@ wheels deploy app logs [--tail=<N>] [--follow] [--container=<name>] [--role=<nam
 |------|-------------|
 | `--tail=<N>` | Trailing lines per host. Default 100. |
 | `--follow` | `docker logs --follow`. Leaves the connection open; Ctrl-C to stop. |
-| `--container=<name>` | Container to read logs from. Pass it in practice: without it the emitted `docker logs` command has no container argument, and Docker rejects it. |
-| `--role=<name>` | Limit to one role. |
+| `--container=<name>` | Read this container's logs instead of each role's newest running container. |
+| `--role=<name>` | Limit to one role. A name that `deploy.yml` doesn't define stops the command with an error listing the roles it does define. |
 | `--destination=<name>` | Overlay destination config. |
 
 `--release` is not required.
 
 ## Behavior
 
-Emits `docker logs --tail <N> [--follow] [<container>]` per host in the targeted role(s). Output is line-buffered and prefixed with `[<host>]`.
+Without `--container`, each host in the targeted role(s) reads the role's newest running container:
+
+```txt
+docker ps --latest --quiet --filter 'label=service=<service>' [--filter 'label=role=<role>' --filter 'label=destination=<destination>'] | xargs -r docker logs --tail <N> [--follow]
+```
+
+The role and destination filters are added for each role the command runs for, which is every targeted role. Without `--destination`, the destination filter is empty (`label=destination=`) and matches containers deployed without one.
+
+With `--container=<name>`, it runs `docker logs --tail <N> [--follow] <name>`, with the name shell-quoted. Output is line-buffered and prefixed with `[<host>]`.
 
 Under `--follow`, the command fans out in parallel and stays running until interrupted.
 
 ## Examples
 
 ```bash title="illustrative"
-wheels deploy app logs --container=myapp-web-abc1234
-wheels deploy app logs --container=myapp-web-abc1234 --tail=500
-wheels deploy app logs --container=myapp-web-abc1234 --follow --role=web
+wheels deploy app logs
+wheels deploy app logs --tail=500 --role=web
+wheels deploy app logs --container=myapp-web-abc1234 --follow
 ```

web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/create.mdx

@@ -24,11 +24,17 @@ wheels deploy build create [--destination=<name>] [--dry-run]
 
 ## When to run
 
-Only when you want a named `kamal-<service>` buildx builder on the control machine, for example to select it yourself with `docker buildx use kamal-<service>`. `build push` and `wheels deploy` do not need it.
+Once, before the first build, when `builder.remote` is set. [`build push`](../push/) then builds with `--builder kamal-<service>`, so that builder must exist. Without `builder.remote`, `build push` uses your current default builder and doesn't need this.
 
 ## Behavior
 
-Emits `docker buildx create --name kamal-<service> --driver=docker-container` on the control machine. The builder is not selected with `--use`, and `build push` / `wheels deploy` do not pass `--builder`, so they build with your current default builder.
+Emits `docker buildx create --name kamal-<service> --driver=docker-container` on the control machine. When `builder.remote` is set, its endpoint is passed too, so the builder runs on that host:
+
+```txt
+[local] docker buildx create --name kamal-ddapp --driver=docker-container 'ssh://deploy@192.0.2.50'
+```
+
+The builder is not selected with `--use`; `build push` names it with `--builder` instead.
 
 ## Example
 

web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/push.mdx

@@ -25,9 +25,23 @@ wheels deploy build push [--version=<v>] [--destination=<name>] [--dry-run]
 
 ## Behavior
 
-Emits one command: `docker buildx build --push --tag <image>:<version> --file <dockerfile> <context>`, using `builder.dockerfile` (default `Dockerfile`) and `builder.context` (default `.`). The image is prefixed with `registry.server` unless the server is `docker.io`.
+Emits one command:
 
-`builder.arch`, `builder.args` and `builder.remote` are not applied: the command has no `--platform`, `--build-arg` or `--builder` option, so it always builds on the control machine with the current default buildx builder.
+```txt
+docker buildx build --push --platform linux/<arch>[,linux/<arch>...] [--builder kamal-<service>] --label service=<service> [--build-arg KEY=value ...] --tag <image>:<version> --file <dockerfile> <context>
+```
+
+- **`--file` and the context** come from `builder.dockerfile` (default `Dockerfile`) and `builder.context` (default `.`). The image is prefixed with `registry.server` unless the server is `docker.io`.
+- **`--platform`** lists one `linux/<arch>` per entry in `builder.arch`, which takes a list or a comma-separated string and defaults to `amd64`. An entry that already contains `/` (for example `linux/arm/v7`) is used as is. An entry that isn't a plain platform name (letters, digits, `.`, `_`, `/` and `-` only) stops the command with `Wheels.Deploy.InvalidInput`.
+- **`--builder kamal-<service>`** is added when `builder.remote` is set. That builder is the one [`wheels deploy build create`](../create/) creates on the remote host.
+- **`--build-arg`** is added once per `builder.args` entry, sorted by key.
+- **`--label service=<service>`** is always set. [`wheels deploy prune images`](../../prune/images/) relies on it to find the service's images; images built before this label was added carry none.
+
+With `--dry-run`, for a `builder` of `arch: amd64,arm64`, `remote: ssh://deploy@192.0.2.50` and `args: {ALPHA: first, ZETA: last}`:
+
+```txt
+[local] docker buildx build --push --platform linux/amd64,linux/arm64 --builder kamal-ddapp --label 'service=ddapp' --build-arg 'ALPHA=first' --build-arg 'ZETA=last' --tag 'ddapp/web:v3' --file 'Dockerfile' '.'
+```
 
 ## Example
 

web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/images.mdx

@@ -7,7 +7,7 @@ sidebar:
   order: 2
 ---
 
-Prune dangling images labelled with the service on every host.
+Remove the service's unused images on every host.
 
 ## Synopsis
 
@@ -24,7 +24,11 @@ wheels deploy prune images [--destination=<name>] [--dry-run]
 
 ## Behavior
 
-Per host, emits `docker image prune -f --filter label=service=<service>`. Without `-a`, `docker image prune` removes only dangling (untagged) images, and only those carrying a `service=<service>` label. The `Dockerfile` that `wheels deploy init` generates sets no such label and the build adds none, so on a default setup this removes nothing; tagged images of old versions stay on the host.
+Per host, emits `docker image prune --all --force --filter label=service=<service>`. It removes every image of the service that no container uses, tagged images of old versions included. Images used by any container, running or stopped, are kept.
+
+Rollback isn't affected while a version's container still exists: [`wheels deploy rollback <version>`](../../rollback/) restarts that version's existing container (`docker start`) and doesn't pull, and an image in use by a stopped container is kept. Once [`prune containers`](../containers/) has removed a version's container, the next `prune images` removes its image too. Going back to that version then means deploying it again with `wheels deploy --version=<version> --skip-push`, which pulls that version's image from the registry instead of building the current checkout.
+
+The label comes from [`wheels deploy build push`](../../build/push/), which sets `service=<service>` on every image it builds. Images built before that label was added carry none, so this command doesn't remove them; remove those once with `docker image rm`.
 
 ## Example
 

web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/index.mdx

@@ -13,8 +13,8 @@ Disk cleanup. Three verbs with increasing scope.
 
 | Verb | Removes |
 |------|---------|
-| [`all`](/v4-2-0/command-line-tools/commands/deploy/prune/all/) | Old stopped containers + dangling service-labelled images. |
-| [`images`](/v4-2-0/command-line-tools/commands/deploy/prune/images/) | Dangling service-labelled images only. |
+| [`all`](/v4-2-0/command-line-tools/commands/deploy/prune/all/) | Old stopped containers + the service's unused images. |
+| [`images`](/v4-2-0/command-line-tools/commands/deploy/prune/images/) | The service's unused images only. |
 | [`containers`](/v4-2-0/command-line-tools/commands/deploy/prune/containers/) | Old stopped containers only. |
 
 ## Retention policy