docs(config): add user-facing deployment documentation for wheels deploy

Author: bpamiri

docs/src/SUMMARY.md

@@ -110,6 +110,77 @@
     * [wheels jobs retry](command-line-tools/commands/jobs/jobs-retry.md)
     * [wheels jobs purge](command-line-tools/commands/jobs/jobs-purge.md)
     * [wheels jobs monitor](command-line-tools/commands/jobs/jobs-monitor.md)
+  * Deploy Commands
+    * [wheels deploy](command-line-tools/commands/deploy/index.md)
+    * Top-level verbs
+      * [deploy](command-line-tools/commands/deploy/deploy.md)
+      * [redeploy](command-line-tools/commands/deploy/redeploy.md)
+      * [rollback](command-line-tools/commands/deploy/rollback.md)
+      * [setup](command-line-tools/commands/deploy/setup.md)
+      * [init](command-line-tools/commands/deploy/init.md)
+      * [config](command-line-tools/commands/deploy/config.md)
+      * [version](command-line-tools/commands/deploy/version.md)
+      * [audit](command-line-tools/commands/deploy/audit.md)
+      * [details](command-line-tools/commands/deploy/details.md)
+      * [docs](command-line-tools/commands/deploy/docs.md)
+      * [remove](command-line-tools/commands/deploy/remove.md)
+    * [app](command-line-tools/commands/deploy/app/index.md)
+      * [app boot](command-line-tools/commands/deploy/app/boot.md)
+      * [app start](command-line-tools/commands/deploy/app/start.md)
+      * [app stop](command-line-tools/commands/deploy/app/stop.md)
+      * [app details](command-line-tools/commands/deploy/app/details.md)
+      * [app containers](command-line-tools/commands/deploy/app/containers.md)
+      * [app images](command-line-tools/commands/deploy/app/images.md)
+      * [app logs](command-line-tools/commands/deploy/app/logs.md)
+      * [app live](command-line-tools/commands/deploy/app/live.md)
+      * [app maintenance](command-line-tools/commands/deploy/app/maintenance.md)
+      * [app remove](command-line-tools/commands/deploy/app/remove.md)
+    * [proxy](command-line-tools/commands/deploy/proxy/index.md)
+      * [proxy boot](command-line-tools/commands/deploy/proxy/boot.md)
+      * [proxy reboot](command-line-tools/commands/deploy/proxy/reboot.md)
+      * [proxy start](command-line-tools/commands/deploy/proxy/start.md)
+      * [proxy stop](command-line-tools/commands/deploy/proxy/stop.md)
+      * [proxy restart](command-line-tools/commands/deploy/proxy/restart.md)
+      * [proxy details](command-line-tools/commands/deploy/proxy/details.md)
+      * [proxy logs](command-line-tools/commands/deploy/proxy/logs.md)
+      * [proxy remove](command-line-tools/commands/deploy/proxy/remove.md)
+    * [accessory](command-line-tools/commands/deploy/accessory/index.md)
+      * [accessory boot](command-line-tools/commands/deploy/accessory/boot.md)
+      * [accessory reboot](command-line-tools/commands/deploy/accessory/reboot.md)
+      * [accessory start](command-line-tools/commands/deploy/accessory/start.md)
+      * [accessory stop](command-line-tools/commands/deploy/accessory/stop.md)
+      * [accessory restart](command-line-tools/commands/deploy/accessory/restart.md)
+      * [accessory details](command-line-tools/commands/deploy/accessory/details.md)
+      * [accessory logs](command-line-tools/commands/deploy/accessory/logs.md)
+      * [accessory remove](command-line-tools/commands/deploy/accessory/remove.md)
+    * [build](command-line-tools/commands/deploy/build/index.md)
+      * [build deliver](command-line-tools/commands/deploy/build/deliver.md)
+      * [build push](command-line-tools/commands/deploy/build/push.md)
+      * [build pull](command-line-tools/commands/deploy/build/pull.md)
+      * [build create](command-line-tools/commands/deploy/build/create.md)
+      * [build remove](command-line-tools/commands/deploy/build/remove.md)
+      * [build details](command-line-tools/commands/deploy/build/details.md)
+      * [build dev](command-line-tools/commands/deploy/build/dev.md)
+    * [registry](command-line-tools/commands/deploy/registry/index.md)
+      * [registry setup](command-line-tools/commands/deploy/registry/setup.md)
+      * [registry login](command-line-tools/commands/deploy/registry/login.md)
+      * [registry logout](command-line-tools/commands/deploy/registry/logout.md)
+      * [registry remove](command-line-tools/commands/deploy/registry/remove.md)
+    * [server](command-line-tools/commands/deploy/server/index.md)
+      * [server exec](command-line-tools/commands/deploy/server/exec.md)
+      * [server bootstrap](command-line-tools/commands/deploy/server/bootstrap.md)
+    * [prune](command-line-tools/commands/deploy/prune/index.md)
+      * [prune all](command-line-tools/commands/deploy/prune/all.md)
+      * [prune images](command-line-tools/commands/deploy/prune/images.md)
+      * [prune containers](command-line-tools/commands/deploy/prune/containers.md)
+    * [lock](command-line-tools/commands/deploy/lock/index.md)
+      * [lock acquire](command-line-tools/commands/deploy/lock/acquire.md)
+      * [lock release](command-line-tools/commands/deploy/lock/release.md)
+      * [lock status](command-line-tools/commands/deploy/lock/status.md)
+    * [secrets](command-line-tools/commands/deploy/secrets/index.md)
+      * [secrets fetch](command-line-tools/commands/deploy/secrets/fetch.md)
+      * [secrets extract](command-line-tools/commands/deploy/secrets/extract.md)
+      * [secrets print](command-line-tools/commands/deploy/secrets/print.md)
 * CLI Development Guides
   * [Configuration Management](command-line-tools/configuration.md)
   * [Creating Commands](command-line-tools/cli-guides/creating-commands.md)
@@ -135,6 +206,13 @@
 * [Contributing to Wheels macOS Installer](working-with-wheels/contributing-to-wheels-macos-installer.md)
 * [Background Jobs](working-with-wheels/background-jobs.md)
 * [Dependency Injection](working-with-wheels/dependency-injection.md)
+* [Deployment](working-with-wheels/deployment/index.md)
+  * [Your First Deploy](working-with-wheels/deployment/first-deploy.md)
+  * [deploy.yml Reference](working-with-wheels/deployment/config-reference.md)
+  * [Accessories](working-with-wheels/deployment/accessories.md)
+  * [Secrets](working-with-wheels/deployment/secrets.md)
+  * [Hooks](working-with-wheels/deployment/hooks.md)
+  * [Migrating from Kamal](working-with-wheels/deployment/migrating-from-kamal.md)
 * [Submitting Pull Requests](working-with-wheels/submitting-pull-requests.md)
 * [Documenting your Code](working-with-wheels/documenting-your-code.md)
 

docs/src/command-line-tools/commands/deploy/accessory/boot.md

@@ -0,0 +1,30 @@
+# `wheels deploy accessory boot`
+
+First-time install of one (or all) sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory boot <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Runs `docker run` for the accessory — creates the container, mounts its volumes and files, sets env, and attaches it to the `kamal` Docker network. Pass `all` to boot every accessory defined in `deploy.yml`.
+
+Idempotent on the container name — calling `boot` when the accessory is already running is a no-op.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory boot db
+wheels deploy accessory boot redis
+wheels deploy accessory boot all
+```

docs/src/command-line-tools/commands/deploy/accessory/details.md

@@ -0,0 +1,27 @@
+# `wheels deploy accessory details`
+
+Show status for a sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory details <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Runs `docker ps` filtered to the accessory's container name. With `all`, shows every accessory across every host.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory details db
+wheels deploy accessory details all
+```

docs/src/command-line-tools/commands/deploy/accessory/index.md

@@ -0,0 +1,20 @@
+# `wheels deploy accessory`
+
+Lifecycle commands for sidecar containers (databases, caches, queues).
+
+## Verbs
+
+| Verb | Summary |
+|------|---------|
+| [`boot`](./boot.md) | First-time install of the accessory. |
+| [`reboot`](./reboot.md) | Stop, remove, and re-install. |
+| [`start`](./start.md) | Start a stopped accessory. |
+| [`stop`](./stop.md) | Stop a running accessory. |
+| [`restart`](./restart.md) | Stop then start. |
+| [`details`](./details.md) | `docker ps` for the accessory. |
+| [`logs`](./logs.md) | Tail accessory logs. |
+| [`remove`](./remove.md) | Tear down the accessory container. |
+
+Every verb takes a positional accessory name — one of the keys under `accessories:` in `deploy.yml`, or the literal `all` to fan out across every accessory.
+
+Accessories are decoupled from the main deploy rhythm — they run their own lifecycle, on their own hosts, with their own volumes. See the [accessories guide](../../../../working-with-wheels/deployment/accessories.md) for when to use them (and when to reach for managed infrastructure instead).

docs/src/command-line-tools/commands/deploy/accessory/logs.md

@@ -0,0 +1,29 @@
+# `wheels deploy accessory logs`
+
+Tail logs from a sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory logs <name|all> [--tail=<N>] [--follow] [--destination=<name>]
+```
+
+## Description
+
+Runs `docker logs` on the accessory container. With `all`, logs every accessory in sequence.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--tail=<N>` | Lines. Defaults to 100. |
+| `--follow` | Stream logs (long-lived SSH connection). |
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory logs db --tail=500
+wheels deploy accessory logs redis --follow
+```

docs/src/command-line-tools/commands/deploy/accessory/reboot.md

@@ -0,0 +1,28 @@
+# `wheels deploy accessory reboot`
+
+Stop, remove, and re-install a sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory reboot <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Recreates the accessory from the current `deploy.yml` definition. Useful after bumping an image tag or changing env/volumes. **Named volumes persist** — data isn't touched. Bind mounts also persist (they are on the host filesystem).
+
+For an image upgrade of Postgres, you generally don't want `reboot` — run a tested upgrade path. For Redis and stateless caches, `reboot` is typically safe.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory reboot redis
+```

docs/src/command-line-tools/commands/deploy/accessory/remove.md

@@ -0,0 +1,29 @@
+# `wheels deploy accessory remove`
+
+Tear down a sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory remove <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Runs `docker rm -f` on the accessory container. **Named volumes are preserved** — accessory data stored in a named Docker volume survives a `remove` and will be re-attached on the next `boot`. Anonymous volumes are gone.
+
+To delete accessory data too, `ssh` to the host and `docker volume rm <volume-name>` explicitly.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory remove redis
+wheels deploy accessory remove all
+```

docs/src/command-line-tools/commands/deploy/accessory/restart.md

@@ -0,0 +1,26 @@
+# `wheels deploy accessory restart`
+
+Stop then start a sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory restart <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Graceful `docker restart` of the accessory. The container identity, volumes, and env are preserved. Use to pick up changes delivered via a `SIGHUP`-style config reload.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory restart redis
+```

docs/src/command-line-tools/commands/deploy/accessory/start.md

@@ -0,0 +1,26 @@
+# `wheels deploy accessory start`
+
+Start a stopped sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory start <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Runs `docker start` on the accessory container. The container must already exist — use `boot` to create one.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory start db
+```

docs/src/command-line-tools/commands/deploy/accessory/stop.md

@@ -0,0 +1,26 @@
+# `wheels deploy accessory stop`
+
+Stop a running sidecar container.
+
+## Synopsis
+
+```bash
+wheels deploy accessory stop <name|all> [--destination=<name>] [--dry-run]
+```
+
+## Description
+
+Runs `docker stop` on the accessory container. Data in volumes is preserved. If the app depends on the accessory, the app will begin erroring immediately — use for maintenance windows, not hotfixes.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--destination=<name>` | Per-destination overlay. |
+| `--dry-run` | Print, don't execute. |
+
+## Examples
+
+```bash
+wheels deploy accessory stop redis
+```