[bpamiri]

Summary

This updates the deploy command reference to the behaviour of #4423 (builder options, app logs, prune images) and #4424 (space-form values, unknown --role). #4404 had documented the behaviour from before those fixes.

• build push:
  • --platform comes from builder.arch: a list or a comma-separated string, defaulting to amd64. An entry containing / is used as is, and anything that isn't a plain platform name is rejected with Wheels.Deploy.InvalidInput.
  • --builder kamal-<service> is added when builder.remote is set.
  • One --build-arg per builder.args entry, sorted by key.
  • The service label is set on every image, with a --dry-run example.
• build create: passes builder.remote's endpoint, so the builder runs on that host. Run it once when remote builds are configured.
• app logs: without --container, each role's newest running container (docker ps --latest ... | xargs -r docker logs); --container is shell-quoted. The examples no longer need --container.
• prune images (and the rows in the prune index): docker image prune --all --force --filter label=service=<service>. It removes the service's unused images, tagged ones included. Images built before the label was added carry none.
• app common flags: an unknown --role is an error that lists the defined roles; --release also takes the space form.

Verification

• Every command and example on these pages was run with --dry-run, using a CLI built from develop (fix(cli): deploy build push honours the builder block; logs and prune images work #4423 and fix(cli): deploy binds space-form values, rejects an unknown role, prints whole ports #4424 merged) against a scratch app with two roles and a builder section. Checked: list and comma-string arch, an invalid arch, defaults with no builder, --tail, --follow, a quoted --container, and an unknown role on boot, stop, details and logs.
• pnpm build (guides): 852 pages.
• pnpm verify:docs on the deploy pages: 1 passed, 0 failed.

🤖 Generated with Claude Code

[bpamiri]

rev1-r3 review @ 38d4635: content APPROVE (final pending PR CI)

I checked all six pages against the merged code for #4423 (BuilderCommands, Builder.arch(), AppCommands.logs, PruneCommands.images) and #4424 ($assertKnownRole, space-form flag values):

• build push: the --platform / --builder / --label / --build-arg order matches push(). Build args are sorted by key, and the builder.arch rules match the validation (/-containing entries pass through; other characters throw Wheels.Deploy.InvalidInput). The dry-run sample has the same quoting shellEscape produces.
• build create: the remote endpoint is quoted, and there is still no --use. The "run once before the first build when builder.remote is set" guidance is correct, because push now names the builder.
• app logs: the default now uses the newest-container pipeline, --container is quoted, and the old "Docker rejects it" caveat is removed. That's correct.
• prune images / prune index: --all --force and the label dependency are described correctly, and so is the note about images built before the label was added.
• app index: both the unknown-role error and the --release <v> space form are correct.

Two optional nits:

• prune/images: add one line saying that pruning removes older versions' images too, so a later wheels deploy rollback <version> to one of them has to pull it from the registry again. Operators who expect rollback to be instant will want to know.
• app/logs: the pipeline sample shows the role and destination filters unconditionally. In the code they're added only when a role or destination applies, so wrap them in [...] as the push synopsis does. The real output also single-quotes each label=… filter, unlike the sample.

Gate: docs-only, so PR CI (including the guides build). I'll post the final when it's green.

[bpamiri]

rev1-r3 review @ 88e4a2a: content APPROVE (final pending PR CI)

Both nits are folded in, and the rollback note corrects my premise. Rollback runs docker start on the version's existing container and never pulls, so prune images affects it only once prune containers has removed that container. The recovery path given, wheels deploy --version=<v> --skip-push (pull, no rebuild), is the right one, and it's correct to steer readers away from plain --version, which would rebuild the current checkout. The links ../../rollback/ and ../containers/ resolve to existing pages.

The logs sample now marks the role and destination filters optional and quotes each filter, and it explains the empty-destination case.

Gate: PR CI. I'll post the final when it's green.

[bpamiri]

rev1-r3 delta check @ 454c3fc: APPROVE. This is a develop merge (bringing in #4444 and #4447). The PR's changed lines against develop are identical to the approved 88e4a2a: the same six deploy pages, +49/−17. The final follows when PR CI is green.

[bpamiri]

rev1-r3 review @ e3dca19: APPROVE (final)

The content was approved at 88e4a2a, and this head's changed lines against develop are identical to it: the six deploy pages, after the develop merge that brought in #4444, #4447 and #4451. This PR is docs only, so the gate is PR CI, which is now 20 pass / 0 fail / 0 pending, with 4 skipping, including verify (the docs harness) and the guides build and deploy.

Ready to merge.