docs(config): add Deploy Quick Reference to CLAUDE.md and surface wheels_deploy MCP tool

Author: bpamiri

CLAUDE.md

@@ -738,6 +738,88 @@ wheels jobs monitor                        # live dashboard
 
 Requires migration: `20260221000001_createwheels_jobs_table.cfc`. Run with `wheels dbmigrate latest`.
 
+## Deploy Quick Reference
+
+`wheels deploy` ships your Dockerized Wheels app to production Linux servers via SSH. Ported from Basecamp Kamal's developer CLI — same `config/deploy.yml` schema, same on-server conventions (container names, labels, network, lock path), invokes the same `kamal-proxy` Go binary for zero-downtime rollover. No Ruby runtime required.
+
+    wheels deploy init                     # scaffold config/deploy.yml + .kamal/secrets
+    wheels deploy setup                    # one-time server bootstrap + first deploy
+    wheels deploy                          # rolling deploy
+    wheels deploy --dry-run                # print commands without executing
+    wheels deploy rollback v1              # roll back to a previous version
+    wheels deploy config                   # print resolved config as YAML
+    wheels deploy version                  # show Kamal version this port mirrors
+
+### Subcommands
+
+```cfm
+wheels deploy app <verb>         // boot/start/stop/details/containers/images/logs/live/maintenance/remove
+wheels deploy proxy <verb>       // boot/reboot/start/stop/restart/details/logs/remove
+wheels deploy accessory <verb>   // boot/reboot/start/stop/restart/details/logs/remove (sidecars: db/redis/search)
+wheels deploy build <verb>       // deliver/push/pull/create/remove/details/dev
+wheels deploy registry <verb>    // setup/login/logout/remove
+wheels deploy server <verb>      // exec/bootstrap
+wheels deploy prune <verb>       // all/images/containers [--keep=N]
+wheels deploy lock <verb>        // acquire/release/status (manual — normal deploys auto-lock)
+wheels deploy secrets <verb>     // fetch/extract/print (adapters: op/bitwarden/aws/lastpass/doppler)
+wheels deploy audit              // tail /tmp/kamal-audit.log on each server
+wheels deploy details            // aggregate app + proxy + accessory status
+wheels deploy remove --confirm   // teardown all app/proxy/accessory containers
+wheels deploy docs [section]     // in-terminal config reference
+```
+
+### On-server parity contract (byte-compatible with Ruby Kamal)
+
+- Container names: `<service>-<role>-<version>`
+- Labels: `service=`, `role=`, `destination=`, `version=`
+- Docker network: `kamal`
+- Lock file: `/tmp/kamal_deploy_lock_<service>`
+- Proxy config: `/home/<user>/.config/kamal-proxy/`
+- Hook env prefix: `KAMAL_*` (never `WHEELS_*` — user hooks migrate unchanged)
+
+A server managed by Ruby Kamal can be taken over by `wheels deploy` without cleanup.
+
+### Architecture
+
+```
+cli/lucli/services/deploy/
+├── cli/*.cfc             DeployMainCli + Deploy<App|Proxy|Accessory|Build|Registry|Server|Prune|Lock|Secrets>Cli
+├── commands/*.cfc        Base + Docker/App/Proxy/Builder/Registry/Auditor/Lock/Hook/Accessory/PruneCommands
+├── config/*.cfc          Config + Role/Env/Builder/Proxy/Registry/Ssh/Accessory/Validator/ConfigLoader
+├── lib/*.cfc             JarLoader/Mustache/Yaml/SshClient/SshPool/FakeSshPool/Output/SecretResolver
+└── secrets/*.cfc         BaseAdapter + OnePassword/Bitwarden/AwsSecrets/LastPass/Doppler adapters
+
+cli/lucli/lib/deploy/*.jar  jmustache, snakeyaml, sshj + BouncyCastle transitives (URLClassLoader-isolated)
+cli/lucli/templates/deploy/ Mustache templates for `wheels deploy init` output
+```
+
+Commands-are-strings invariant: every `*Commands.cfc` method returns a shell-command string; only `*Cli.cfc` and the orchestrator execute them. That's why `--dry-run` is trivial and unit tests run without network.
+
+### Critical gotchas
+
+1. **Kamal-compatible schema, ONE divergence.** ERB in `deploy.yml` is NOT supported. Use the restricted Mustache context `{{env.FOO}}`, `{{destination}}`, `{{hostname}}` instead. Everything else in `config/deploy.yml` is byte-identical to Kamal 2.4.0.
+2. **Hook env prefix is `KAMAL_`, not `WHEELS_`.** This is deliberate — it means Ruby Kamal users' existing `.kamal/hooks/` scripts work unchanged.
+3. **`app live` / `app maintenance` use a marker file** (`/tmp/kamal-maintenance-<svc>`) rather than kamal-proxy native maintenance mode. Phase 2 simplification; Phase 3 follow-up will align with Kamal's proxy-native semantics.
+4. **`wheels deploy remove` is destructive and requires `--confirm`.** Bare `wheels deploy remove` throws without touching anything.
+5. **Lucee reserved scope names in subagent-authored deploy code.** `client`, `session`, `application` — use `ssh`/`sc`, `sess`, `app` instead. Bit us multiple times during the port.
+6. **No `--dry-run` flag in Ruby Kamal 2.8.2.** The `tools/deploy-config-diff.sh` harness compares config-layer output only. Byte-identical command-string parity is aspirational; see `tools/deploy-dry-run-diff.sh` for the plan.
+
+### Testing
+
+`cli/lucli/tests/specs/deploy/` extends `wheels.wheelstest.system.BaseSpec`. Run with:
+
+    bash tools/test-cli-local.sh
+
+Fixtures at `cli/lucli/tests/_fixtures/deploy/configs/` (`minimal.yml`, `full.yml`, `with-accessories.yml`, `invalid/*.yml`). `FakeSshPool.cfc` records every command for offline assertions; no sshd needed for unit tests. `SshClientSpec` + `SshPoolSpec` exercise real SSH via the fixture at `cli/lucli/tests/_fixtures/deploy/sshd/` (brought up by `tools/deploy-sshd-up.sh`).
+
+### Reference docs
+
+- User guides: `docs/src/working-with-wheels/deployment/` (first-deploy, config-reference, accessories, secrets, hooks, migrating-from-kamal)
+- Per-verb CLI reference: `docs/src/command-line-tools/commands/deploy/`
+- Design spec: `docs/superpowers/specs/2026-04-20-wheels-deploy-kamal-port-design.md`
+- Implementation plan: `docs/superpowers/plans/2026-04-20-wheels-deploy-kamal-port.md`
+- Retrospective: `docs/superpowers/plans/2026-04-21-phase1-retrospective.md`
+
 ## Server-Sent Events (SSE) Quick Reference
 
 ```cfm
@@ -874,7 +956,7 @@ The project name is **Wheels** (not "CFWheels"). The rebrand happened at v3.0. A
 
 Or run `wheels mcp setup` to generate `.mcp.json` + `.opencode.json` automatically.
 
-Tools are auto-discovered from `cli/lucli/Module.cfc` public functions, prefixed with the module name (`wheels_generate`, `wheels_migrate`, `wheels_test`, `wheels_reload`, `wheels_seed`, `wheels_analyze`, `wheels_validate`, `wheels_routes`, `wheels_info`, `wheels_destroy`, `wheels_doctor`, `wheels_stats`, `wheels_notes`, `wheels_db`, `wheels_upgrade`, `wheels_create`). CLI-only tools (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) are hidden from MCP `tools/list` via `mcpHiddenTools()`.
+Tools are auto-discovered from `cli/lucli/Module.cfc` public functions, prefixed with the module name (`wheels_generate`, `wheels_migrate`, `wheels_test`, `wheels_reload`, `wheels_seed`, `wheels_analyze`, `wheels_validate`, `wheels_routes`, `wheels_info`, `wheels_destroy`, `wheels_doctor`, `wheels_stats`, `wheels_notes`, `wheels_db`, `wheels_upgrade`, `wheels_create`, `wheels_deploy`). CLI-only tools (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) are hidden from MCP `tools/list` via `mcpHiddenTools()`.
 
 Workflow orchestration (multi-step planning, feature development) is not a framework concern — use your preferred Claude Code plugin (Superpowers, feature-dev, etc.). The framework ships deterministic Wheels operations via MCP; the model orchestrates.