From 6894c43e65b83536da0324a083f8a0b033a96c19 Mon Sep 17 00:00:00 2001
From: Fixture <fixture@example.com>
Date: Sat, 5 Sep 2026 15:47:19 +0900
Subject: [PATCH] docs: generate env and CLI reference tables from source

README carried a hand-written environment-variable table (12 rows, including
AGENTDESK_SERVER_PORT which the binary never reads) and a CLI Reference block
that had drifted from src/cli/args.rs (19 subcommands missing, a `--flavor dev`
value that does not exist). Both are now generated from the source tree:

- scripts/generate_env_reference.py -> docs/generated/env-reference.md
  Collects env::var / env::var_os / std::env::var literal reads, const-defined
  AGENTDESK_*/ADK_* names (including indirect env::var(CONST) reads),
  *env* helper calls, and tracing EnvFilter::from_default_env (RUST_LOG).
  Excludes tests.rs, src/**/tests/, and #[cfg(test)] modules. Sorted by name;
  one-sentence description from the nearest comment naming the variable.
- scripts/generate_cli_reference.py -> docs/generated/cli-reference.md
  Parses the clap derive items (Parser/Subcommand/Args/ValueEnum) without a
  cargo build and renders every command, nested subcommand, flag, positional,
  value-enum choices, defaults, after_help and cfg/hide notes. The unit test
  asserts the derived top-level list equals the clap snapshot test in args.rs.
- README links to both documents and keeps only a short "commonly used" list.
- scripts/ci-script-checks.sh regenerates both docs, runs their unit tests,
  and reuses the existing `git diff --exit-code` tracked-doc gate so drift
  fails the PR. docs/generated/README.md records the exception to the
  warning-only drift policy.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md                            |  102 +--
 docs/generated/README.md             |    9 +
 docs/generated/cli-reference.md      | 1209 ++++++++++++++++++++++++++
 docs/generated/env-reference.md      |  138 +++
 scripts/ci-script-checks.sh          |   16 +-
 scripts/generate_cli_reference.py    |  865 ++++++++++++++++++
 scripts/generate_env_reference.py    |  442 ++++++++++
 tests/test_generate_cli_reference.py |   92 ++
 tests/test_generate_env_reference.py |  117 +++
 9 files changed, 2914 insertions(+), 76 deletions(-)
 create mode 100644 docs/generated/cli-reference.md
 create mode 100644 docs/generated/env-reference.md
 create mode 100644 scripts/generate_cli_reference.py
 create mode 100644 scripts/generate_env_reference.py
 create mode 100644 tests/test_generate_cli_reference.py
 create mode 100644 tests/test_generate_env_reference.py

diff --git a/README.md b/README.md
index 072ed60313..50eb6424f4 100644
--- a/README.md
+++ b/README.md
@@ -446,21 +446,16 @@ AgentDesk keeps settings in multiple surfaces on purpose. The contract is per-su
 
 ### Environment Variables
 
-| Variable | Purpose |
-|----------|---------|
-| `AGENTDESK_ROOT_DIR` | Override runtime directory (default: `~/.adk/release`) |
-| `AGENTDESK_CONFIG` | Override config file path |
-| `AGENTDESK_REPO_DIR` | Override resolved AgentDesk repo path used by `git`/`gh` exec helpers |
-| `AGENTDESK_SERVER_PORT` | Override HTTP server port (default: 8791) |
-| `AGENTDESK_INSTALL_PORT` | Override the macOS installer-created config port; sandbox install roots derive a non-8791 loopback port by default |
-| `AGENTDESK_API_URL` | Override base URL the CLI client uses to reach the local API |
-| `AGENTDESK_TOKEN` | Optional Discord bot token forwarded to `dcserver` at startup. **Not** used by `discord-send*` CLI commands (those load configured bot tokens via the wizard, or require `--key`) and **not** used for `/api/*` auth — that comes from `server.auth_token` in `agentdesk.yaml` |
-| `AGENTDESK_DCSERVER_LABEL` | Override launchd service label |
-| `AGENTDESK_STATUS_INTERVAL_SECS` | Status polling interval (default: 5) |
-| `AGENTDESK_TURN_TIMEOUT_SECS` | Turn watchdog timeout in seconds (default: 3600) |
-| `AGENTDESK_HEADLESS_DISCORD_NONCE` | Opt in (`1` or `true`) to an enforced Discord nonce for trusted durable `headless_turn` outbox rows on the <=2,000-character manual/v3 inline path. Default is off. Retries of one parsed positive row ID reuse the same nonce, but Discord applies duplicate suppression only within its bounded recent-nonce retention window; this is not indefinite deduplication, and oversize attachment/chunk paths are outside this rollout. |
-| `AGENTDESK_GH_PATH` / `AGENTDESK_CODEX_PATH` / `AGENTDESK_GEMINI_PATH` | Override resolved provider/CLI binary paths |
-| `RUST_LOG` | Standard tracing filter (default: `agentdesk=info`) |
+The full list of environment variables the binary reads is generated from the
+source tree: see [docs/generated/env-reference.md](docs/generated/env-reference.md)
+(regenerate with `python3 scripts/generate_env_reference.py`; CI fails when it
+drifts). The most commonly used ones:
+
+- `AGENTDESK_ROOT_DIR` — runtime directory (default: `~/.adk/release`)
+- `AGENTDESK_CONFIG` — config file path
+- `AGENTDESK_API_URL` — base URL the CLI client uses to reach the local API
+- `AGENTDESK_TOKEN` — optional Discord bot token forwarded to `dcserver` at startup. **Not** used by `discord-send*` CLI commands and **not** used for `/api/*` auth (that comes from `server.auth_token` in `agentdesk.yaml`)
+- `RUST_LOG` — standard tracing filter (default: `agentdesk=info`)
 
 ## Customization
 
@@ -631,73 +626,30 @@ Each agent maps to a Discord channel where it receives and responds to tasks.
 
 ## CLI Reference
 
+Every subcommand, nested subcommand, flag, and positional argument is generated
+from the clap definitions in `src/cli/args.rs`: see
+[docs/generated/cli-reference.md](docs/generated/cli-reference.md) (regenerate
+with `python3 scripts/generate_cli_reference.py`; CI fails when it drifts).
+`agentdesk --help` and `agentdesk <command> --help` print the same information
+at runtime.
+
+Frequently used entry points:
+
 ```
-# Server
 agentdesk dcserver                               # Start Discord control plane
 agentdesk init                                   # Interactive setup wizard
-agentdesk reconfigure                            # Re-run setup (preserves data)
-agentdesk restart-dcserver                       # Graceful restart with crash context
-agentdesk doctor [--json] [--profile quick|deep|security]
-agentdesk doctor --fix --allow-restart           # Explicit service restart repair
-agentdesk doctor --fix --repair-sqlite-cache     # Explicit legacy SQLite cache repair
-agentdesk emit-launchd-plist --flavor release|dev [--label <LABEL>] [--output <PATH>]
-
-# Discord messaging
-agentdesk discord-sendfile <PATH> --channel <ID> --key <HASH>
-agentdesk discord-sendmessage --channel <ID> --message <TEXT>
-agentdesk discord-senddm --user <ID> --message <TEXT>
-agentdesk send --target channel:<ID> --content <TEXT> [--bot announce|notify|<provider>]
-agentdesk discord read <CHANNEL_ID> [--limit <N>] [--before <ID>] [--after <ID>]
-agentdesk monitoring start --channel <ID> --key <KEY> --description <TEXT>
-agentdesk monitoring stop --channel <ID> --key <KEY>
-
-# Review / docs / sessions
-agentdesk review-verdict --dispatch <ID> --verdict pass|improve|rework|reject|approved
-agentdesk review-decision --card <CARD_ID> --decision approve|rework|escalate|accept|dispute|dismiss|requeue|resume
-agentdesk docs [CATEGORY] [--flat]
-agentdesk force-kill --session-key <KEY> [--retry]
-
-# Kanban / dispatch / auto-queue
-agentdesk cards [--status <STATUS>]              # List kanban cards
-agentdesk card create --from-issue <NUMBER> [--status ready] [--agent <ID>] [--repo <OWNER/REPO>]
-agentdesk card status <CARD_ID|ISSUE_NUMBER> [--repo <OWNER/REPO>]
-agentdesk dispatch <ISSUE_GROUPS...> [--agent <ID>] [--concurrent <N>] [--no-activate]
-agentdesk dispatch list
-agentdesk dispatch retry <CARD_ID>
-agentdesk dispatch redispatch <CARD_ID>
-agentdesk resume <CARD_ID> [--force] [--reason <TEXT>]
-agentdesk advance <ISSUE_NUMBER>                 # Promote card to review
-agentdesk queue                                  # Auto-queue status with thread links
-agentdesk auto-queue activate [--run <ID>] [--agent <ID>] [--repo <OWNER/REPO>] [--active-only]
-agentdesk auto-queue add <CARD_ID> [--run <ID>] [--priority <N>] [--phase <N>] [--thread-group <N>] [--agent <ID>]
-agentdesk auto-queue config --max-concurrent <N> [--run <ID>] [--repo <OWNER/REPO>] [--agent <ID>]
-
-# Git / runtime / migrations
-agentdesk github-sync [--repo <OWNER/REPO>]
-agentdesk cherry-merge <BRANCH> [--close-issue]
+agentdesk doctor [--fix] [--profile quick|deep|security]
 agentdesk status                                 # Runtime health summary
-agentdesk config get                             # Read runtime config
-agentdesk config set '<JSON>'                    # Set runtime config
-agentdesk config audit [--dry-run]               # Reconcile yaml/DB drift
-agentdesk agents                                 # List agents
-agentdesk diag <AGENT_ID|CHANNEL_ID> [--json]    # Turn/session diagnostics
-agentdesk terminations [--card-id <ID>] [--dispatch-id <ID>] [--session <KEY>] [--limit <N>]
-agentdesk api GET /api/health                    # Public safe health summary
-agentdesk api GET /api/health/detail             # Authenticated/local detailed health
+agentdesk query [queue|dispatches|phase-gate]    # Queue + dispatch + phase-gate snapshot
+agentdesk send --target channel:<ID> --content <TEXT>
+agentdesk api GET /api/health                    # Call any API endpoint
 agentdesk deploy                                 # Build workspace + promote to release
-agentdesk migrate openclaw <ARGS>                # Import OpenClaw durable state
-# `migrate postgres-cutover` was retired (production cutover landed 2026-04-19) and the
-# subcommand has been removed. Restore src/cli/migrate/postgres_cutover.rs from history
-# for an explicitly approved emergency re-cutover.
-agentdesk provider-cli <SUBCOMMAND>              # Provider CLI safe-migration ops (status/plan/upgrade/canary/promote/rollback/cleanup/run/resume/smoke)
-
-# Process wrappers (internal — invoked by tmux session lifecycle)
-agentdesk tmux-wrapper                           # Claude session wrapper
-agentdesk codex-tmux-wrapper                     # Codex session wrapper
-agentdesk qwen-tmux-wrapper                      # Qwen session wrapper
-agentdesk reset-tmux                             # Kill AgentDesk-* tmux sessions and clean temp files
 ```
 
+`migrate postgres-cutover` was retired after the production cutover landed
+(2026-04-19); restore `src/cli/migrate/postgres_cutover.rs` from history only
+for an explicitly approved emergency re-cutover.
+
 ## API Overview
 
 AgentDesk exposes 270 REST API endpoints. Key groups:
diff --git a/docs/generated/README.md b/docs/generated/README.md
index a95c645a81..071be63761 100644
--- a/docs/generated/README.md
+++ b/docs/generated/README.md
@@ -30,6 +30,13 @@ about the generated report or its generator.
   source-of-truth invariants such as giant-file registry drift, missing required
   registry metadata, or top-level architecture map parse errors. Those are not
   generic generated-doc markdown freshness failures.
+- `env-reference.md` and `cli-reference.md` are the exception: README links to
+  them in place of hand-written tables, so `scripts/ci-script-checks.sh`
+  regenerates both (`scripts/generate_env_reference.py`,
+  `scripts/generate_cli_reference.py`) and fails on drift. They are cheap
+  source parsers (no cargo build) and only change when an env read site or a
+  clap definition changes, so the churn cost that motivated the warning-only
+  policy does not apply.
 - Do not re-introduce a hard PR gate solely because generated docs drifted.
 
 ## Rationale
@@ -70,6 +77,8 @@ generator, maintainability rules, baselines, or report wording.
 Commands:
 
 - `python3 scripts/generate_inventory_docs.py`
+- `python3 scripts/generate_env_reference.py`
+- `python3 scripts/generate_cli_reference.py`
 - `python3 scripts/audit_maintainability.py --write-report`
 - `python3 scripts/audit_legacy_sqlite_sunset.py --root . --format markdown --top 20`
 
diff --git a/docs/generated/cli-reference.md b/docs/generated/cli-reference.md
new file mode 100644
index 0000000000..6cb3a424a5
--- /dev/null
+++ b/docs/generated/cli-reference.md
@@ -0,0 +1,1209 @@
+# CLI Reference
+
+<!-- Generated by `python3 scripts/generate_cli_reference.py`. Do not edit by hand. -->
+
+`agentdesk` — AI agent orchestration platform
+
+Derived from the clap definitions in `src/cli/args.rs` (and the `Args` /
+`Subcommand` types it references). Commands are listed in declaration
+order, matching `agentdesk --help`. Running `agentdesk` with no
+subcommand starts the server.
+
+Regenerate with `python3 scripts/generate_cli_reference.py`; CI fails when this file drifts.
+
+- Top-level commands: 53
+- Commands including nested subcommands: 93
+
+## Global options
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--json` | flag |  | Emit machine-readable JSON instead of the human-readable text output. Accepted globally — before or after the subcommand. Commands that only ever emit JSON treat this as a no-op (never a double-encode). (accepted before or after the subcommand) |
+| `-h, --help` | flag |  | Print help |
+| `-V, --version` | flag |  | Print version |
+
+## Command index
+
+| Command | Summary | Notes |
+|---|---|---|
+| [`agentdesk dcserver`](#agentdesk-dcserver) | Start Discord bot server(s) |  |
+| [`agentdesk init`](#agentdesk-init) | Run the initial setup wizard |  |
+| [`agentdesk reconfigure`](#agentdesk-reconfigure) | Re-run the configuration wizard |  |
+| [`agentdesk emit-launchd-plist`](#agentdesk-emit-launchd-plist) | Emit a launchd plist using the canonical Rust renderer |  |
+| [`agentdesk restart-dcserver`](#agentdesk-restart-dcserver) | Restart Discord bot server(s) |  |
+| [`agentdesk discord-sendfile`](#agentdesk-discord-sendfile) | Deprecated: send a file to a Discord channel | deprecated |
+| [`agentdesk discord-sendmessage`](#agentdesk-discord-sendmessage) | Deprecated: send a message to a Discord channel | deprecated |
+| [`agentdesk discord-senddm`](#agentdesk-discord-senddm) | Deprecated: send a direct message to a Discord user | deprecated |
+| [`agentdesk send`](#agentdesk-send) | Send a routed Discord message without HTTP server dependency |  |
+| [`agentdesk send-to-agent`](#agentdesk-send-to-agent) | Send a trigger-capable agent handoff through the announce bot |  |
+| [`agentdesk review-verdict`](#agentdesk-review-verdict) | Submit a review verdict without HTTP server dependency |  |
+| [`agentdesk review-decision`](#agentdesk-review-decision) | Submit a review decision without HTTP server dependency |  |
+| [`agentdesk review-recover-target`](#agentdesk-review-recover-target) | Recover a review dispatch target commit/worktree through the API |  |
+| [`agentdesk docs`](#agentdesk-docs) | Read API documentation without HTTP server dependency |  |
+| [`agentdesk auto-queue`](#agentdesk-auto-queue) | Auto-queue operations without HTTP server dependency |  |
+| [`agentdesk auto-queue activate`](#agentdesk-auto-queue-activate) | Activate an auto-queue run |  |
+| [`agentdesk auto-queue add`](#agentdesk-auto-queue-add) | Add a card to an auto-queue run |  |
+| [`agentdesk auto-queue config`](#agentdesk-auto-queue-config) | Update auto-queue runtime config |  |
+| [`agentdesk force-kill`](#agentdesk-force-kill) | Force-kill a session without HTTP server dependency |  |
+| [`agentdesk github-sync`](#agentdesk-github-sync) | Sync GitHub issues without HTTP server dependency |  |
+| [`agentdesk monitoring`](#agentdesk-monitoring) | Monitor status commands for Discord channels |  |
+| [`agentdesk monitoring start`](#agentdesk-monitoring-start) | Register or refresh a monitor status entry |  |
+| [`agentdesk monitoring stop`](#agentdesk-monitoring-stop) | Remove a monitor status entry |  |
+| [`agentdesk intake-outbox`](#agentdesk-intake-outbox) | intake_outbox operator tools (Phase 5 of intake-node-routing) |  |
+| [`agentdesk intake-outbox dispatched-audit`](#agentdesk-intake-outbox-dispatched-audit) | List dispatched rows and their recorded audit facts without changing them. |  |
+| [`agentdesk intake-outbox dispatched-settle`](#agentdesk-intake-outbox-dispatched-settle) | Settle a dispatched handoff as unknown without creating a retry child that could redeliver an already delivered turn. |  |
+| [`agentdesk intake-outbox spawned-settle`](#agentdesk-intake-outbox-spawned-settle) | Settle a spawned handoff as unknown without creating a retry child that could redeliver an already delivered turn. |  |
+| [`agentdesk intake-outbox status`](#agentdesk-intake-outbox-status) | Show recent intake_outbox rows (newest first). |  |
+| [`agentdesk intake-outbox force-fail`](#agentdesk-intake-outbox-force-fail) | Force-fail a stuck row and re-enqueue a fresh attempt. Implements transition 12 from the design doc. |  |
+| [`agentdesk discord`](#agentdesk-discord) | Discord utility commands without HTTP server dependency |  |
+| [`agentdesk discord read`](#agentdesk-discord-read) | Read channel messages |  |
+| [`agentdesk discord category-create`](#agentdesk-discord-category-create) | Create a guild category. Idempotent (list-then-create): returns the existing category when one with the same name is already present. Not safe under concurrent invocations against the same guild. |  |
+| [`agentdesk discord channel-create`](#agentdesk-discord-channel-create) | Create a text channel under an optional category. Idempotent by (name, parent category) via list-then-create. Not safe under concurrent invocations against the same guild. |  |
+| [`agentdesk discord thread-create`](#agentdesk-discord-thread-create) | Create a thread under a text/news channel or a post under a forum/media channel. Cross-process safe and idempotent by (parent, normalized name) across active and archived public threads. |  |
+| [`agentdesk card`](#agentdesk-card) | Kanban utility commands without HTTP server dependency |  |
+| [`agentdesk card create`](#agentdesk-card-create) | Create a card from a GitHub issue |  |
+| [`agentdesk card status`](#agentdesk-card-status) | Inspect a card and connected lifecycle state |  |
+| [`agentdesk cherry-merge`](#agentdesk-cherry-merge) | Cherry-pick a worktree branch into main and optionally close its issue |  |
+| [`agentdesk tmux-wrapper`](#agentdesk-tmux-wrapper) | tmux + Claude CLI integration wrapper (Unix only) | `#[cfg(unix)]` |
+| [`agentdesk codex-tmux-wrapper`](#agentdesk-codex-tmux-wrapper) | tmux + Codex CLI integration wrapper (Unix only) | `#[cfg(unix)]` |
+| [`agentdesk qwen-tmux-wrapper`](#agentdesk-qwen-tmux-wrapper) | tmux + Qwen CLI integration wrapper (Unix only) | `#[cfg(unix)]` |
+| [`agentdesk claude-hook-relay`](#agentdesk-claude-hook-relay) | Relay Claude Code hook stdin JSON to the AgentDesk TUI hook receiver |  |
+| [`agentdesk codex-hook-relay`](#agentdesk-codex-hook-relay) | Relay Codex hook stdin JSON to the AgentDesk TUI hook receiver |  |
+| [`agentdesk reset-tmux`](#agentdesk-reset-tmux) | Kill all AgentDesk-* tmux sessions and clean temp files |  |
+| [`agentdesk ismcptool`](#agentdesk-ismcptool) | Check if MCP tool(s) are registered in .claude/settings.json |  |
+| [`agentdesk addmcptool`](#agentdesk-addmcptool) | Add MCP tool permission(s) to .claude/settings.json |  |
+| [`agentdesk install-memento-session-hook`](#agentdesk-install-memento-session-hook) | #2655: install (or refresh) the Memento `context()` SessionStart hook and a UserPromptSubmit token-pressure reminder into a Claude Code settings file. Idempotent — running twice produces the same file. |  |
+| [`agentdesk status`](#agentdesk-status) | Show server health, active sessions, and auto-queue status |  |
+| [`agentdesk cards`](#agentdesk-cards) | List kanban cards |  |
+| [`agentdesk dispatch`](#agentdesk-dispatch) | Dispatch operations |  |
+| [`agentdesk dispatch list`](#agentdesk-dispatch-list) | List active dispatches |  |
+| [`agentdesk dispatch retry`](#agentdesk-dispatch-retry) | Retry a dispatch for a card |  |
+| [`agentdesk dispatch redispatch`](#agentdesk-dispatch-redispatch) | Redispatch a card |  |
+| [`agentdesk resume`](#agentdesk-resume) | Resume a stuck kanban card from its current state |  |
+| [`agentdesk advance`](#agentdesk-advance) | Complete pending dispatch and advance to review |  |
+| [`agentdesk queue`](#agentdesk-queue) | Show auto-queue status with thread links | deprecated |
+| [`agentdesk query`](#agentdesk-query) | Unified queue + dispatch + phase-gate inspection (issue #2651). |  |
+| [`agentdesk query queue`](#agentdesk-query-queue) | Auto-queue run + entries snapshot (calls `/api/queue/status`). |  |
+| [`agentdesk query dispatches`](#agentdesk-query-dispatches) | Pending dispatches across all agents (calls `/api/dispatches/pending`). |  |
+| [`agentdesk query phase-gate`](#agentdesk-query-phase-gate) | Phase-gate catalog + active gate state (calls `/api/queue/phase-gates/catalog`). |  |
+| [`agentdesk query all`](#agentdesk-query-all) | All sections in one shot (default). |  |
+| [`agentdesk phase`](#agentdesk-phase) | Phase-gate violation snapshot (issue #2657). |  |
+| [`agentdesk phase status`](#agentdesk-phase-status) | Show current violations (default). |  |
+| [`agentdesk deploy`](#agentdesk-deploy) | Build + deploy dev + promote to release |  |
+| [`agentdesk agents`](#agentdesk-agents) | List agents and their status |  |
+| [`agentdesk diag`](#agentdesk-diag) | Show turn/session diagnostics for an agent ID or Discord channel ID |  |
+| [`agentdesk config`](#agentdesk-config) | Runtime config get/set |  |
+| [`agentdesk config get`](#agentdesk-config-get) | Get current runtime config |  |
+| [`agentdesk config set`](#agentdesk-config-set) | Set runtime config (JSON string) |  |
+| [`agentdesk config audit`](#agentdesk-config-audit) | Audit config source-of-truth drift across yaml/DB/legacy files |  |
+| [`agentdesk config sync-mcp`](#agentdesk-config-sync-mcp) | Sync runtime MCP servers into provider config files |  |
+| [`agentdesk api`](#agentdesk-api) | Call any API endpoint (curl replacement) |  |
+| [`agentdesk terminations`](#agentdesk-terminations) | List session termination events |  |
+| [`agentdesk doctor`](#agentdesk-doctor) | Environment diagnostics |  |
+| [`agentdesk migrate`](#agentdesk-migrate) | Migration helpers |  |
+| [`agentdesk migrate openclaw`](#agentdesk-migrate-openclaw) | Import OpenClaw durable state into AgentDesk |  |
+| [`agentdesk release-migrate-postgres`](#agentdesk-release-migrate-postgres) | Apply pending PostgreSQL migrations before release activation | hidden from `--help` |
+| [`agentdesk provider-cli`](#agentdesk-provider-cli) | Provider CLI safe migration management |  |
+| [`agentdesk provider-cli status`](#agentdesk-provider-cli-status) | Show current registry channels and migration states |  |
+| [`agentdesk provider-cli plan`](#agentdesk-provider-cli-plan) | Show what a migration would do without running it |  |
+| [`agentdesk provider-cli upgrade`](#agentdesk-provider-cli-upgrade) | [step] Snapshot current binary and run upgrade |  |
+| [`agentdesk provider-cli smoke`](#agentdesk-provider-cli-smoke) | [step] Run smoke checks against current or candidate binary |  |
+| [`agentdesk provider-cli canary`](#agentdesk-provider-cli-canary) | [step] Select a canary agent for the migration |  |
+| [`agentdesk provider-cli promote`](#agentdesk-provider-cli-promote) | Confirm promotion after canary passes (operator gate) |  |
+| [`agentdesk provider-cli rollback`](#agentdesk-provider-cli-rollback) | Roll back migration to previous state |  |
+| [`agentdesk provider-cli cleanup`](#agentdesk-provider-cli-cleanup) | List paths eligible for cleanup (dry-run only — deletion not implemented) |  |
+| [`agentdesk provider-cli run`](#agentdesk-provider-cli-run) | Run full migration orchestration up to CanaryActive |  |
+| [`agentdesk provider-cli resume`](#agentdesk-provider-cli-resume) | Resume migration from the current persisted state |  |
+| [`agentdesk show`](#agentdesk-show) | Inspect deterministic session-binding values (epic #2285 E1). |  |
+| [`agentdesk show session-name`](#agentdesk-show-session-name) | Print the expected tmux session name for a Discord channel. |  |
+| [`agentdesk health`](#agentdesk-health) | Show consolidated health snapshot of the current node (server status, dcserver pid, last deploy time, queue lag, Discord/disk/outbox). |  |
+| [`agentdesk machine-compare`](#agentdesk-machine-compare) | Compare release/main/dev state across every registered worker node (`mac-mini`, `mac-book`, …). Renders a side-by-side table with dcserver pid, last deploy, queue lag, and a `diff` column. |  |
+| [`agentdesk activity`](#agentdesk-activity) | Time-windowed activity report: commits / closed issues / merged PRs / deploys / incidents in a single table. Uses gh + git + AgentDesk API. |  |
+
+## Commands
+
+## `agentdesk dcserver`
+
+Start Discord bot server(s)
+
+Usage: `agentdesk dcserver [TOKEN]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `[TOKEN]` | `String` |  | Bot token (defaults to configured Discord bots or AGENTDESK_TOKEN env) |
+
+## `agentdesk init`
+
+Run the initial setup wizard
+
+Usage: `agentdesk init`
+
+## `agentdesk reconfigure`
+
+Re-run the configuration wizard
+
+Usage: `agentdesk reconfigure`
+
+## `agentdesk emit-launchd-plist`
+
+Emit a launchd plist using the canonical Rust renderer
+
+Usage: `agentdesk emit-launchd-plist [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--flavor <FLAVOR>` (required) | `release` |  | Runtime flavor to render |
+| `--label <LABEL>` | `String` |  | Override the launchd Label in the generated plist |
+| `--home <HOME>` | `PathBuf` |  | Override the home directory used in generated paths |
+| `--root-dir <ROOT_DIR>` | `PathBuf` |  | Override the runtime root directory used in generated paths |
+| `--agentdesk-bin <AGENTDESK_BIN>` | `PathBuf` |  | Override the agentdesk binary path used in ProgramArguments |
+| `--output <OUTPUT>` | `PathBuf` |  | Write the plist to this path instead of stdout |
+
+## `agentdesk restart-dcserver`
+
+Restart Discord bot server(s)
+
+Usage: `agentdesk restart-dcserver [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--report-channel-id <REPORT_CHANNEL_ID>` | `u64` |  | Discord channel ID for restart completion report |
+| `--report-provider <REPORT_PROVIDER>` | `claude`, `codex`, `gemini`, `opencode`, `qwen` |  | Provider for restart report (claude, codex, gemini, opencode, or qwen) |
+| `--report-message-id <REPORT_MESSAGE_ID>` | `u64` |  | Existing message ID to edit for restart report |
+
+## `agentdesk discord-sendfile`
+
+Deprecated: send a file to a Discord channel
+
+Notes: deprecated.
+
+Usage: `agentdesk discord-sendfile [OPTIONS] <PATH>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PATH>` | `String` |  | File path to send |
+| `--channel <CHANNEL>` (required) | `u64` |  | Discord channel ID |
+| `--key <KEY>` (required) | `String` |  | Authentication key hash |
+
+> Deprecated compatibility command. The routed `send` command does not currently accept file attachments, so keep using this command until an attachment-capable replacement is available.
+
+## `agentdesk discord-sendmessage`
+
+Deprecated: send a message to a Discord channel
+
+Notes: deprecated.
+
+Usage: `agentdesk discord-sendmessage [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--channel <CHANNEL>` (required) | `u64` |  | Discord channel ID |
+| `--message <MESSAGE>` (required) | `String` |  | Message text |
+| `--key <KEY>` | `String` |  | Authentication key hash (optional; without it, configured bot tokens are tried sequentially until one succeeds) |
+
+> Deprecated compatibility command. With `--key`, this command selects that one configured bot token; without `--key`, it tries configured bot tokens sequentially until one succeeds. For a role-mapped channel with a configured bot runtime, migrate to `agentdesk send --target channel:<id> --content <TEXT>`. Routed `send` instead requires role-map authorization and selects one `--bot` runtime (default: announce), so it does not preserve this command's token selection or sequential fallback. Keep using this compatibility command when those routing requirements do not match the current delivery.
+
+## `agentdesk discord-senddm`
+
+Deprecated: send a direct message to a Discord user
+
+Notes: deprecated.
+
+Usage: `agentdesk discord-senddm [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--user <USER>` (required) | `u64` |  | Discord user ID |
+| `--message <MESSAGE>` (required) | `String` |  | Message text |
+| `--key <KEY>` | `String` |  | Authentication key hash (optional; without it, configured bot tokens are tried sequentially until one succeeds) |
+
+> Deprecated compatibility command. With `--key`, this command selects that one configured bot token; without `--key`, it tries configured bot tokens sequentially until one succeeds. Routed `send` instead requires a role-map-authorized channel or agent target and selects one configured `--bot` runtime (default: announce); it does not preserve this token fallback, target a Discord user, or create a DM. Keep using this command until a supported replacement is available.
+
+## `agentdesk send`
+
+Send a routed Discord message without HTTP server dependency
+
+Usage: `agentdesk send [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--target <TARGET>` (required) | `String` |  | Target must be channel:<id>, channel:<name>, or agent:<roleId>; bare channel IDs/names are accepted for compatibility. |
+| `--source <SOURCE>` | `String` |  | Source label recorded in the send envelope |
+| `--bot <BOT>` | `String` |  | Preferred Discord bot name |
+| `--content <CONTENT>` (required) | `String` |  | Message body |
+
+## `agentdesk send-to-agent`
+
+Send a trigger-capable agent handoff through the announce bot
+
+Usage: `agentdesk send-to-agent [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--from <FROM_AGENT_ID>` (required) | `String` |  | Source agent id recorded in the message envelope |
+| `--to <TO_AGENT_ID>` (required) | `String` |  | Target agent id whose Discord channel binding is used |
+| `--message <MESSAGE>` (required) | `String` |  | Message body |
+| `--channel-kind <CHANNEL_KIND>` | `cc`, `cdx` | `cc` | Target channel binding kind |
+| `--no-prefix` | flag |  | Send the body without the automatic handoff prefix |
+| `--expect-reply <EXPECT_REPLY>` (required) | `true`, `false` |  | Required: `true` → 회신 필수, `false` → 회신 불필요. |
+| `--start-turn` | flag |  | #3556 — reserve a headless turn on the target mailbox instead of posting an announce message. Authoritative wake-up: exits non-zero on 409 (mailbox busy). Mutually exclusive with the default announce-post behavior. |
+
+## `agentdesk review-verdict`
+
+Submit a review verdict without HTTP server dependency
+
+Usage: `agentdesk review-verdict [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--dispatch <DISPATCH_ID>` (required) | `String` |  | Review dispatch ID |
+| `--verdict <VERDICT>` (required) | `String` |  | Verdict: pass, improve, rework, reject, approved |
+| `--notes <NOTES>` | `String` |  | Optional verdict notes |
+| `--feedback <FEEDBACK>` | `String` |  | Optional detailed feedback |
+| `--provider <PROVIDER>` | `String` |  | Reviewer provider id for counter-model reviews |
+| `--commit <COMMIT>` | `String` |  | Reviewed commit SHA |
+
+## `agentdesk review-decision`
+
+Submit a review decision without HTTP server dependency
+
+Usage: `agentdesk review-decision [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--card <CARD_ID>` (required) | `String` |  | Kanban card ID |
+| `--decision <DECISION>` (required) | `String` |  | Decision: approve, rework, escalate, accept, dispute, dismiss, requeue, resume |
+| `--comment <COMMENT>` | `String` |  | Optional decision comment |
+| `--dispatch <DISPATCH_ID>` | `String` |  | Optional dispatch scope for agent reply decisions |
+
+## `agentdesk review-recover-target`
+
+Recover a review dispatch target commit/worktree through the API
+
+Usage: `agentdesk review-recover-target [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--dispatch <DISPATCH_ID>` | `String` |  | Review dispatch ID |
+| `--card <CARD_ID>` | `String` |  | Kanban card ID, used to resolve the latest review dispatch when --dispatch is omitted |
+| `--commit <TARGET_COMMIT>` | `String` |  | Reviewed commit SHA to pin |
+| `--worktree <WORKTREE_PATH>` | `String` |  | Worktree path whose HEAD must match the reviewed commit |
+| `--reason <REASON>` | `String` |  | Operator reason stored in the audit event |
+
+## `agentdesk docs`
+
+Read API documentation without HTTP server dependency
+
+Usage: `agentdesk docs [OPTIONS] [CATEGORY]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `[CATEGORY]` | `String` |  | Optional docs category |
+| `--flat` | flag |  | Emit flat endpoint list |
+
+## `agentdesk auto-queue`
+
+Auto-queue operations without HTTP server dependency
+
+Usage: `agentdesk auto-queue <COMMAND>`
+
+Subcommands:
+
+- `activate` — Activate an auto-queue run
+- `add` — Add a card to an auto-queue run
+- `config` — Update auto-queue runtime config
+
+### `agentdesk auto-queue activate`
+
+Activate an auto-queue run
+
+Usage: `agentdesk auto-queue activate [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--run <RUN_ID>` | `String` |  | Auto-queue run ID |
+| `--agent <AGENT_ID>` | `String` |  | Target agent ID |
+| `--repo <REPO>` | `String` |  | Repository in owner/repo form |
+| `--active-only` | flag |  | Restrict activation to already-live entries |
+
+### `agentdesk auto-queue add`
+
+Add a card to an auto-queue run
+
+Usage: `agentdesk auto-queue add [OPTIONS] <CARD_ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<CARD_ID>` | `String` |  | Card ID or issue number |
+| `--run <RUN_ID>` | `String` |  | Auto-queue run ID |
+| `--priority <PRIORITY>` | `i64` |  | Explicit priority rank |
+| `--phase <PHASE>` | `i64` |  | Batch phase |
+| `--thread-group <THREAD_GROUP>` | `i64` |  | Thread group |
+| `--agent <AGENT_ID>` | `String` |  | Agent override |
+
+### `agentdesk auto-queue config`
+
+Update auto-queue runtime config
+
+Usage: `agentdesk auto-queue config [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--run <RUN_ID>` | `String` |  | Auto-queue run ID |
+| `--repo <REPO>` | `String` |  | Repository in owner/repo form |
+| `--agent <AGENT_ID>` | `String` |  | Target agent ID |
+| `--max-concurrent <MAX_CONCURRENT_THREADS>` (required) | `i64` |  | Max concurrently active threads |
+
+## `agentdesk force-kill`
+
+Force-kill a session without HTTP server dependency
+
+Usage: `agentdesk force-kill [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--session-key <SESSION_KEY>` (required) | `String` |  | Session key |
+| `--retry` | flag |  | Requeue card after force-kill |
+
+## `agentdesk github-sync`
+
+Sync GitHub issues without HTTP server dependency
+
+Usage: `agentdesk github-sync [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--repo <REPO>` | `String` |  | Repository in owner/repo form. Omit to sync all registered sync-enabled repos. |
+
+## `agentdesk monitoring`
+
+Monitor status commands for Discord channels
+
+Usage: `agentdesk monitoring <COMMAND>`
+
+Subcommands:
+
+- `start` — Register or refresh a monitor status entry
+- `stop` — Remove a monitor status entry
+
+### `agentdesk monitoring start`
+
+Register or refresh a monitor status entry
+
+Usage: `agentdesk monitoring start [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--channel <CHANNEL>` (required) | `u64` |  | Discord channel ID |
+| `--key <KEY>` (required) | `String` |  | Monitor key, stable across refreshes |
+| `--description <DESCRIPTION>` (required) | `String` |  | Human-readable monitor description |
+
+### `agentdesk monitoring stop`
+
+Remove a monitor status entry
+
+Usage: `agentdesk monitoring stop [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--channel <CHANNEL>` (required) | `u64` |  | Discord channel ID |
+| `--key <KEY>` (required) | `String` |  | Monitor key to remove |
+
+## `agentdesk intake-outbox`
+
+intake_outbox operator tools (Phase 5 of intake-node-routing)
+
+Usage: `agentdesk intake-outbox <COMMAND>`
+
+Subcommands:
+
+- `dispatched-audit` — List dispatched rows and their recorded audit facts without changing them.
+- `dispatched-settle` — Settle a dispatched handoff as unknown without creating a retry child that could redeliver an already delivered turn.
+- `spawned-settle` — Settle a spawned handoff as unknown without creating a retry child that could redeliver an already delivered turn.
+- `status` — Show recent intake_outbox rows (newest first).
+- `force-fail` — Force-fail a stuck row and re-enqueue a fresh attempt. Implements transition 12 from the design doc.
+
+### `agentdesk intake-outbox dispatched-audit`
+
+List dispatched rows and their recorded audit facts without changing them.
+
+Usage: `agentdesk intake-outbox dispatched-audit`
+
+### `agentdesk intake-outbox dispatched-settle`
+
+Settle a dispatched handoff as unknown without creating a retry child that could redeliver an already delivered turn.
+
+Usage: `agentdesk intake-outbox dispatched-settle [OPTIONS] <ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<ID>` | `i64` |  |  |
+| `--reason <REASON>` | `String` | `operator dispatched-settle via CLI` |  |
+
+### `agentdesk intake-outbox spawned-settle`
+
+Settle a spawned handoff as unknown without creating a retry child that could redeliver an already delivered turn.
+
+Usage: `agentdesk intake-outbox spawned-settle [OPTIONS] <ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<ID>` | `i64` |  |  |
+| `--reason <REASON>` | `String` | `operator spawned-settle via CLI` |  |
+
+### `agentdesk intake-outbox status`
+
+Show recent intake_outbox rows (newest first).
+
+Usage: `agentdesk intake-outbox status [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--channel <CHANNEL_ID>` | `String` |  | Filter to a single Discord channel id. |
+| `--limit <LIMIT>` | `i64` | `20` | Maximum rows to display. |
+
+### `agentdesk intake-outbox force-fail`
+
+Force-fail a stuck row and re-enqueue a fresh attempt. Implements transition 12 from the design doc.
+
+Usage: `agentdesk intake-outbox force-fail [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--id <ID>` (required) | `i64` |  | id of the stuck row. |
+| `--reason <REASON>` | `String` | `operator force-fail via CLI` | Operator's reason text recorded in `last_error`. |
+
+## `agentdesk discord`
+
+Discord utility commands without HTTP server dependency
+
+Usage: `agentdesk discord <COMMAND>`
+
+Subcommands:
+
+- `read` — Read channel messages
+- `category-create` — Create a guild category. Idempotent (list-then-create): returns the existing category when one with the same name is already present. Not safe under concurrent invocations against the same guild.
+- `channel-create` — Create a text channel under an optional category. Idempotent by (name, parent category) via list-then-create. Not safe under concurrent invocations against the same guild.
+- `thread-create` — Create a thread under a text/news channel or a post under a forum/media channel. Cross-process safe and idempotent by (parent, normalized name) across active and archived public threads.
+
+### `agentdesk discord read`
+
+Read channel messages
+
+Usage: `agentdesk discord read [OPTIONS] <CHANNEL_ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<CHANNEL_ID>` | `String` |  | Discord channel ID |
+| `--limit <LIMIT>` | `u32` |  | Max messages to return |
+| `--before <BEFORE>` | `String` |  | Read messages before this message ID |
+| `--after <AFTER>` | `String` |  | Read messages after this message ID |
+
+### `agentdesk discord category-create`
+
+Create a guild category. Idempotent (list-then-create): returns the existing category when one with the same name is already present. Not safe under concurrent invocations against the same guild.
+
+Usage: `agentdesk discord category-create [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--name <NAME>` (required) | `String` |  | Category display name |
+| `--guild-id <GUILD_ID>` | `String` |  | Override the configured guild id |
+
+### `agentdesk discord channel-create`
+
+Create a text channel under an optional category. Idempotent by (name, parent category) via list-then-create. Not safe under concurrent invocations against the same guild.
+
+Usage: `agentdesk discord channel-create [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--name <NAME>` (required) | `String` |  | Channel display name |
+| `--category-id <CATEGORY_ID>` | `String` |  | Parent category channel id |
+| `--topic <TOPIC>` | `String` |  | Optional channel topic |
+| `--guild-id <GUILD_ID>` | `String` |  | Override the configured guild id |
+
+### `agentdesk discord thread-create`
+
+Create a thread under a text/news channel or a post under a forum/media channel. Cross-process safe and idempotent by (parent, normalized name) across active and archived public threads.
+
+Usage: `agentdesk discord thread-create [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--parent-channel-id <PARENT_CHANNEL_ID>` (required) | `String` |  | Parent text, news, forum, or media channel id |
+| `--name <NAME>` (required) | `String` |  | Thread name |
+| `--message <MESSAGE>` | `String` |  | Starter message required for forum/media parents (alias: --starter-message) (alias `--starter-message`) |
+| `--tag-id <TAG_IDS>...` | `u64` (repeatable) |  | Forum/media tag id to apply (repeat for multiple tags) |
+| `--auto-archive-minutes <AUTO_ARCHIVE_MINUTES>` | `u16` | `1440` | Auto-archive duration in minutes (60, 1440, 4320, 10080) |
+
+## `agentdesk card`
+
+Kanban utility commands without HTTP server dependency
+
+Usage: `agentdesk card <COMMAND>`
+
+Subcommands:
+
+- `create` — Create a card from a GitHub issue
+- `status` — Inspect a card and connected lifecycle state
+
+### `agentdesk card create`
+
+Create a card from a GitHub issue
+
+Usage: `agentdesk card create [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--from-issue <ISSUE_NUMBER>` (required) | `i64` |  | GitHub issue number to import |
+| `--repo <REPO>` | `String` |  | Repository in owner/repo form |
+| `--status <STATUS>` | `String` |  | Target status: backlog or ready |
+| `--agent <AGENT_ID>` | `String` |  | Agent assignment for ready cards |
+
+### `agentdesk card status`
+
+Inspect a card and connected lifecycle state
+
+Usage: `agentdesk card status [OPTIONS] <CARD_REF>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<CARD_REF>` | `String` |  | Card ID or GitHub issue number |
+| `--repo <REPO>` | `String` |  | Repository in owner/repo form |
+
+## `agentdesk cherry-merge`
+
+Cherry-pick a worktree branch into main and optionally close its issue
+
+Usage: `agentdesk cherry-merge [OPTIONS] <BRANCH>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<BRANCH>` | `String` |  | Source branch to merge into main |
+| `--close-issue` | flag |  | Close the linked GitHub issue when it can be inferred uniquely |
+
+## `agentdesk tmux-wrapper`
+
+tmux + Claude CLI integration wrapper (Unix only)
+
+Notes: `#[cfg(unix)]`.
+
+Usage: `agentdesk tmux-wrapper [OPTIONS] [CLAUDE_CMD]...`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--output-file <OUTPUT_FILE>` (required) | `String` |  | Path to the output capture file |
+| `--input-fifo <INPUT_FIFO>` (required) | `String` |  | Path to the input FIFO |
+| `--prompt-file <PROMPT_FILE>` (required) | `String` |  | Path to the prompt file |
+| `--cwd <CWD>` | `String` | `.` | Working directory (defaults to ".") |
+| `--input-mode <INPUT_MODE>` | `fifo`, `pipe` | `fifo` | Input mode: fifo (default) or pipe |
+| `[CLAUDE_CMD]...` | `String` (repeatable) |  | Claude command and arguments (after --) (after `--`) |
+
+## `agentdesk codex-tmux-wrapper`
+
+tmux + Codex CLI integration wrapper (Unix only)
+
+Notes: `#[cfg(unix)]`.
+
+Usage: `agentdesk codex-tmux-wrapper [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--output-file <OUTPUT_FILE>` (required) | `String` |  | Path to the output capture file |
+| `--input-fifo <INPUT_FIFO>` (required) | `String` |  | Path to the input FIFO |
+| `--prompt-file <PROMPT_FILE>` (required) | `String` |  | Path to the prompt file |
+| `--codex-bin <CODEX_BIN>` (required) | `String` |  | Path to codex binary |
+| `--codex-model <CODEX_MODEL>` | `String` |  | Optional codex model override |
+| `--reasoning-effort <REASONING_EFFORT>` | `String` |  | Optional reasoning effort (low, normal, high, xhigh) |
+| `--developer-instructions <DEVELOPER_INSTRUCTIONS>` | `String` |  | Optional developer instructions passed through Codex config |
+| `--resume-session-id <RESUME_SESSION_ID>` | `String` |  | Optional resume session id for the first turn |
+| `--fast-mode-state <FAST_MODE_STATE>` | `enabled`, `disabled` |  | Override Codex native fast mode for every turn in this wrapper session |
+| `--goals-state <GOALS_STATE>` | `enabled`, `disabled` |  | Override Codex goals feature flag for every turn in this wrapper session |
+| `--cwd <CWD>` | `String` | `.` | Working directory (defaults to ".") |
+| `--add-dir <ADD_DIRS>...` | `String` (repeatable) |  | Additional directory writable alongside the primary workspace |
+| `--input-mode <INPUT_MODE>` | `fifo`, `pipe` | `fifo` | Input mode: fifo (default) or pipe |
+| `--compact-token-limit <COMPACT_TOKEN_LIMIT>` | `u64` |  | Auto-compact token limit (absolute token count) |
+
+## `agentdesk qwen-tmux-wrapper`
+
+tmux + Qwen CLI integration wrapper (Unix only)
+
+Notes: `#[cfg(unix)]`.
+
+Usage: `agentdesk qwen-tmux-wrapper [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--output-file <OUTPUT_FILE>` (required) | `String` |  | Path to the output capture file |
+| `--input-fifo <INPUT_FIFO>` (required) | `String` |  | Path to the input FIFO |
+| `--prompt-file <PROMPT_FILE>` (required) | `String` |  | Path to the prompt file |
+| `--qwen-bin <QWEN_BIN>` (required) | `String` |  | Path to qwen binary |
+| `--qwen-model <QWEN_MODEL>` | `String` |  | Optional qwen model override |
+| `--qwen-core-tool <QWEN_CORE_TOOLS>...` | `String` (repeatable) |  | Qwen built-in core tool allowlist entry |
+| `--resume-session-id <RESUME_SESSION_ID>` | `String` |  | Optional resume session id for the first turn |
+| `--fresh-session` | flag |  | Force the first turn to start without reusing provider session state |
+| `--cwd <CWD>` | `String` | `.` | Working directory (defaults to ".") |
+| `--input-mode <INPUT_MODE>` | `fifo`, `pipe` | `fifo` | Input mode: fifo (default) or pipe |
+
+## `agentdesk claude-hook-relay`
+
+Relay Claude Code hook stdin JSON to the AgentDesk TUI hook receiver
+
+Usage: `agentdesk claude-hook-relay [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--endpoint <ENDPOINT>` (required) | `String` |  | Hook receiver base endpoint, e.g. http://127.0.0.1:49152 |
+| `--provider <PROVIDER>` (required) | `String` |  | Provider id, e.g. claude |
+| `--event <EVENT>` (required) | `String` |  | Claude hook event name, e.g. Stop or PreToolUse |
+| `--session-id <SESSION_ID>` (required) | `String` |  | TUI session id assigned by AgentDesk |
+
+## `agentdesk codex-hook-relay`
+
+Relay Codex hook stdin JSON to the AgentDesk TUI hook receiver
+
+Usage: `agentdesk codex-hook-relay [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--endpoint <ENDPOINT>` (required) | `String` |  | Hook receiver base endpoint, e.g. http://127.0.0.1:49152 |
+| `--provider <PROVIDER>` (required) | `String` |  | Provider id, e.g. codex |
+| `--event <EVENT>` (required) | `String` |  | Codex hook event name, e.g. Stop or PreToolUse |
+| `--session-id <SESSION_ID>` (required) | `String` |  | TUI session id assigned by AgentDesk |
+
+## `agentdesk reset-tmux`
+
+Kill all AgentDesk-* tmux sessions and clean temp files
+
+Usage: `agentdesk reset-tmux`
+
+## `agentdesk ismcptool`
+
+Check if MCP tool(s) are registered in .claude/settings.json
+
+Usage: `agentdesk ismcptool <TOOLS>...`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<TOOLS>...` | `String` (repeatable) |  | Tool names to check |
+
+## `agentdesk addmcptool`
+
+Add MCP tool permission(s) to .claude/settings.json
+
+Usage: `agentdesk addmcptool <TOOLS>...`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<TOOLS>...` | `String` (repeatable) |  | Tool names to add |
+
+## `agentdesk install-memento-session-hook`
+
+#2655: install (or refresh) the Memento `context()` SessionStart hook and a UserPromptSubmit token-pressure reminder into a Claude Code settings file. Idempotent — running twice produces the same file.
+
+Usage: `agentdesk install-memento-session-hook [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--settings-path <SETTINGS_PATH>` | `String` |  | Path to the settings.json to mutate. Defaults to `~/.claude/settings.json` when omitted. |
+| `--dry-run` | flag |  | Skip writing and instead print the rendered settings to stdout. |
+| `--uninstall` | flag |  | Remove the AgentDesk-managed memento hook entries instead of installing them. Useful when an operator wants to revert. (conflicts with `dry_run`) |
+
+## `agentdesk status`
+
+Show server health, active sessions, and auto-queue status
+
+Usage: `agentdesk status`
+
+## `agentdesk cards`
+
+List kanban cards
+
+Usage: `agentdesk cards [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--status <STATUS>` | `String` |  | Filter by status (e.g. ready, in_progress, done) |
+
+## `agentdesk dispatch`
+
+Dispatch operations
+
+Usage: `agentdesk dispatch [COMMAND] [OPTIONS] [ISSUE_GROUP]...`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `[ISSUE_GROUP]...` | `String` (repeatable) |  | Issue groups such as `423,405` or `407` |
+| `--repo <REPO>` | `String` |  | Repository full name. Defaults to git remote inference when possible. |
+| `--agent <AGENT_ID>` | `String` |  | Target agent id for auto-assignment and activation filtering. |
+| `--unified` | flag |  | Legacy compatibility flag forwarded to the API. |
+| `--concurrent <CONCURRENT>` | `i64` |  | Max number of concurrently active thread groups. |
+| `--no-activate` | flag |  | Generate the run but do not activate it. |
+
+Subcommands:
+
+- `list` — List active dispatches
+- `retry` — Retry a dispatch for a card
+- `redispatch` — Redispatch a card
+
+### `agentdesk dispatch list`
+
+List active dispatches
+
+Usage: `agentdesk dispatch list`
+
+### `agentdesk dispatch retry`
+
+Retry a dispatch for a card
+
+Usage: `agentdesk dispatch retry <CARD_ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<CARD_ID>` | `String` |  | Kanban card ID |
+
+### `agentdesk dispatch redispatch`
+
+Redispatch a card
+
+Usage: `agentdesk dispatch redispatch <CARD_ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<CARD_ID>` | `String` |  | Kanban card ID |
+
+## `agentdesk resume`
+
+Resume a stuck kanban card from its current state
+
+Usage: `agentdesk resume [OPTIONS] <CARD_ID>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<CARD_ID>` | `String` |  | Card ID or GitHub issue number |
+| `--force` | flag |  | Force resume (bypass guards for manual-intervention states) |
+| `--reason <REASON>` | `String` |  | Reason for audit log |
+
+## `agentdesk advance`
+
+Complete pending dispatch and advance to review
+
+Usage: `agentdesk advance <ISSUE_NUMBER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<ISSUE_NUMBER>` | `String` |  | GitHub issue number |
+
+## `agentdesk queue`
+
+Show auto-queue status with thread links
+
+Notes: deprecated.
+
+Usage: `agentdesk queue`
+
+> Deprecated compatibility command. For the queue-only inspector, use `agentdesk query queue`; use `agentdesk query` for the combined queue, dispatch, and phase-gate snapshot. This command preserves its legacy text and JSON output shapes.
+
+## `agentdesk query`
+
+Unified queue + dispatch + phase-gate inspection (issue #2651).
+
+First-class replacement for the ad-hoc `curl /api/queue/status | python -c '...'` polling pattern. Aggregates the queue run state, pending dispatches, and phase-gate snapshot into one structured response. Pass `--json` for machine-readable output.
+
+Usage: `agentdesk query [COMMAND] [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--filter <FILTERS>...` | `String` (repeatable) |  | Filter result rows. Repeatable. Format: `key:value` (e.g. `--filter status:pending`, `--filter dispatch_type:review`). (accepted before or after the subcommand) |
+| `--agent <AGENT>` | `String` |  | Restrict to a specific agent_id when applicable. (accepted before or after the subcommand) |
+| `--limit <LIMIT>` | `usize` | `0` | Maximum rows to render per section (0 = unlimited). (accepted before or after the subcommand) |
+
+Subcommands:
+
+- `queue` — Auto-queue run + entries snapshot (calls `/api/queue/status`).
+- `dispatches` — Pending dispatches across all agents (calls `/api/dispatches/pending`).
+- `phase-gate` — Phase-gate catalog + active gate state (calls `/api/queue/phase-gates/catalog`).
+- `all` — All sections in one shot (default).
+
+### `agentdesk query queue`
+
+Auto-queue run + entries snapshot (calls `/api/queue/status`).
+
+Usage: `agentdesk query queue`
+
+### `agentdesk query dispatches`
+
+Pending dispatches across all agents (calls `/api/dispatches/pending`).
+
+Usage: `agentdesk query dispatches`
+
+### `agentdesk query phase-gate`
+
+Phase-gate catalog + active gate state (calls `/api/queue/phase-gates/catalog`).
+
+Usage: `agentdesk query phase-gate`
+
+### `agentdesk query all`
+
+All sections in one shot (default).
+
+Usage: `agentdesk query all`
+
+## `agentdesk phase`
+
+Phase-gate violation snapshot (issue #2657).
+
+Read-only inspector that flags auto-queue entries dispatched at a higher `batch_phase` than the run's live phase pointer. Mirrors the `/adk-phase` Discord slash command.
+
+Usage: `agentdesk phase [COMMAND] [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--detailed` | flag |  | Show full per-entry detail. (accepted before or after the subcommand) |
+
+Subcommands:
+
+- `status` — Show current violations (default).
+
+### `agentdesk phase status`
+
+Show current violations (default).
+
+Usage: `agentdesk phase status`
+
+## `agentdesk deploy`
+
+Build + deploy dev + promote to release
+
+Usage: `agentdesk deploy`
+
+## `agentdesk agents`
+
+List agents and their status
+
+Usage: `agentdesk agents`
+
+## `agentdesk diag`
+
+Show turn/session diagnostics for an agent ID or Discord channel ID
+
+Usage: `agentdesk diag <IDENTIFIER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<IDENTIFIER>` | `String` |  | Agent ID or Discord channel ID |
+
+## `agentdesk config`
+
+Runtime config get/set
+
+Usage: `agentdesk config <COMMAND>`
+
+Subcommands:
+
+- `get` — Get current runtime config
+- `set` — Set runtime config (JSON string)
+- `audit` — Audit config source-of-truth drift across yaml/DB/legacy files
+- `sync-mcp` — Sync runtime MCP servers into provider config files
+
+### `agentdesk config get`
+
+Get current runtime config
+
+Usage: `agentdesk config get`
+
+### `agentdesk config set`
+
+Set runtime config (JSON string)
+
+Usage: `agentdesk config set <JSON>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<JSON>` | `String` |  | JSON value to set |
+
+### `agentdesk config audit`
+
+Audit config source-of-truth drift across yaml/DB/legacy files
+
+Usage: `agentdesk config audit [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--dry-run` | flag |  | Preview migrations without writing files or syncing the DB |
+
+### `agentdesk config sync-mcp`
+
+Sync runtime MCP servers into provider config files
+
+Usage: `agentdesk config sync-mcp`
+
+## `agentdesk api`
+
+Call any API endpoint (curl replacement)
+
+Usage: `agentdesk api <METHOD> <PATH> [BODY]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<METHOD>` | `String` |  | HTTP method (GET, POST, PATCH, PUT, DELETE) |
+| `<PATH>` | `String` |  | API path (e.g. /api/health) |
+| `[BODY]` | `String` |  | Optional JSON body |
+
+## `agentdesk terminations`
+
+List session termination events
+
+Usage: `agentdesk terminations [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--card-id <CARD_ID>` | `String` |  | Filter by kanban card ID |
+| `--dispatch-id <DISPATCH_ID>` | `String` |  | Filter by dispatch ID |
+| `--session <SESSION>` | `String` |  | Filter by session key |
+| `--limit <LIMIT>` | `u32` | `50` | Max number of events to show |
+
+## `agentdesk doctor`
+
+Environment diagnostics
+
+Usage: `agentdesk doctor [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--fix` | flag |  | Apply safe local repairs before running diagnostics |
+| `--allow-restart` | flag |  | Allow doctor --fix to restart the dcserver service |
+| `--repair-sqlite-cache` | flag |  | Allow doctor --fix to run SQLite schema repair and remove stale SQLite cache files |
+| `--allow-remote` | flag |  | Allow sending configured auth tokens to a non-loopback AGENTDESK_API_URL |
+| `--profile <PROFILE>` | `quick`, `deep`, `security` |  | Restrict checks to a profile |
+
+## `agentdesk migrate`
+
+Migration helpers
+
+Usage: `agentdesk migrate <COMMAND>`
+
+Subcommands:
+
+- `openclaw` — Import OpenClaw durable state into AgentDesk
+
+### `agentdesk migrate openclaw`
+
+Import OpenClaw durable state into AgentDesk
+
+Usage: `agentdesk migrate openclaw [OPTIONS] [ROOT_PATH]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `[ROOT_PATH]` | `String` |  | OpenClaw root path or openclaw.json path. Defaults to the current directory. (conflicts with `resume`) |
+| `--agentdesk-root <PATH>` | `String` |  | Override the target AgentDesk runtime root. |
+| `--agent <AGENT_ID>...` | `String` (repeatable) |  | Select a specific source agent id. May be repeated. (conflicts with `all_agents`) |
+| `--all-agents` | flag |  | Import every source agent. (conflicts with `agent_ids`) |
+| `--dry-run` | flag |  | Print the canonical import plan without writing files. |
+| `--resume <IMPORT_ID>` | `String` |  | Resume an unfinished import from $AGENTDESK_ROOT_DIR/openclaw/imports/<import_id>. (conflicts with `root_path`) |
+| `--fallback-provider <FALLBACK_PROVIDER>` | `String` |  | Fallback provider to use when the source provider is unsupported. |
+| `--workspace-root-rewrite <OLD=NEW>...` | `String` (repeatable) |  | Rewrite absolute OpenClaw workspace prefixes during import planning. May be repeated as OLD=NEW. |
+| `--write-org` | flag |  | Preview writing config/org.yaml mutations. |
+| `--write-bot-settings` | flag |  | Preview writing config/bot_settings.json mutations. |
+| `--write-db` | flag |  | Preview PostgreSQL upserts. |
+| `--overwrite` | flag |  | Preview replacing generated artifacts for the selected role(s). |
+| `--with-channel-bindings` | flag |  | Preview Discord channel binding imports. |
+| `--with-sessions` | flag |  | Preview lossy session import. |
+| `--snapshot-source` | flag |  | Preview snapshotting the source tree into audit outputs. |
+| `--no-workspace` | flag |  | Skip workspace copy while still inspecting source workspaces for prompt/memory. |
+| `--no-memory` | flag |  | Skip Markdown memory import. |
+| `--no-prompts` | flag |  | Skip merged prompt generation. |
+| `--tool-policy-mode <TOOL_POLICY_MODE>` | `String` | `report` | Tool-policy handling mode for bot_settings import. |
+| `--discord-token-mode <DISCORD_TOKEN_MODE>` | `String` | `report` | Discord token handling mode for bot_settings import. |
+
+## `agentdesk release-migrate-postgres`
+
+Apply pending PostgreSQL migrations before release activation
+
+Notes: hidden from `--help`.
+
+Usage: `agentdesk release-migrate-postgres`
+
+## `agentdesk provider-cli`
+
+Provider CLI safe migration management
+
+Usage: `agentdesk provider-cli <COMMAND>`
+
+Subcommands:
+
+- `status` — Show current registry channels and migration states
+- `plan` — Show what a migration would do without running it
+- `upgrade` — [step] Snapshot current binary and run upgrade
+- `smoke` — [step] Run smoke checks against current or candidate binary
+- `canary` — [step] Select a canary agent for the migration
+- `promote` — Confirm promotion after canary passes (operator gate)
+- `rollback` — Roll back migration to previous state
+- `cleanup` — List paths eligible for cleanup (dry-run only — deletion not implemented)
+- `run` — Run full migration orchestration up to CanaryActive
+- `resume` — Resume migration from the current persisted state
+
+### `agentdesk provider-cli status`
+
+Show current registry channels and migration states
+
+Usage: `agentdesk provider-cli status [OPTIONS] [PROVIDER]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `[PROVIDER]` | `String` |  | Restrict output to a single provider (codex, claude, gemini, opencode, qwen) |
+| `--json` | flag |  | Output raw JSON instead of the default table |
+
+### `agentdesk provider-cli plan`
+
+Show what a migration would do without running it
+
+Usage: `agentdesk provider-cli plan <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to plan (codex, claude, gemini, opencode, qwen) |
+
+### `agentdesk provider-cli upgrade`
+
+[step] Snapshot current binary and run upgrade
+
+Use `agentdesk provider-cli run` for the full automated migration.
+
+Usage: `agentdesk provider-cli upgrade [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to upgrade |
+| `--skip-previous-preservation` | flag |  | Skip preserving the previous binary (for mutates_in_place providers) |
+| `--candidate-path <CANDIDATE_PATH>` | `String` |  | Override candidate binary path after upgrade |
+
+### `agentdesk provider-cli smoke`
+
+[step] Run smoke checks against current or candidate binary
+
+Smoke is run automatically by `agentdesk provider-cli run`.
+
+Usage: `agentdesk provider-cli smoke [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to smoke-test |
+| `--channel <CHANNEL>` | `String` | `current` | Channel to test: current or candidate |
+
+### `agentdesk provider-cli canary`
+
+[step] Select a canary agent for the migration
+
+Canary selection is handled automatically by `agentdesk provider-cli run`.
+
+Usage: `agentdesk provider-cli canary [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to select canary for |
+| `--agent <CANARY_AGENT>` | `String` |  | Explicitly request this agent as the canary |
+
+### `agentdesk provider-cli promote`
+
+Confirm promotion after canary passes (operator gate)
+
+Usage: `agentdesk provider-cli promote [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to promote |
+| `--evidence <EVIDENCE>` | `String` |  | Operator note recorded in migration history |
+
+### `agentdesk provider-cli rollback`
+
+Roll back migration to previous state
+
+Usage: `agentdesk provider-cli rollback [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to roll back |
+| `--evidence <EVIDENCE>` | `String` |  | Operator note recorded in migration history |
+
+### `agentdesk provider-cli cleanup`
+
+List paths eligible for cleanup (dry-run only — deletion not implemented)
+
+Usage: `agentdesk provider-cli cleanup <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to inspect |
+
+### `agentdesk provider-cli run`
+
+Run full migration orchestration up to CanaryActive
+
+Usage: `agentdesk provider-cli run [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to migrate |
+| `--candidate-path <CANDIDATE_PATH>` | `String` |  | Override candidate path (skip upgrade step) |
+| `--canary-agent <CANARY_AGENT>` | `String` |  | Request a specific canary agent |
+| `--skip-upgrade` | flag |  | Skip binary preservation (use with caution) |
+| `--skip-confirm` | flag |  | Skip operator confirmation gate after canary passes (alias `--auto-promote`) |
+
+### `agentdesk provider-cli resume`
+
+Resume migration from the current persisted state
+
+Usage: `agentdesk provider-cli resume [OPTIONS] <PROVIDER>`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `<PROVIDER>` | `String` |  | Provider to resume |
+| `--skip-confirm` | flag |  | Skip operator confirmation gate after canary passes (alias `--auto-promote`) |
+
+## `agentdesk show`
+
+Inspect deterministic session-binding values (epic #2285 E1).
+
+Usage: `agentdesk show <COMMAND>`
+
+Subcommands:
+
+- `session-name` — Print the expected tmux session name for a Discord channel.
+
+### `agentdesk show session-name`
+
+Print the expected tmux session name for a Discord channel.
+
+Usage: `agentdesk show session-name [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--channel <CHANNEL>` (required) | `String` |  | Discord channel id (or stable channel identifier) — same value AgentDesk uses when composing the tmux session name. |
+| `--provider <PROVIDER>` | `String` |  | Provider to encode in the session name. Required unless the channel name ends in a registered provider suffix (`-cc`, `-cdx`, `-gm`, `-oc`, `-qw`). The CLI deliberately does not read live channel bindings — operator output must be reproducible from arguments alone. |
+
+## `agentdesk health`
+
+Show consolidated health snapshot of the current node (server status, dcserver pid, last deploy time, queue lag, Discord/disk/outbox).
+
+Usage: `agentdesk health`
+
+## `agentdesk machine-compare`
+
+Compare release/main/dev state across every registered worker node (`mac-mini`, `mac-book`, …). Renders a side-by-side table with dcserver pid, last deploy, queue lag, and a `diff` column.
+
+Usage: `agentdesk machine-compare`
+
+## `agentdesk activity`
+
+Time-windowed activity report: commits / closed issues / merged PRs / deploys / incidents in a single table. Uses gh + git + AgentDesk API.
+
+Usage: `agentdesk activity [OPTIONS]`
+
+| Argument | Value | Default | Description |
+|---|---|---|---|
+| `--since <SINCE>` (required) | `String` |  | Window start. Accepts RFC3339 (`2026-05-19T23:10:00+09:00`), duration suffix (`24h`, `90m`, `7d`), or `since:<sha>` to anchor on a commit (commit time becomes the start). |
+| `--until <UNTIL>` | `String` |  | Optional window end (RFC3339). Defaults to `now` when omitted. |
+| `--repo <REPO>` | `String` |  | Repository in owner/repo form. Defaults to the current repo's `origin` remote when omitted. |
+| `--no-agentdesk` | flag |  | Skip the AgentDesk-side deploy / incident lookup (useful when the local API is offline). Pure git + gh report. |
diff --git a/docs/generated/env-reference.md b/docs/generated/env-reference.md
new file mode 100644
index 0000000000..b7e2babd8e
--- /dev/null
+++ b/docs/generated/env-reference.md
@@ -0,0 +1,138 @@
+# Environment Variable Reference
+
+<!-- Generated by `python3 scripts/generate_env_reference.py`. Do not edit by hand. -->
+
+Environment variables read by the AgentDesk binary, derived from `src/`.
+Test-only modules and `#[cfg(test)]` blocks are excluded. `Defined at`
+points to the name constant when one exists, otherwise to the first read
+site; `(+N more)` counts additional read sites. `Description` is the
+comment adjacent to that site (blank when the code has none).
+
+Regenerate with `python3 scripts/generate_env_reference.py`; CI fails when this file drifts.
+
+- AgentDesk variables (`AGENTDESK_*`, `ADK_*`): 87
+- Platform and third-party variables: 27
+
+## AgentDesk variables
+
+| Variable | Defined at | Description |
+|---|---|---|
+| `ADK_API_URL` | `src/cli/monitoring.rs:33` | This module's api_base() prefers ADK_API_URL over AGENTDESK_API_URL — the hint must match that order. |
+| `ADK_FORCE_LOCAL_MEMORY` | `src/server/routes/memory_api.rs:53` | `ADK_FORCE_LOCAL_MEMORY=1` → always Local (testing / escape hatch). |
+| `ADK_GITHUB_SYNC_ALERT_CHANNEL` | `src/github/sync.rs:1460` |  |
+| `ADK_INTAKE_ROUTING_MODE` | `src/services/cluster/intake_routing_config.rs:236` (+1 more) |  |
+| `ADK_OBSERVABILITY_COUNTER_SNAPSHOT_RETENTION_DAYS` | `src/services/observability/retention.rs:35` | #2049 Finding 9: prune old rows from observability tables to bound disk and index growth on long-lived single-node deployments. |
+| `ADK_OBSERVABILITY_EVENTS_PATH` | `src/services/observability/events.rs:211` | Honors `ADK_OBSERVABILITY_EVENTS_PATH` for tests. |
+| `ADK_OBSERVABILITY_EVENT_RETENTION_DAYS` | `src/services/observability/retention.rs:27` | #2049 Finding 9: prune old rows from observability tables to bound disk and index growth on long-lived single-node deployments. |
+| `ADK_OBSERVABILITY_QUALITY_RETENTION_DAYS` | `src/services/observability/retention.rs:31` | #2049 Finding 9: prune old rows from observability tables to bound disk and index growth on long-lived single-node deployments. |
+| `ADK_QUALITY_ALERT_DRILL_BASE` | `src/services/agent_quality/regression_alerts.rs:44` (+1 more) | Resolve the drill-down base URL (env override or fallback const). |
+| `ADK_SLO_ALERT_CHANNEL` | `src/services/slo/mod.rs:34` (+1 more) | Fallback alert channel (adk-cc) used when `ADK_SLO_ALERT_CHANNEL` is unset. |
+| `ADK_THREAD_LOCK_WAIT_STARTED` | `src/cli/discord_thread_create_lock.rs:549` |  |
+| `ADK_VOICE_KEEP_WAV` | `src/voice/config.rs:135` | `keep_recordings` 또는 환경변수 `ADK_VOICE_KEEP_WAV` 에 따라 utterance wav / segment / transcript sidecar 를 보존할지 결정한다 (#2156). |
+| `ADK_VOICE_SILENCE` | `src/services/discord/voice_barge_in/foreground_decision.rs:3` |  |
+| `AGENTDESK_API_URL` | `src/cli/client.rs:11` (+1 more) | `env_hint` names the environment variable(s) the *caller's* `api_base()` actually honors — client.rs resolves `AGENTDESK_API_URL` only, while monitoring.rs pre… |
+| `AGENTDESK_CATCH_UP_POLL_SECS` | `src/services/discord/runtime_bootstrap/spawns.rs:412` |  |
+| `AGENTDESK_CATCH_UP_SCAN_PACE_MS` | `src/services/discord/catch_up.rs:714` | `AGENTDESK_CATCH_UP_SCAN_PACE_MS` overrides the gap (0 disables — used by tests and by operators who want the old unthrottled behaviour). |
+| `AGENTDESK_CLAUDE_TUI_FOLLOWUP_REQUEUE` | `src/services/claude.rs:65` (+1 more) | Default ON; set `AGENTDESK_CLAUDE_TUI_FOLLOWUP_REQUEUE` to `0`, `false`, `off`, `no`, `disable`, or `disabled` for emergency opt-out. |
+| `AGENTDESK_CLUSTER_API_BASE_URL` | `src/services/cluster/session_routing.rs:19` |  |
+| `AGENTDESK_CODEX_DIRECT_TUI_HOOKS` | `src/services/codex.rs:428` |  |
+| `AGENTDESK_CODEX_FIRST_EVENT_TIMEOUT_SECS` | `src/services/codex_tmux_wrapper.rs:357` |  |
+| `AGENTDESK_CODEX_REASONING_EFFORT` | `src/services/codex.rs:192` |  |
+| `AGENTDESK_CODEX_REMOTE_TMUX` | `src/services/codex.rs:1233` |  |
+| `AGENTDESK_CODEX_TUI_WARM_FOLLOWUP` | `src/services/codex_tui/warm_followup.rs:14` (+1 more) |  |
+| `AGENTDESK_CODEX_TURN_HARD_CEILING_SECS` | `src/services/codex_tmux_wrapper.rs:380` (+1 more) | Override via `AGENTDESK_CODEX_TURN_HARD_CEILING_SECS` (shared with the orchestrator-side auto-extend ceiling so a single knob bounds the Codex turn end to end). |
+| `AGENTDESK_CODEX_TURN_IDLE_RECV_SECS` | `src/services/codex_tmux_wrapper.rs:368` | Override via `AGENTDESK_CODEX_TURN_IDLE_RECV_SECS`. |
+| `AGENTDESK_CONFIG` | `src/config.rs:3353` (+5 more) | The on-disk config path the running server loaded from, resolved with the same precedence as [`load`] (`$AGENTDESK_CONFIG` → runtime root → cwd → home). |
+| `AGENTDESK_CSWAP_PATH` | `src/services/cswap.rs:22` (+1 more) |  |
+| `AGENTDESK_DCSERVER_LABEL` | `src/cli/dcserver.rs:18` (+2 more) |  |
+| `AGENTDESK_DCSERVER_LOG_MAX_BYTES` | `src/logging.rs:214` |  |
+| `AGENTDESK_DCSERVER_LOG_MAX_FILES` | `src/logging.rs:222` |  |
+| `AGENTDESK_DELIVERY_RECORD_AUTHORITY` | `src/services/discord/outbound/delivery_record.rs:1320` | #3089 B2b read-authority flag (`AGENTDESK_DELIVERY_RECORD_AUTHORITY`, OnceLock, compiled default ON since #5071 T1 S8-2). |
+| `AGENTDESK_DELIVERY_RECORD_SHADOW` | `src/services/discord/outbound/delivery_record.rs:1249` | #3089 B1 shadow-write flag (`AGENTDESK_DELIVERY_RECORD_SHADOW`, OnceLock, default OFF), with its provenance. |
+| `AGENTDESK_DISCORD_API_BASE_URL` | `src/services/dispatches/discord_delivery/transport.rs:192` |  |
+| `AGENTDESK_DISCORD_HIGH_RISK_ENABLED` | `src/services/discord/commands/command_policy.rs:147` | Issue #2653 recovery commands also run curated bash pipelines (launchctl + ssh + git push --force-with-lease) so they share the same tier: owner-only AND defau… |
+| `AGENTDESK_E2E_CHANNEL_IDS` | `src/services/discord/e2e_control.rs:22` (+1 more) | The HTTP route subtree is mounted only when `AGENTDESK_E2E_CONTROL=1` was present when dcserver started, and every operation is restricted to channel IDs captu… |
+| `AGENTDESK_E2E_CONTROL` | `src/services/discord/e2e_control.rs:21` (+1 more) | The HTTP route subtree is mounted only when `AGENTDESK_E2E_CONTROL=1` was present when dcserver started, and every operation is restricted to channel IDs captu… |
+| `AGENTDESK_GH_PATH` | `src/github/mod.rs:17` (+1 more) |  |
+| `AGENTDESK_HEADLESS_DISCORD_NONCE` | `src/services/discord/outbound/manual_delivery/headless_nonce.rs:8` (+1 more) |  |
+| `AGENTDESK_HEADLESS_DURABLE_OUTBOX` | `src/services/discord/turn_bridge/headless_delivery/durable_outbox.rs:8` (+1 more) |  |
+| `AGENTDESK_HOOK_RELAY_FAILURE_MARKER_PARENT_TEST` | `src/services/claude_tui/hook_relay.rs:36` |  |
+| `AGENTDESK_HOOK_RELAY_FAILURE_MARKER_TEST_ELAPSED_PATH` | `src/services/claude_tui/hook_relay.rs:38` |  |
+| `AGENTDESK_HOOK_RELAY_FAILURE_MARKER_TEST_RELEASE_PATH` | `src/services/claude_tui/hook_relay.rs:41` |  |
+| `AGENTDESK_HOOK_RELAY_FAILURE_MARKER_WORKER` | `src/services/claude_tui/hook_relay.rs:32` (+1 more) |  |
+| `AGENTDESK_HOOK_RELAY_NON_WAIT_PARENT_TEST` | `src/services/claude_tui/hook_relay.rs:44` |  |
+| `AGENTDESK_HOOK_RELAY_NON_WAIT_WORKER` | `src/services/claude_tui/hook_relay.rs:33` (+1 more) |  |
+| `AGENTDESK_HOOK_RELAY_TEST_ELAPSED_PATH` | `src/services/claude_tui/hook_relay.rs:48` |  |
+| `AGENTDESK_HOOK_RELAY_TEST_ENDPOINT` | `src/services/claude_tui/hook_relay.rs:46` |  |
+| `AGENTDESK_HOOK_RELAY_TEST_MUTATION` | `src/services/claude_tui/hook_relay/ordered_queue.rs:41` (+1 more) |  |
+| `AGENTDESK_HOOK_RELAY_TEST_STDOUT_PATH` | `src/services/claude_tui/hook_relay.rs:50` |  |
+| `AGENTDESK_INSTANCE_ID` | `src/services/cluster/node_registry.rs:676` (+1 more) | Resolve the self instance_id, preferring the value the cluster bootstrap registered (config-driven if present), falling back to the env-var/hostname pair only… |
+| `AGENTDESK_KAKAO_ACCOUNTS` | `src/services/kakao.rs:28` (+1 more) |  |
+| `AGENTDESK_KAKAO_DEFAULT_ACCOUNT` | `src/services/kakao.rs:29` (+1 more) |  |
+| `AGENTDESK_KAKAO_ENABLED` | `src/services/kakao.rs:27` (+2 more) |  |
+| `AGENTDESK_KAKAO_LANDING_URL` | `src/services/kakao.rs:30` (+1 more) |  |
+| `AGENTDESK_LONG_TURN_ALERT_COOLDOWN_SECS` | `src/services/long_turn_watchdog.rs:65` | Override via `AGENTDESK_LONG_TURN_ALERT_COOLDOWN_SECS`. |
+| `AGENTDESK_MEETING_SELECTION_TIMEOUT_SECS` | `src/services/discord/meeting_orchestrator/selection_runtime.rs:58` |  |
+| `AGENTDESK_MEMENTO_HOOK` | `src/cli/utils.rs:152` | #2655: marker key that identifies AgentDesk-managed hook entries in a Claude Code `settings.json`. |
+| `AGENTDESK_MEMORY_MERGE_SKILL` | `src/services/routines/migrated.rs:221` |  |
+| `AGENTDESK_MIGRATED_AGENTFACTORY_WORKDIR` | `src/services/routines/migrated.rs:207` |  |
+| `AGENTDESK_OBSIDIAN_AGENTS_SRC` | `src/services/operator_connectors.rs:132` (+2 more) |  |
+| `AGENTDESK_OBSIDIAN_SKILL_ROOT` | `src/services/operator_connectors.rs:147` (+3 more) |  |
+| `AGENTDESK_POLICY_HARDENING` | `src/engine/loader.rs:67` (+1 more) |  |
+| `AGENTDESK_POLICY_TRUST_ENFORCE` | `src/engine/loader.rs:61` |  |
+| `AGENTDESK_POLICY_TRUST_OVERRIDE` | `src/engine/loader.rs:55` |  |
+| `AGENTDESK_PROMPT_CACHE_DEFAULT_MINUTES` | `src/config.rs:615` | `AGENTDESK_PROMPT_CACHE_DEFAULT_MINUTES` accepts `5` or `60`; anything else (including the variable being unset) returns `None`. |
+| `AGENTDESK_PRUNE_GLOBAL_SLASH_COMMANDS` | `src/services/discord/runtime_bootstrap/framework_setup.rs:282` |  |
+| `AGENTDESK_PYTHON3_PATH` | `src/engine/ops/runtime_ops.rs:18` |  |
+| `AGENTDESK_REBIND_ORIGIN_DEADLINE_SECS` | `src/services/discord/inflight/rebind_reap.rs:268` | Reads `AGENTDESK_REBIND_ORIGIN_DEADLINE_SECS`; on absence / parse failure falls back to [`REBIND_ORIGIN_DEADLINE_SECS_DEFAULT`]. |
+| `AGENTDESK_RECOVERY_ANCHOR_REPOST` | `src/services/discord/recovery_paths/shared.rs:243` | #3610 PR-2: gate for the recovery anchor-repost fallback (`AGENTDESK_RECOVERY_ANCHOR_REPOST`). |
+| `AGENTDESK_RELAY_CIRCUIT_STAMP` | `src/services/discord/relay_recovery_circuit_alert_producer.rs:19` (+1 more) |  |
+| `AGENTDESK_RELEASE_TMUX_SESSION` | `src/cli/dcserver.rs:19` (+1 more) |  |
+| `AGENTDESK_REPORT_CHANNEL_ID` | `src/services/discord/restart_report.rs:14` (+1 more) |  |
+| `AGENTDESK_REPORT_PROVIDER` | `src/services/discord/restart_report.rs:15` (+1 more) |  |
+| `AGENTDESK_REPO_DIR` | `src/services/git/repo_resolver.rs:32` | Priority: `AGENTDESK_REPO_DIR` env -> scan all known roots for a git workspace -> `~/AgentDesk`. |
+| `AGENTDESK_REQUIRE_PG` | `src/db/postgres.rs:1170` (+2 more) | Every fixture that creates a database must use this authority; callers that can skip return `None`, while required lanes still get the hard failure below when… |
+| `AGENTDESK_REVIEW_MCP_ALLOWLIST` | `src/services/mcp_config.rs:16` (+1 more) |  |
+| `AGENTDESK_ROOT_DIR` | `src/cli/dcserver.rs:20` (+14 more) | Canonical runtime root: $AGENTDESK_ROOT_DIR → ~/.adk/release All code that needs the AgentDesk root directory MUST call this function instead of reimplementing… |
+| `AGENTDESK_SINGLE_MESSAGE_PANEL` | `src/services/discord/single_message_panel.rs:33` | The rollout gate previously short-circuited a missing env var to `false`, so any environment without an explicit `AGENTDESK_SINGLE_MESSAGE_PANEL=1` silently fe… |
+| `AGENTDESK_SOURCE_ZPROFILE` | `src/services/routines/migrated.rs:619` |  |
+| `AGENTDESK_STATUS_INTERVAL_SECS` | `src/services/discord/mod.rs:499` (+1 more) | Minimum interval between Discord placeholder progress edits (AGENTDESK_STATUS_INTERVAL_SECS, default 5s). |
+| `AGENTDESK_TEST_POSTGRES_ACQUIRE_TIMEOUT_MS` | `src/db/postgres.rs:1172` (+1 more) | Read the shared PG fixture base; required PG lanes must not silently turn a missing base into a soft-skip. |
+| `AGENTDESK_TOKEN` | `src/cli/run.rs:142` |  |
+| `AGENTDESK_TURN_HARD_CEILING_SECS` | `src/services/discord/mod.rs:531` | Default 6h matches the current effective cap so this is non-destructive by default; lower it via `AGENTDESK_TURN_HARD_CEILING_SECS` to enforce a real backstop. |
+| `AGENTDESK_TURN_IDLE_TIMEOUT_SECS` | `src/services/discord/mod.rs:517` | AGENTDESK_TURN_IDLE_TIMEOUT_SECS. |
+| `AGENTDESK_TURN_TIMEOUT_SECS` | `src/services/discord/mod.rs:508` (+1 more) | AGENTDESK_TURN_TIMEOUT_SECS. |
+| `AGENTDESK_VOICE_REQUIRE_ALIASES` | `src/services/discord_config_audit.rs:206` | - On collision when `AGENTDESK_VOICE_REQUIRE_ALIASES=1`: return an `Err` describing the collision so callers can choose to fail fast. |
+| `AGENTDESK_WORKSPACE_ROOT` | `src/services/routines/migrated.rs:309` (+1 more) |  |
+
+## Platform and third-party variables
+
+| Variable | Defined at | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | `src/server/mod.rs:1212` (+1 more) | Priority: 1) OAuth token (Claude Code subscription), 2) ANTHROPIC_API_KEY. |
+| `APPDATA` | `src/services/platform/binary_resolver.rs:1186` |  |
+| `CARGO_MANIFEST_DIR` | `src/services/maintenance/jobs/target_sweep.rs:55` | Order matters: `CARGO_MANIFEST_DIR` is set by cargo during dev/test runs (resolving the actual checkout) but is UNSET in the deployed release binary, so it cle… |
+| `CLAUDE_CONFIG_DIR` | `src/services/claude_tui/hook_output_guard.rs:57` (+3 more) | The Claude home this host reads rollout transcripts under, honouring the `CLAUDE_CONFIG_DIR` override. |
+| `CODEX_HOME` | `src/services/codex_tui/rollout_tail.rs:168` | The Codex home this host reads rollouts under, honouring the `CODEX_HOME` override. |
+| `COKACDIR_DEBUG` | `src/services/claude.rs:242` | Global runtime debug flag — togglable via `/debug` command or COKACDIR_DEBUG=1 env var. |
+| `COMPUTERNAME` | `src/services/tmux_common.rs:1136` |  |
+| `DATABASE_URL` | `src/db/postgres.rs:1138` |  |
+| `GEMINI_CLIENT_ID` | `src/server/mod.rs:1714` | env vars GEMINI_CLIENT_ID / GEMINI_CLIENT_SECRET 2. |
+| `GEMINI_CLIENT_SECRET` | `src/server/mod.rs:1715` | env vars GEMINI_CLIENT_ID / GEMINI_CLIENT_SECRET 2. |
+| `GEMINI_CLI_HOME` | `src/services/mcp_config.rs:665` |  |
+| `HOME` | `src/cli/doctor/orchestrator.rs:498` (+10 more) | #2655: handler for the `install-memento-session-hook` CLI surface. |
+| `HOSTNAME` | `src/server/mod.rs:3147` (+5 more) | Opens this turn's buffer and evicts whatever predecessor was left on this channel by a bridge exit that never reached post-loop finalize. |
+| `LOCALAPPDATA` | `src/services/platform/binary_resolver.rs:1114` (+2 more) |  |
+| `MEMENTO_WORKSPACE` | `src/server/routes/memory_api.rs:200` (+1 more) |  |
+| `OPENAI_API_KEY` | `src/server/mod.rs:1015` | --- Codex rate limits --- Priority: 1) ~/.codex/auth.json (Codex CLI subscription), 2) OPENAI_API_KEY |
+| `PATH` | `src/cli/doctor/orchestrator.rs:1686` (+5 more) | Resolve via PATH using `which` semantics — mirror the existing ProviderRuntime checks which simply call the binary with --version. |
+| `POSTGRES_TEST_ADMIN_DB` | `src/db/auto_queue/test_support.rs:16` (+4 more) |  |
+| `POSTGRES_TEST_DATABASE_URL_BASE` | `src/db/postgres.rs:1152` | Read the shared PG fixture base; required PG lanes must not silently turn a missing base into a soft-skip. |
+| `QWEN_CODE_SYSTEM_DEFAULTS_PATH` | `src/cli/doctor/orchestrator.rs:514` (+1 more) |  |
+| `QWEN_CODE_SYSTEM_SETTINGS_PATH` | `src/cli/doctor/orchestrator.rs:520` (+1 more) |  |
+| `QWEN_HOME` | `src/cli/doctor/orchestrator.rs:492` (+2 more) |  |
+| `REQUIRE_WAKE_WORD` | `src/voice/config.rs:103` | A live yaml with `wake_words: []` plus `REQUIRE_WAKE_WORD=1` would otherwise make EVERY utterance fail the (impossible-to-satisfy) gate and be silently dropped. |
+| `RUST_LOG` | `src/logging.rs:18` |  |
+| `SHELL` | `src/services/platform/binary_resolver.rs:1293` |  |
+| `USERPROFILE` | `src/cli/doctor/orchestrator.rs:502` (+6 more) |  |
+| `VOICE_AUDIO_DEBUG_DIR` | `src/voice/receiver.rs:72` |  |
diff --git a/scripts/ci-script-checks.sh b/scripts/ci-script-checks.sh
index 38e52a7081..8eab894056 100755
--- a/scripts/ci-script-checks.sh
+++ b/scripts/ci-script-checks.sh
@@ -413,7 +413,21 @@ echo "=== Generate inventory docs (refresh workspace; gate source-of-truth invar
 # Giant deadlines have one selector/evaluator. It refreshes inventories only
 # after its fail-closed main or strict PR-progress verdict succeeds.
 GFP_REFRESH_DOCS=1 "$PYTHON" scripts/giant_file_progress.py
-git diff --exit-code -- ARCHITECTURE.md docs/generated/route-inventory.md docs/generated/worker-inventory.md
+
+echo "=== Generate env + CLI reference docs (README source-of-truth tables) ==="
+# README links to these instead of carrying hand-written tables. Both
+# generators are pure source parsers (no cargo build), so they run on every
+# pass and share the tracked-doc drift gate below: regenerate, then fail the
+# PR when the committed docs/generated/*.md differ from the regenerated view.
+"$PYTHON" scripts/generate_env_reference.py
+"$PYTHON" scripts/generate_cli_reference.py
+"$PYTHON" -m unittest tests.test_generate_env_reference tests.test_generate_cli_reference
+git diff --exit-code -- \
+  ARCHITECTURE.md \
+  docs/generated/route-inventory.md \
+  docs/generated/worker-inventory.md \
+  docs/generated/env-reference.md \
+  docs/generated/cli-reference.md
 
 echo "=== Inventory prod/test split regression tests (#4394) ==="
 "$PYTHON" -m unittest tests.test_giant_file_progress tests.test_inventory_giant_split
diff --git a/scripts/generate_cli_reference.py b/scripts/generate_cli_reference.py
new file mode 100644
index 0000000000..53079b3902
--- /dev/null
+++ b/scripts/generate_cli_reference.py
@@ -0,0 +1,865 @@
+#!/usr/bin/env python3
+"""Generate ``docs/generated/cli-reference.md`` from the clap derive sources.
+
+The README used to carry a hand-written ``## CLI Reference`` block that
+drifted from ``src/cli/args.rs`` (missing subcommands, flags that no longer
+exist). This generator parses the ``#[derive(Parser | Subcommand | Args |
+ValueEnum)]`` items under ``src/`` and renders every command, nested
+subcommand, flag, and positional with the same names clap derives at runtime
+(kebab-case variant names, ``--field-name`` longs, ``<FIELD_NAME>`` value
+names, ``#[command(name = ...)]`` / ``#[arg(long = ...)]`` overrides).
+
+Parsing ``args.rs`` instead of dumping ``agentdesk --help`` keeps the check
+cheap enough to run on every CI pass without a cargo build. The clap unit
+tests in ``src/cli/args.rs`` (``top_level_command_name_snapshot_...``) pin the
+runtime name derivation; ``tests/test_generate_cli_reference.py`` asserts this
+generator reproduces that snapshot so the two cannot diverge silently.
+
+Test modules (``#[cfg(test)] mod``) are blanked before parsing; ``target/`` is
+never scanned. Commands are rendered in declaration order (the order
+``agentdesk --help`` prints) so the output is deterministic. CI regenerates
+the document and fails on ``git diff`` drift (``scripts/ci-script-checks.sh``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from generate_env_reference import (  # noqa: E402
+    blank_test_modules,
+    production_rust_files,
+    rel_posix,
+)
+from generate_inventory_docs import scan_balanced  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+OUTPUT_DOC = REPO_ROOT / "docs" / "generated" / "cli-reference.md"
+GENERATOR_COMMAND = "python3 scripts/generate_cli_reference.py"
+BINARY_NAME = "agentdesk"
+
+CLAP_DERIVES = ("Parser", "Subcommand", "Args", "ValueEnum")
+
+_DERIVE_RE = re.compile(r"#\[derive\((?P<list>[^)]*)\)\]")
+_ITEM_HEAD_RE = re.compile(
+    r"(?:pub(?:\([^)]*\))?\s+)?(?P<kind>enum|struct)\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*"
+)
+_IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_STRING_RE = re.compile(r'"((?:[^"\\]|\\.)*)"', re.DOTALL)
+
+
+class ParseError(RuntimeError):
+    pass
+
+
+# --------------------------------------------------------------------------- #
+# Lexical helpers
+# --------------------------------------------------------------------------- #
+
+
+def kebab_case(name: str) -> str:
+    """Mirror heck's ``to_kebab_case`` for the identifiers clap derives."""
+
+    words = re.findall(r"[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+", name)
+    return "-".join(word.lower() for word in words)
+
+
+def screaming_snake(name: str) -> str:
+    return name.upper()
+
+
+def unescape(text: str) -> str:
+    return (
+        text.replace('\\"', '"')
+        .replace("\\n", " ")
+        .replace("\\t", " ")
+        .replace("\\\\", "\\")
+    )
+
+
+def split_top_level_commas(text: str) -> list[str]:
+    parts: list[str] = []
+    depth = 0
+    last = 0
+    index = 0
+    while index < len(text):
+        ch = text[index]
+        if ch == '"':
+            match = _STRING_RE.match(text, index)
+            if match is None:
+                raise ParseError(f"unterminated string in attribute: {text!r}")
+            index = match.end()
+            continue
+        if ch == "'":
+            # char literal such as short = 'x'
+            index += 3 if index + 2 < len(text) and text[index + 2] == "'" else 1
+            continue
+        if ch in "([{<":
+            depth += 1
+        elif ch in ")]}>":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            parts.append(text[last:index].strip())
+            last = index + 1
+        index += 1
+    tail = text[last:].strip()
+    if tail:
+        parts.append(tail)
+    return parts
+
+
+def parse_attribute_args(inner: str) -> dict[str, str | bool]:
+    """Parse ``key = value, flag, key(value)`` attribute bodies."""
+
+    parsed: dict[str, str | bool] = {}
+    for part in split_top_level_commas(inner):
+        if not part:
+            continue
+        key, eq, value = part.partition("=")
+        key = key.strip()
+        if not eq:
+            paren = key.find("(")
+            if paren != -1:
+                parsed[key[:paren].strip()] = key[paren + 1 : -1].strip()
+            else:
+                parsed[key] = True
+            continue
+        value = value.strip()
+        match = _STRING_RE.fullmatch(value)
+        if match is not None:
+            parsed[key] = unescape(match.group(1))
+        elif value.startswith("'") and value.endswith("'") and len(value) == 3:
+            parsed[key] = value[1]
+        else:
+            parsed[key] = value
+    return parsed
+
+
+@dataclass
+class Attribute:
+    name: str
+    args: dict[str, str | bool]
+    raw: str
+
+
+@dataclass
+class Field:
+    name: str
+    type_text: str
+    docs: list[str]
+    attrs: list[Attribute]
+    line: int
+
+    def attr(self, name: str) -> dict[str, str | bool]:
+        merged: dict[str, str | bool] = {}
+        for attribute in self.attrs:
+            if attribute.name == name:
+                merged.update(attribute.args)
+        return merged
+
+
+@dataclass
+class Variant:
+    name: str
+    docs: list[str]
+    attrs: list[Attribute]
+    tuple_type: str | None
+    fields: list[Field]
+    line: int
+
+    def attr(self, name: str) -> dict[str, str | bool]:
+        merged: dict[str, str | bool] = {}
+        for attribute in self.attrs:
+            if attribute.name == name:
+                merged.update(attribute.args)
+        return merged
+
+
+@dataclass
+class Item:
+    kind: str  # enum | struct
+    name: str
+    derives: set[str]
+    docs: list[str]
+    attrs: list[Attribute]
+    path: str
+    line: int
+    variants: list[Variant] = field(default_factory=list)
+    fields: list[Field] = field(default_factory=list)
+
+    def attr(self, name: str) -> dict[str, str | bool]:
+        merged: dict[str, str | bool] = {}
+        for attribute in self.attrs:
+            if attribute.name == name:
+                merged.update(attribute.args)
+        return merged
+
+
+class Cursor:
+    """Small scanner over an item body (variants or struct fields)."""
+
+    def __init__(self, text: str, base_line: int) -> None:
+        self.text = text
+        self.index = 0
+        self.base_line = base_line
+
+    def line(self) -> int:
+        return self.base_line + self.text.count("\n", 0, self.index)
+
+    def skip_ws(self) -> None:
+        while self.index < len(self.text) and self.text[self.index].isspace():
+            self.index += 1
+
+    def at_end(self) -> bool:
+        self.skip_ws()
+        return self.index >= len(self.text)
+
+    def peek(self, literal: str) -> bool:
+        self.skip_ws()
+        return self.text.startswith(literal, self.index)
+
+    def take_docs_and_attrs(self) -> tuple[list[str], list[Attribute]]:
+        docs: list[str] = []
+        attrs: list[Attribute] = []
+        while True:
+            self.skip_ws()
+            if self.text.startswith("///", self.index):
+                end = self.text.find("\n", self.index)
+                end = len(self.text) if end == -1 else end
+                docs.append(self.text[self.index + 3 : end].strip())
+                self.index = end
+                continue
+            if self.text.startswith("//", self.index):
+                end = self.text.find("\n", self.index)
+                self.index = len(self.text) if end == -1 else end
+                continue
+            if self.text.startswith("#[", self.index):
+                inner, after = scan_balanced(self.text, self.index + 1, "[", "]")
+                self.index = after
+                match = _IDENT_RE.match(inner.strip())
+                if match is None:
+                    raise ParseError(f"unparseable attribute {inner!r}")
+                name = match.group(0)
+                rest = inner.strip()[match.end() :].strip()
+                args: dict[str, str | bool] = {}
+                if rest.startswith("(") and rest.endswith(")"):
+                    args = parse_attribute_args(rest[1:-1])
+                attrs.append(Attribute(name, args, inner.strip()))
+                continue
+            return docs, attrs
+
+    def take_ident(self) -> str:
+        self.skip_ws()
+        match = _IDENT_RE.match(self.text, self.index)
+        if match is None:
+            raise ParseError(
+                f"expected identifier at line {self.line()}: {self.text[self.index:self.index + 40]!r}"
+            )
+        self.index = match.end()
+        return match.group(0)
+
+    def take_balanced(self, open_char: str, close_char: str) -> str:
+        self.skip_ws()
+        inner, after = scan_balanced(self.text, self.index, open_char, close_char)
+        self.index = after
+        return inner
+
+    def take_type(self) -> str:
+        """Consume a type expression up to the next top-level ``,``."""
+
+        self.skip_ws()
+        depth = 0
+        start = self.index
+        while self.index < len(self.text):
+            ch = self.text[self.index]
+            if ch in "<([":
+                depth += 1
+            elif ch in ">)]":
+                depth -= 1
+            elif ch == "," and depth == 0:
+                break
+            self.index += 1
+        return " ".join(self.text[start : self.index].split())
+
+    def take_comma(self) -> None:
+        self.skip_ws()
+        if self.index < len(self.text) and self.text[self.index] == ",":
+            self.index += 1
+
+
+def parse_fields(body: str, base_line: int) -> list[Field]:
+    cursor = Cursor(body, base_line)
+    fields: list[Field] = []
+    while not cursor.at_end():
+        docs, attrs = cursor.take_docs_and_attrs()
+        if cursor.at_end():
+            break
+        line = cursor.line()
+        name = cursor.take_ident()
+        if name == "pub":
+            if cursor.peek("("):
+                cursor.take_balanced("(", ")")
+            name = cursor.take_ident()
+        cursor.skip_ws()
+        if not cursor.peek(":"):
+            raise ParseError(f"expected ':' after field {name} at line {line}")
+        cursor.index += 1
+        type_text = cursor.take_type()
+        cursor.take_comma()
+        fields.append(Field(name, type_text, docs, attrs, line))
+    return fields
+
+
+def parse_variants(body: str, base_line: int) -> list[Variant]:
+    cursor = Cursor(body, base_line)
+    variants: list[Variant] = []
+    while not cursor.at_end():
+        docs, attrs = cursor.take_docs_and_attrs()
+        if cursor.at_end():
+            break
+        line = cursor.line()
+        name = cursor.take_ident()
+        tuple_type: str | None = None
+        fields: list[Field] = []
+        if cursor.peek("("):
+            tuple_type = " ".join(cursor.take_balanced("(", ")").split())
+        elif cursor.peek("{"):
+            cursor.skip_ws()
+            field_line = cursor.line()
+            fields = parse_fields(cursor.take_balanced("{", "}"), field_line)
+        cursor.take_comma()
+        variants.append(Variant(name, docs, attrs, tuple_type, fields, line))
+    return variants
+
+
+def collect_items() -> dict[str, Item]:
+    items: dict[str, Item] = {}
+    for path in production_rust_files():
+        text = blank_test_modules(path.read_text(encoding="utf-8"))
+        if not any(f"{derive}" in text for derive in CLAP_DERIVES):
+            continue
+        for match in _DERIVE_RE.finditer(text):
+            derives = {part.strip() for part in match.group("list").split(",")}
+            if not derives & set(CLAP_DERIVES):
+                continue
+            # Walk backwards over docs; forwards over sibling attributes to
+            # the item head.
+            head_cursor = Cursor(text, 1)
+            head_cursor.index = match.end()
+            _docs_after, attrs_after = head_cursor.take_docs_and_attrs()
+            head = _ITEM_HEAD_RE.match(text, head_cursor.index)
+            if head is None:
+                continue
+            docs, attrs_before = _docs_and_attrs_before(text, match.start())
+            attrs = attrs_before + attrs_after
+            kind = head.group("kind")
+            name = head.group("name")
+            body_open = head.end()
+            if body_open >= len(text) or text[body_open] != "{":
+                continue
+            body, _after = scan_balanced(text, body_open, "{", "}")
+            body_line = text.count("\n", 0, body_open) + 1
+            item = Item(
+                kind=kind,
+                name=name,
+                derives=derives & set(CLAP_DERIVES),
+                docs=docs,
+                attrs=attrs,
+                path=rel_posix(path),
+                line=text.count("\n", 0, head.start()) + 1,
+            )
+            if kind == "enum":
+                item.variants = parse_variants(body, body_line)
+            else:
+                item.fields = parse_fields(body, body_line)
+            if name in items:
+                raise ParseError(
+                    f"duplicate clap item name {name} in {item.path} and {items[name].path}"
+                )
+            items[name] = item
+    return items
+
+
+def _docs_and_attrs_before(text: str, offset: int) -> tuple[list[str], list[Attribute]]:
+    """Collect ``///`` docs and ``#[...]`` attributes directly above ``offset``."""
+
+    lines = text[:offset].splitlines()
+    docs: list[str] = []
+    attrs: list[Attribute] = []
+    cursor = len(lines) - 1
+    while cursor >= 0:
+        stripped = lines[cursor].strip()
+        if stripped.startswith("///"):
+            docs.append(stripped[3:].strip())
+        elif stripped.startswith("#[") and stripped.endswith("]"):
+            inner = stripped[2:-1]
+            match = _IDENT_RE.match(inner)
+            if match is None:
+                break
+            rest = inner[match.end() :].strip()
+            args = parse_attribute_args(rest[1:-1]) if rest.startswith("(") else {}
+            attrs.append(Attribute(match.group(0), args, inner))
+        elif stripped.startswith("//") or not stripped:
+            pass
+        else:
+            break
+        cursor -= 1
+    docs.reverse()
+    attrs.reverse()
+    return docs, attrs
+
+
+# --------------------------------------------------------------------------- #
+# clap semantics
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class ArgSpec:
+    display: str  # e.g. `--channel <CHANNEL>` or `<PATH>`
+    value: str  # value type / enum choices
+    default: str
+    description: str
+    positional: bool
+    required: bool
+
+
+@dataclass
+class CommandSpec:
+    path: list[str]
+    summary: str
+    long_about: str
+    after_help: str
+    notes: list[str]
+    args: list[ArgSpec]
+    subcommands: list["CommandSpec"]
+    subcommand_optional: bool
+    source: str
+
+
+def strip_generic(type_text: str, wrapper: str) -> str | None:
+    if type_text.startswith(wrapper + "<") and type_text.endswith(">"):
+        return type_text[len(wrapper) + 1 : -1].strip()
+    return None
+
+
+def last_segment(path: str) -> str:
+    return path.split("::")[-1].strip()
+
+
+def doc_summary(docs: list[str]) -> tuple[str, str]:
+    """Split clap-style docs into (first paragraph, remaining paragraphs)."""
+
+    paragraphs: list[list[str]] = [[]]
+    for line in docs:
+        if not line.strip():
+            if paragraphs[-1]:
+                paragraphs.append([])
+            continue
+        paragraphs[-1].append(line.strip())
+    joined = [" ".join(paragraph) for paragraph in paragraphs if paragraph]
+    if not joined:
+        return "", ""
+    return joined[0], " ".join(joined[1:])
+
+
+class Renderer:
+    def __init__(self, items: dict[str, Item]) -> None:
+        self.items = items
+        self.consts = _collect_str_consts()
+
+    def value_enum_choices(self, type_name: str) -> list[str] | None:
+        item = self.items.get(last_segment(type_name))
+        if item is None or "ValueEnum" not in item.derives:
+            return None
+        choices: list[str] = []
+        for variant in item.variants:
+            value_attr = variant.attr("value")
+            if value_attr.get("skip"):
+                continue
+            name = value_attr.get("name")
+            choices.append(str(name) if isinstance(name, str) else kebab_case(variant.name))
+        return choices
+
+    def resolve_help(self, expr: str) -> str:
+        const = self.consts.get(last_segment(expr))
+        if const is not None:
+            return const
+        return f"(see `{expr}`)"
+
+    def build_args(self, fields: list[Field], args: list[ArgSpec]) -> tuple[str | None, bool]:
+        """Append argument specs; return (subcommand enum type, optional?)."""
+
+        subcommand_type: str | None = None
+        subcommand_optional = False
+        for field_ in fields:
+            command_attr = field_.attr("command")
+            if command_attr.get("subcommand"):
+                inner = strip_generic(field_.type_text, "Option")
+                subcommand_optional = inner is not None
+                subcommand_type = inner or field_.type_text
+                continue
+            if command_attr.get("flatten"):
+                nested = self.items.get(last_segment(field_.type_text))
+                if nested is None:
+                    raise ParseError(f"unknown flattened Args type {field_.type_text}")
+                nested_sub, nested_opt = self.build_args(nested.fields, args)
+                if nested_sub is not None:
+                    subcommand_type, subcommand_optional = nested_sub, nested_opt
+                continue
+            args.append(self.arg_spec(field_))
+        return subcommand_type, subcommand_optional
+
+    def arg_spec(self, field_: Field) -> ArgSpec:
+        arg = field_.attr("arg")
+        type_text = field_.type_text
+        optional = False
+        repeatable = False
+        inner = strip_generic(type_text, "Option")
+        if inner is not None:
+            optional = True
+            type_text = inner
+        inner = strip_generic(type_text, "Vec")
+        if inner is not None:
+            repeatable = True
+            type_text = inner
+
+        arg_id = str(arg["id"]) if isinstance(arg.get("id"), str) else field_.name
+        value_name = (
+            str(arg["value_name"])
+            if isinstance(arg.get("value_name"), str)
+            else screaming_snake(arg_id)
+        )
+        action = str(arg.get("action", ""))
+        is_flag = type_text == "bool" and "Set" not in action
+        is_count = "Count" in action
+
+        long_name: str | None = None
+        if "long" in arg:
+            long_name = str(arg["long"]) if isinstance(arg["long"], str) else kebab_case(field_.name)
+        short_name: str | None = None
+        if "short" in arg:
+            short_name = str(arg["short"]) if isinstance(arg["short"], str) else field_.name[0]
+
+        choices = self.value_enum_choices(type_text) if arg.get("value_enum") else None
+        if choices is None and type_text == "bool" and not is_flag:
+            choices = ["true", "false"]
+
+        if choices is not None:
+            value = "`" + "`, `".join(choices) + "`"
+        elif is_flag or is_count:
+            value = "flag"
+        else:
+            value = f"`{type_text}`"
+        if repeatable:
+            value += " (repeatable)"
+
+        default = ""
+        if "default_value" in arg:
+            default = f"`{arg['default_value']}`"
+        elif "default_value_t" in arg:
+            raw = str(arg["default_value_t"])
+            if choices is not None and "::" in raw:
+                default = f"`{kebab_case(last_segment(raw))}`"
+            else:
+                default = f"`{raw}`"
+
+        # clap derive: a non-Option, non-Vec, non-bool field without a default
+        # is required; `Vec<T>` and `Option<T>` are optional unless
+        # `required = true` is spelled out.
+        required = bool(arg.get("required")) or (
+            not optional and not repeatable and not is_flag and not is_count and not default
+        )
+
+        positional = long_name is None and short_name is None
+        if positional:
+            display = f"<{value_name}>" if required else f"[{value_name}]"
+            if repeatable:
+                display += "..."
+        else:
+            flags = []
+            if short_name:
+                flags.append(f"-{short_name}")
+            if long_name:
+                flags.append(f"--{long_name}")
+            display = ", ".join(flags)
+            if not is_flag and not is_count:
+                display += f" <{value_name}>"
+            if repeatable:
+                display += "..."
+
+        summary, rest = doc_summary(field_.docs)
+        if isinstance(arg.get("help"), str):
+            help_text = str(arg["help"])
+            if _STRING_RE.fullmatch('"' + help_text + '"') is None or "::" in help_text:
+                help_text = self.resolve_help(help_text)
+            summary = help_text
+        description = summary
+        if rest:
+            description = f"{summary} {rest}"
+        notes: list[str] = []
+        if isinstance(arg.get("alias"), str):
+            notes.append(f"alias `--{arg['alias']}`")
+        if isinstance(arg.get("visible_alias"), str):
+            notes.append(f"alias `--{arg['visible_alias']}`")
+        if arg.get("global"):
+            notes.append("accepted before or after the subcommand")
+        if arg.get("last"):
+            notes.append("after `--`")
+        if isinstance(arg.get("conflicts_with"), str):
+            notes.append(f"conflicts with `{arg['conflicts_with']}`")
+        if isinstance(arg.get("env"), str):
+            notes.append(f"env `{arg['env']}`")
+        if notes:
+            description = f"{description} ({'; '.join(notes)})" if description else "; ".join(notes)
+        return ArgSpec(display, value, default, description, positional, required)
+
+    def command_from_variant(self, variant: Variant, parent: list[str]) -> CommandSpec | None:
+        for attribute in variant.attrs:
+            if attribute.name == "cfg" and "test" in attribute.raw:
+                return None
+        command_attr = variant.attr("command")
+        name = str(command_attr["name"]) if isinstance(command_attr.get("name"), str) else kebab_case(variant.name)
+        summary, long_about = doc_summary(variant.docs)
+        if isinstance(command_attr.get("about"), str):
+            summary = str(command_attr["about"])
+        notes: list[str] = []
+        if command_attr.get("hide"):
+            notes.append("hidden from `--help`")
+        for attribute in variant.attrs:
+            if attribute.name == "cfg":
+                notes.append(f"`#[{attribute.raw}]`")
+        for key in ("alias", "visible_alias"):
+            if isinstance(command_attr.get(key), str):
+                notes.append(f"alias `{command_attr[key]}`")
+        after_help = str(command_attr["after_help"]) if isinstance(command_attr.get("after_help"), str) else ""
+        if after_help.startswith("Deprecated"):
+            notes.insert(0, "deprecated")
+
+        args: list[ArgSpec] = []
+        fields = variant.fields
+        if variant.tuple_type is not None:
+            nested = self.items.get(last_segment(variant.tuple_type))
+            if nested is None:
+                raise ParseError(f"unknown Args type {variant.tuple_type} for {variant.name}")
+            fields = nested.fields
+        subcommand_type, subcommand_optional = self.build_args(fields, args)
+        path = parent + [name]
+        subcommands: list[CommandSpec] = []
+        if subcommand_type is not None:
+            subcommands = self.commands_from_enum(subcommand_type, path)
+        return CommandSpec(
+            path=path,
+            summary=summary,
+            long_about=long_about,
+            after_help=after_help,
+            notes=notes,
+            args=args,
+            subcommands=subcommands,
+            subcommand_optional=subcommand_optional,
+            source=f"{self.items[last_segment(variant.tuple_type)].path if variant.tuple_type else ''}",
+        )
+
+    def commands_from_enum(self, type_name: str, parent: list[str]) -> list[CommandSpec]:
+        item = self.items.get(last_segment(type_name))
+        if item is None or "Subcommand" not in item.derives:
+            raise ParseError(f"unknown Subcommand enum {type_name}")
+        commands: list[CommandSpec] = []
+        for variant in item.variants:
+            command = self.command_from_variant(variant, parent)
+            if command is not None:
+                command.source = f"{item.path}:{variant.line}"
+                commands.append(command)
+        return commands
+
+    def root(self) -> tuple[Item, list[ArgSpec], list[CommandSpec]]:
+        parsers = [item for item in self.items.values() if "Parser" in item.derives]
+        if len(parsers) != 1:
+            raise ParseError(f"expected exactly one #[derive(Parser)] item, found {len(parsers)}")
+        parser = parsers[0]
+        args: list[ArgSpec] = []
+        subcommand_type, _optional = self.build_args(parser.fields, args)
+        if subcommand_type is None:
+            raise ParseError("root Parser has no #[command(subcommand)] field")
+        return parser, args, self.commands_from_enum(subcommand_type, [])
+
+
+def _collect_str_consts() -> dict[str, str]:
+    """``pub const NAME: &str = "..."`` literals used as ``help = path::NAME``."""
+
+    pattern = re.compile(
+        r"const\s+(?P<ident>[A-Z][A-Z0-9_]*)\s*:\s*&(?:'static\s+)?str\s*=\s*\"(?P<value>(?:[^\"\\]|\\.)*)\""
+    )
+    consts: dict[str, str] = {}
+    for path in production_rust_files():
+        if "cli" not in path.parts and "discord" not in path.parts:
+            continue
+        text = blank_test_modules(path.read_text(encoding="utf-8"))
+        for match in pattern.finditer(text):
+            consts.setdefault(match.group("ident"), unescape(match.group("value")))
+    return consts
+
+
+# --------------------------------------------------------------------------- #
+# Markdown rendering
+# --------------------------------------------------------------------------- #
+
+
+def markdown_cell(text: str) -> str:
+    return " ".join(text.replace("|", "\\|").split())
+
+
+def usage_line(command: CommandSpec) -> str:
+    parts = [BINARY_NAME, *command.path]
+    if command.subcommands:
+        parts.append("[COMMAND]" if command.subcommand_optional else "<COMMAND>")
+    options = [arg for arg in command.args if not arg.positional]
+    if options:
+        parts.append("[OPTIONS]")
+    for arg in command.args:
+        if arg.positional:
+            parts.append(arg.display)
+    return " ".join(parts)
+
+
+def flatten(commands: list[CommandSpec]) -> list[CommandSpec]:
+    ordered: list[CommandSpec] = []
+    for command in commands:
+        ordered.append(command)
+        ordered.extend(flatten(command.subcommands))
+    return ordered
+
+
+def render_args_table(args: list[ArgSpec]) -> list[str]:
+    lines = ["| Argument | Value | Default | Description |", "|---|---|---|---|"]
+    for arg in args:
+        display = f"`{arg.display}`"
+        if arg.required and not arg.positional:
+            display += " (required)"
+        lines.append(
+            f"| {display} | {markdown_cell(arg.value)} | {markdown_cell(arg.default)} | {markdown_cell(arg.description)} |"
+        )
+    return lines
+
+
+def render_command(command: CommandSpec) -> list[str]:
+    depth = min(len(command.path), 4)
+    heading = "#" * (depth + 1)
+    lines = [f"{heading} `{BINARY_NAME} {' '.join(command.path)}`", ""]
+    if command.summary:
+        lines.append(command.summary)
+        lines.append("")
+    if command.long_about:
+        lines.append(command.long_about)
+        lines.append("")
+    if command.notes:
+        lines.append("Notes: " + "; ".join(command.notes) + ".")
+        lines.append("")
+    lines.append(f"Usage: `{usage_line(command)}`")
+    lines.append("")
+    if command.args:
+        lines.extend(render_args_table(command.args))
+        lines.append("")
+    if command.subcommands:
+        lines.append("Subcommands:")
+        lines.append("")
+        for sub in command.subcommands:
+            lines.append(f"- `{sub.path[-1]}` — {sub.summary}" if sub.summary else f"- `{sub.path[-1]}`")
+        lines.append("")
+    if command.after_help:
+        lines.append(f"> {command.after_help}")
+        lines.append("")
+    for sub in command.subcommands:
+        lines.extend(render_command(sub))
+    return lines
+
+
+def render(parser: Item, global_args: list[ArgSpec], commands: list[CommandSpec]) -> str:
+    command_attr = parser.attr("command")
+    about = str(command_attr.get("about", "")) if isinstance(command_attr.get("about"), str) else ""
+    all_commands = flatten(commands)
+    lines = [
+        "# CLI Reference",
+        "",
+        f"<!-- Generated by `{GENERATOR_COMMAND}`. Do not edit by hand. -->",
+        "",
+        f"`{BINARY_NAME}` — {about}" if about else f"`{BINARY_NAME}`",
+        "",
+        f"Derived from the clap definitions in `{parser.path}` (and the `Args` /",
+        "`Subcommand` types it references). Commands are listed in declaration",
+        "order, matching `agentdesk --help`. Running `agentdesk` with no",
+        "subcommand starts the server.",
+        "",
+        f"Regenerate with `{GENERATOR_COMMAND}`; CI fails when this file drifts.",
+        "",
+        f"- Top-level commands: {len(commands)}",
+        f"- Commands including nested subcommands: {len(all_commands)}",
+        "",
+        "## Global options",
+        "",
+        *render_args_table(
+            global_args
+            + [
+                ArgSpec("-h, --help", "flag", "", "Print help", False, False),
+                ArgSpec("-V, --version", "flag", "", "Print version", False, False),
+            ]
+        ),
+        "",
+        "## Command index",
+        "",
+        "| Command | Summary | Notes |",
+        "|---|---|---|",
+    ]
+    for command in all_commands:
+        anchor = "-".join([BINARY_NAME, *command.path])
+        lines.append(
+            f"| [`{BINARY_NAME} {' '.join(command.path)}`](#{anchor}) | {markdown_cell(command.summary)} | {markdown_cell('; '.join(command.notes))} |"
+        )
+    lines.append("")
+    lines.append("## Commands")
+    lines.append("")
+    for command in commands:
+        lines.extend(render_command(command))
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def generate() -> tuple[str, list[CommandSpec]]:
+    renderer = Renderer(collect_items())
+    parser, global_args, commands = renderer.root()
+    return render(parser, global_args, commands), commands
+
+
+def main(argv: list[str] | None = None) -> int:
+    arg_parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    arg_parser.add_argument(
+        "--output",
+        type=Path,
+        default=OUTPUT_DOC,
+        help="destination markdown path (default: docs/generated/cli-reference.md)",
+    )
+    arg_parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="print the rendered document instead of writing it",
+    )
+    args = arg_parser.parse_args(argv)
+    rendered, commands = generate()
+    if args.stdout:
+        sys.stdout.write(rendered)
+        return 0
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(rendered, encoding="utf-8")
+    print(
+        f"wrote {args.output.relative_to(REPO_ROOT).as_posix()}: "
+        f"{len(commands)} top-level commands, {len(flatten(commands))} including nested"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/generate_env_reference.py b/scripts/generate_env_reference.py
new file mode 100644
index 0000000000..c8990f6894
--- /dev/null
+++ b/scripts/generate_env_reference.py
@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+"""Generate ``docs/generated/env-reference.md`` from the Rust sources.
+
+The README used to carry a hand-written environment-variable table that
+drifted from the code (a dozen rows against 100+ variables actually read, plus
+rows for variables nothing reads). This generator derives the table from
+``src/`` so the reference cannot drift silently:
+
+* ``env::var("NAME")`` / ``env::var_os("NAME")`` / ``std::env::var(...)`` read
+  sites with a literal name.
+* ``const FOO_ENV: &str = "AGENTDESK_..."`` style name constants (``AGENTDESK_``
+  and ``ADK_`` prefixes), including the indirect reads that pass such a
+  constant to ``env::var``.
+* ``some_env_helper("AGENTDESK_...")`` calls — helper functions whose name
+  contains ``env`` and that take the literal name as an argument.
+* ``tracing_subscriber::EnvFilter::from_default_env()`` (reads ``RUST_LOG``)
+  and ``EnvFilter::from_env("NAME")``.
+
+The one-line description comes, in order of preference, from a comment in the
+same file that names the variable (nearest to the site), the comment adjacent
+to the site, or the doc comment of the enclosing ``fn``.
+
+Test-only code is excluded: ``tests.rs`` / ``integration_tests.rs`` modules,
+``src/**/tests/`` directories, and ``#[cfg(test)] mod ... { ... }`` blocks
+(blanked in place so line numbers stay stable). ``target/`` is never scanned.
+
+Output is deterministic: files are visited in sorted order, rows are sorted by
+variable name, and the description is a single sentence chosen by a fixed
+preference order. CI regenerates the document and fails on ``git diff`` drift
+(see ``scripts/ci-script-checks.sh``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from generate_inventory_docs import (  # noqa: E402
+    _CFG_MOD_RE,
+    cfg_requires_test,
+    is_test_file,
+    scan_balanced,
+)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SRC_ROOT = REPO_ROOT / "src"
+OUTPUT_DOC = REPO_ROOT / "docs" / "generated" / "env-reference.md"
+GENERATOR_COMMAND = "python3 scripts/generate_env_reference.py"
+
+PROJECT_PREFIXES = ("AGENTDESK_", "ADK_")
+ENV_NAME = r"[A-Z][A-Z0-9_]*"
+MAX_DESCRIPTION_CHARS = 160
+
+# `env::var("NAME")`, `env::var_os("NAME")`, `std::env::var("NAME")`.
+_LITERAL_READ_RE = re.compile(
+    r"(?<![A-Za-z0-9_])(?:std::)?env::var(?:_os)?\(\s*\"(?P<name>" + ENV_NAME + r")\""
+)
+# `env::var(SOME_CONST)` — resolved through the constant table below.
+_CONST_READ_RE = re.compile(
+    r"(?<![A-Za-z0-9_])(?:std::)?env::var(?:_os)?\(\s*(?P<ident>[A-Z][A-Z0-9_]*)\s*\)"
+)
+# `const FOO: &str = "AGENTDESK_..."` (also `pub`, `pub(crate)`, `static`,
+# `&'static str`; the literal may sit on the next line after a rustfmt wrap).
+_CONST_DEF_RE = re.compile(
+    r"(?:pub(?:\([^)]*\))?\s+)?(?:const|static)\s+(?P<ident>[A-Z][A-Z0-9_]*)\s*:\s*&(?:'static\s+)?str\s*=\s*\"(?P<name>(?:AGENTDESK|ADK)_[A-Z0-9_]*)\""
+)
+# `explicit_env_path("AGENTDESK_X")`, `migrated_env_path("AGENTDESK_X")`, ...
+_HELPER_READ_RE = re.compile(
+    r"(?<![A-Za-z0-9_])(?P<helper>[a-z_]*env[a-z_]*)\(\s*[^()\"]*?\"(?P<name>(?:AGENTDESK|ADK)_[A-Z0-9_]*)\""
+)
+_HELPER_EXCLUDE = {"set_var", "remove_var", "env_remove", "env"}
+# `tracing_subscriber::EnvFilter::from_default_env()` reads `RUST_LOG` without
+# naming it; `EnvFilter::from_env("NAME")` names its variable explicitly.
+_ENV_FILTER_DEFAULT_RE = re.compile(r"EnvFilter::(?:try_)?from_default_env\(")
+_ENV_FILTER_NAMED_RE = re.compile(
+    r"EnvFilter::(?:try_)?from_env\(\s*\"(?P<name>" + ENV_NAME + r")\""
+)
+ENV_FILTER_DEFAULT_VARIABLE = "RUST_LOG"
+
+
+class ParseError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True, order=True)
+class Site:
+    path: str
+    line: int
+    kind: str  # "const" | "read" | "helper"
+    comment: str = field(compare=False, default="")
+
+
+@dataclass
+class Variable:
+    name: str
+    sites: list[Site] = field(default_factory=list)
+
+    @property
+    def is_project_variable(self) -> bool:
+        return self.name.startswith(PROJECT_PREFIXES)
+
+    def primary_site(self) -> Site:
+        consts = sorted(site for site in self.sites if site.kind == "const")
+        if consts:
+            return consts[0]
+        return sorted(self.sites)[0]
+
+    def description(self) -> str:
+        ordered = sorted(self.sites)
+        candidates = [site.comment for site in ordered if site.comment]
+        if not candidates:
+            return ""
+        for comment in candidates:
+            if self.name in comment:
+                return comment
+        for comment in candidates:
+            if re.search(r"\benv(?:ironment)?\b", comment, re.IGNORECASE):
+                return comment
+        primary = self.primary_site()
+        return primary.comment or candidates[0]
+
+
+def rel_posix(path: Path) -> str:
+    return path.relative_to(REPO_ROOT).as_posix()
+
+
+def production_rust_files() -> list[Path]:
+    files: list[Path] = []
+    for path in sorted(SRC_ROOT.rglob("*.rs")):
+        rel = path.relative_to(SRC_ROOT)
+        if "target" in rel.parts:
+            continue
+        if "tests" in rel.parts[:-1]:
+            continue
+        if is_test_file(path):
+            continue
+        files.append(path)
+    return files
+
+
+def blank_test_modules(text: str) -> str:
+    """Replace ``#[cfg(test)] mod x { ... }`` bodies with newlines.
+
+    Line numbers of the surrounding code are preserved because every removed
+    character that is not a newline is dropped while newlines are kept.
+    """
+
+    result: list[str] = []
+    cursor = 0
+    for match in _CFG_MOD_RE.finditer(text):
+        if match.start() < cursor:
+            continue
+        if not cfg_requires_test(match.group("predicate")):
+            continue
+        open_index = match.end() - 1
+        try:
+            _body, close_index = scan_balanced(text, open_index, "{", "}")
+        except Exception as error:  # pragma: no cover - defensive
+            raise ParseError(f"unbalanced test module at offset {open_index}: {error}") from error
+        result.append(text[cursor : match.start()])
+        # ``scan_balanced`` returns the index just past the closing brace.
+        removed = text[match.start() : close_index]
+        result.append("\n" * removed.count("\n"))
+        cursor = close_index
+    result.append(text[cursor:])
+    return "".join(result)
+
+
+def _clean_comment_line(line: str) -> str:
+    stripped = line.strip()
+    for prefix in ("///", "//!", "//"):
+        if stripped.startswith(prefix):
+            stripped = stripped[len(prefix) :]
+            break
+    return " ".join(stripped.split())
+
+
+_FN_LINE_RE = re.compile(r"^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:extern\s+\"C\"\s+)?fn\s")
+
+
+def _comment_block_above(lines: list[str], index: int) -> str:
+    """Join the contiguous ``//`` comment block ending right above ``index``.
+
+    Attribute lines (``#[...]``) between the block and the statement are
+    skipped so ``/// doc`` + ``#[arg]`` + ``field`` still resolves the doc.
+    """
+
+    cursor = index - 1
+    while cursor >= 0 and lines[cursor].strip().startswith("#["):
+        cursor -= 1
+    block: list[str] = []
+    while cursor >= 0:
+        stripped = lines[cursor].strip()
+        if stripped.startswith("//"):
+            block.append(_clean_comment_line(stripped))
+            cursor -= 1
+            continue
+        break
+    block.reverse()
+    return " ".join(text for text in block if text)
+
+
+def _trailing_comment(line: str) -> str:
+    code, _, trailing = line.partition("//")
+    if trailing and '"' not in trailing and code.strip():
+        return _clean_comment_line("//" + trailing)
+    return ""
+
+
+def _sentence_mentioning(text: str, name: str) -> str:
+    for sentence in re.split(r"(?<=[.!?])\s+", text):
+        if name in sentence:
+            return sentence
+    return first_sentence(text)
+
+
+def _nearest_mention(lines: list[str], index: int, name: str) -> str:
+    """Nearest comment line in the file that names the variable."""
+
+    best: tuple[int, int] | None = None
+    for cursor, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped.startswith("//"):
+            continue
+        if name not in _clean_comment_line(stripped):
+            continue
+        distance = abs(cursor - index)
+        if best is None or distance < best[0]:
+            best = (distance, cursor)
+    if best is None:
+        return ""
+    # Expand to the contiguous comment block around the hit and pick the
+    # sentence that mentions the variable.
+    top = best[1]
+    while top > 0 and lines[top - 1].strip().startswith("//"):
+        top -= 1
+    bottom = best[1]
+    while bottom + 1 < len(lines) and lines[bottom + 1].strip().startswith("//"):
+        bottom += 1
+    joined = " ".join(
+        text for text in (_clean_comment_line(lines[i]) for i in range(top, bottom + 1)) if text
+    )
+    return _sentence_mentioning(joined, name)
+
+
+def _enclosing_fn_doc(lines: list[str], index: int) -> str:
+    cursor = index
+    while cursor >= 0:
+        if _FN_LINE_RE.match(lines[cursor]):
+            return _comment_block_above(lines, cursor)
+        cursor -= 1
+    return ""
+
+
+def describe_site(lines: list[str], line_number: int, name: str) -> str:
+    """Return a one-line description for the variable read at ``line_number``.
+
+    Preference: a comment in the same file that names the variable (nearest to
+    the site), then the trailing/preceding comment adjacent to the site, then
+    the doc comment of the enclosing ``fn``. Only one sentence is kept so the
+    table stays one row per variable.
+    """
+
+    index = line_number - 1
+    mention = _nearest_mention(lines, index, name)
+    if mention:
+        return truncate(mention)
+    trailing = _trailing_comment(lines[index])
+    if trailing:
+        return truncate(first_sentence(trailing))
+    above = _comment_block_above(lines, index)
+    if above:
+        return truncate(first_sentence(above))
+    fn_doc = _enclosing_fn_doc(lines, index)
+    if fn_doc:
+        return truncate(first_sentence(fn_doc))
+    return ""
+
+
+def first_sentence(text: str) -> str:
+    match = re.search(r"[.!?](?:\s|$)", text)
+    if match is None:
+        return text
+    return text[: match.start() + 1]
+
+
+def truncate(text: str) -> str:
+    if len(text) <= MAX_DESCRIPTION_CHARS:
+        return text
+    return text[: MAX_DESCRIPTION_CHARS - 1].rstrip() + "…"
+
+
+def offset_to_line(text: str, offset: int) -> int:
+    return text.count("\n", 0, offset) + 1
+
+
+def collect_variables(files: list[Path]) -> dict[str, Variable]:
+    variables: dict[str, Variable] = {}
+    # Constant identifiers are resolved per file first (a const is almost
+    # always used in the module that defines it), then crate-wide.
+    per_file_consts: dict[Path, dict[str, str]] = {}
+    global_consts: dict[str, str] = {}
+    texts: dict[Path, str] = {}
+
+    def add(name: str, site: Site) -> None:
+        variables.setdefault(name, Variable(name)).sites.append(site)
+
+    for path in files:
+        text = blank_test_modules(path.read_text(encoding="utf-8"))
+        texts[path] = text
+        lines = text.splitlines()
+        consts: dict[str, str] = {}
+        rel = rel_posix(path)
+        for match in _CONST_DEF_RE.finditer(text):
+            line = offset_to_line(text, match.start())
+            consts[match.group("ident")] = match.group("name")
+            add(match.group("name"), Site(rel, line, "const", describe_site(lines, line, match.group("name"))))
+        per_file_consts[path] = consts
+        for ident, name in consts.items():
+            global_consts.setdefault(ident, name)
+
+    for path in files:
+        text = texts[path]
+        lines = text.splitlines()
+        rel = rel_posix(path)
+        for match in _LITERAL_READ_RE.finditer(text):
+            line = offset_to_line(text, match.start())
+            add(match.group("name"), Site(rel, line, "read", describe_site(lines, line, match.group("name"))))
+        for match in _CONST_READ_RE.finditer(text):
+            ident = match.group("ident")
+            name = per_file_consts[path].get(ident) or global_consts.get(ident)
+            if name is None:
+                continue
+            line = offset_to_line(text, match.start())
+            add(name, Site(rel, line, "read", describe_site(lines, line, name)))
+        for match in _HELPER_READ_RE.finditer(text):
+            if match.group("helper") in _HELPER_EXCLUDE:
+                continue
+            line = offset_to_line(text, match.start())
+            add(match.group("name"), Site(rel, line, "helper", describe_site(lines, line, match.group("name"))))
+        for match in _ENV_FILTER_DEFAULT_RE.finditer(text):
+            line = offset_to_line(text, match.start())
+            add(
+                ENV_FILTER_DEFAULT_VARIABLE,
+                Site(rel, line, "helper", describe_site(lines, line, ENV_FILTER_DEFAULT_VARIABLE)),
+            )
+        for match in _ENV_FILTER_NAMED_RE.finditer(text):
+            line = offset_to_line(text, match.start())
+            add(match.group("name"), Site(rel, line, "helper", describe_site(lines, line, match.group("name"))))
+
+    for variable in variables.values():
+        variable.sites = sorted(set(variable.sites))
+    return variables
+
+
+def markdown_cell(text: str) -> str:
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def render_table(variables: list[Variable]) -> list[str]:
+    lines = ["| Variable | Defined at | Description |", "|---|---|---|"]
+    for variable in variables:
+        site = variable.primary_site()
+        extra = len(variable.sites) - 1
+        location = f"`{site.path}:{site.line}`"
+        if extra > 0:
+            location += f" (+{extra} more)"
+        lines.append(
+            f"| `{variable.name}` | {location} | {markdown_cell(variable.description())} |"
+        )
+    return lines
+
+
+def render(variables: dict[str, Variable]) -> str:
+    ordered = sorted(variables.values(), key=lambda variable: variable.name)
+    project = [variable for variable in ordered if variable.is_project_variable]
+    external = [variable for variable in ordered if not variable.is_project_variable]
+    lines = [
+        "# Environment Variable Reference",
+        "",
+        f"<!-- Generated by `{GENERATOR_COMMAND}`. Do not edit by hand. -->",
+        "",
+        "Environment variables read by the AgentDesk binary, derived from `src/`.",
+        "Test-only modules and `#[cfg(test)]` blocks are excluded. `Defined at`",
+        "points to the name constant when one exists, otherwise to the first read",
+        "site; `(+N more)` counts additional read sites. `Description` is the",
+        "comment adjacent to that site (blank when the code has none).",
+        "",
+        f"Regenerate with `{GENERATOR_COMMAND}`; CI fails when this file drifts.",
+        "",
+        f"- AgentDesk variables (`AGENTDESK_*`, `ADK_*`): {len(project)}",
+        f"- Platform and third-party variables: {len(external)}",
+        "",
+        "## AgentDesk variables",
+        "",
+        *render_table(project),
+        "",
+        "## Platform and third-party variables",
+        "",
+        *render_table(external),
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=OUTPUT_DOC,
+        help="destination markdown path (default: docs/generated/env-reference.md)",
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="print the rendered document instead of writing it",
+    )
+    args = parser.parse_args(argv)
+
+    variables = collect_variables(production_rust_files())
+    rendered = render(variables)
+    if args.stdout:
+        sys.stdout.write(rendered)
+        return 0
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(rendered, encoding="utf-8")
+    project = sum(1 for variable in variables.values() if variable.is_project_variable)
+    print(
+        f"wrote {args.output.relative_to(REPO_ROOT).as_posix()}: "
+        f"{project} AgentDesk variables, {len(variables) - project} other"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/test_generate_cli_reference.py b/tests/test_generate_cli_reference.py
new file mode 100644
index 0000000000..ceb679f6b3
--- /dev/null
+++ b/tests/test_generate_cli_reference.py
@@ -0,0 +1,92 @@
+from pathlib import Path
+import re
+import sys
+import unittest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+import generate_cli_reference as gen  # noqa: E402
+
+
+class NamingTests(unittest.TestCase):
+    def test_kebab_case_matches_clap_derivation(self) -> None:
+        cases = {
+            "SendToAgent": "send-to-agent",
+            "Ismcptool": "ismcptool",
+            "DiscordSenddm": "discord-senddm",
+            "ReleaseMigratePostgres": "release-migrate-postgres",
+            "OpenCode": "open-code",
+            "report_channel_id": "report-channel-id",
+        }
+        for name, expected in cases.items():
+            self.assertEqual(gen.kebab_case(name), expected, name)
+
+
+class AttributeParsingTests(unittest.TestCase):
+    def test_attribute_args(self) -> None:
+        parsed = gen.parse_attribute_args(
+            'long = "from", value_enum, default_value_t = InputModeArg::Fifo, '
+            'help = crate::x::CONTRACT, short = \'c\', alias = "starter-message"'
+        )
+        self.assertEqual(parsed["long"], "from")
+        self.assertIs(parsed["value_enum"], True)
+        self.assertEqual(parsed["default_value_t"], "InputModeArg::Fifo")
+        self.assertEqual(parsed["help"], "crate::x::CONTRACT")
+        self.assertEqual(parsed["short"], "c")
+        self.assertEqual(parsed["alias"], "starter-message")
+
+
+class RepositoryTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.rendered, cls.commands = gen.generate()
+        cls.flat = gen.flatten(cls.commands)
+
+    def test_top_level_commands_match_clap_snapshot_test(self) -> None:
+        """The clap unit test in src/cli/args.rs pins the runtime command list.
+
+        Reproducing that snapshot proves the Python name derivation matches what
+        clap actually builds, without needing a cargo build here.
+        """
+
+        source = (REPO_ROOT / "src" / "cli" / "args.rs").read_text(encoding="utf-8")
+        match = re.search(
+            r"fn top_level_command_name_snapshot_preserves_public_cli_surface.*?let expected = vec!\[(.*?)\];",
+            source,
+            re.S,
+        )
+        self.assertIsNotNone(match, "clap snapshot test missing from src/cli/args.rs")
+        expected = [name for name in re.findall(r'"([a-z0-9-]+)"', match.group(1)) if name != "help"]
+        self.assertEqual([command.path[0] for command in self.commands], expected)
+
+    def test_required_commands_and_flags_are_rendered(self) -> None:
+        paths = {" ".join(command.path) for command in self.flat}
+        for required in (
+            "send-to-agent",
+            "query",
+            "health",
+            "machine-compare",
+            "auto-queue activate",
+            "provider-cli status",
+            "migrate openclaw",
+            "discord thread-create",
+        ):
+            self.assertIn(required, paths, required)
+        by_path = {" ".join(command.path): command for command in self.flat}
+        flavor = next(arg for arg in by_path["emit-launchd-plist"].args if arg.display.startswith("--flavor"))
+        self.assertEqual(flavor.value, "`release`")  # no `dev` variant exists
+        expect_reply = next(arg for arg in by_path["send-to-agent"].args if arg.display.startswith("--expect-reply"))
+        self.assertTrue(expect_reply.required)
+        self.assertEqual(expect_reply.value, "`true`, `false`")
+        # `help = crate::...::SEND_TARGET_CONTRACT` resolves to the const text.
+        self.assertIn("Target must be channel:<id>", self.rendered)
+        self.assertNotIn("SEND_TARGET_CONTRACT", self.rendered)
+
+    def test_rendering_is_deterministic(self) -> None:
+        again, _ = gen.generate()
+        self.assertEqual(self.rendered, again)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_generate_env_reference.py b/tests/test_generate_env_reference.py
new file mode 100644
index 0000000000..e66d7734c4
--- /dev/null
+++ b/tests/test_generate_env_reference.py
@@ -0,0 +1,117 @@
+from pathlib import Path
+import sys
+import textwrap
+import unittest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+import generate_env_reference as gen  # noqa: E402
+
+
+class BlankTestModulesTests(unittest.TestCase):
+    def test_cfg_test_module_is_blanked_but_line_numbers_survive(self) -> None:
+        source = textwrap.dedent(
+            """\
+            const KEEP_ENV: &str = "AGENTDESK_KEEP";
+
+            #[cfg(test)]
+            mod tests {
+                const DROP_ENV: &str = "AGENTDESK_DROP";
+                fn f() { let _ = std::env::var("AGENTDESK_DROP_READ"); }
+            }
+            fn after() { let _ = std::env::var("AGENTDESK_AFTER"); }
+            """
+        )
+        blanked = gen.blank_test_modules(source)
+        self.assertEqual(blanked.count("\n"), source.count("\n"))
+        self.assertIn("AGENTDESK_KEEP", blanked)
+        self.assertNotIn("AGENTDESK_DROP", blanked)
+        self.assertIn("AGENTDESK_AFTER", blanked)
+        after_line = blanked.splitlines().index('fn after() { let _ = std::env::var("AGENTDESK_AFTER"); }') + 1
+        self.assertEqual(after_line, 8)
+
+    def test_not_test_cfg_module_is_kept(self) -> None:
+        source = '#[cfg(not(test))]\nmod prod {\n    const X: &str = "AGENTDESK_PROD";\n}\n'
+        self.assertIn("AGENTDESK_PROD", gen.blank_test_modules(source))
+
+
+class DescriptionTests(unittest.TestCase):
+    def test_prefers_comment_that_names_the_variable(self) -> None:
+        lines = [
+            "/// Default ON; set `AGENTDESK_FLAG` to `0` to disable. Second sentence.",
+            "fn enabled() -> bool {",
+            "    // unrelated note",
+            '    std::env::var("AGENTDESK_FLAG").is_ok()',
+            "}",
+        ]
+        self.assertEqual(
+            gen.describe_site(lines, 4, "AGENTDESK_FLAG"),
+            "Default ON; set `AGENTDESK_FLAG` to `0` to disable.",
+        )
+
+    def test_falls_back_to_adjacent_then_enclosing_fn_doc(self) -> None:
+        adjacent = [
+            "/// Fn doc.",
+            "fn f() {",
+            "    // Adjacent note. More.",
+            '    std::env::var("AGENTDESK_X")',
+            "}",
+        ]
+        self.assertEqual(gen.describe_site(adjacent, 4, "AGENTDESK_X"), "Adjacent note.")
+        enclosing = ["/// Fn doc only.", "fn f() {", '    std::env::var("AGENTDESK_X")', "}"]
+        self.assertEqual(gen.describe_site(enclosing, 3, "AGENTDESK_X"), "Fn doc only.")
+        bare = ["fn f() {", '    std::env::var("AGENTDESK_X")', "}"]
+        self.assertEqual(gen.describe_site(bare, 2, "AGENTDESK_X"), "")
+
+
+class PatternTests(unittest.TestCase):
+    def test_read_const_and_helper_patterns(self) -> None:
+        source = textwrap.dedent(
+            """\
+            const STAMP_ENV: &str = "AGENTDESK_STAMP";
+            pub(crate) static OTHER: &'static str = "ADK_OTHER";
+            fn f() {
+                let _ = std::env::var("HOME");
+                let _ = env::var_os(STAMP_ENV);
+                let _ = explicit_env_path("AGENTDESK_PATHY");
+                let _ = resolve_with_env_pg(pool, "ADK_CHANNEL");
+                std::env::set_var("AGENTDESK_NOT_A_READ", "1");
+            }
+            """
+        )
+        literal = {m.group("name") for m in gen._LITERAL_READ_RE.finditer(source)}
+        consts = {m.group("ident"): m.group("name") for m in gen._CONST_DEF_RE.finditer(source)}
+        helpers = {m.group("name") for m in gen._HELPER_READ_RE.finditer(source)}
+        self.assertEqual(literal, {"HOME"})
+        self.assertEqual(consts, {"STAMP_ENV": "AGENTDESK_STAMP", "OTHER": "ADK_OTHER"})
+        self.assertEqual(helpers, {"AGENTDESK_PATHY", "ADK_CHANNEL"})
+        self.assertNotIn("AGENTDESK_NOT_A_READ", helpers)
+
+
+class RepositoryTests(unittest.TestCase):
+    def test_generated_doc_is_deterministic_and_covers_known_variables(self) -> None:
+        variables = gen.collect_variables(gen.production_rust_files())
+        first = gen.render(variables)
+        second = gen.render(gen.collect_variables(gen.production_rust_files()))
+        self.assertEqual(first, second)
+        project = [name for name in variables if name.startswith(gen.PROJECT_PREFIXES)]
+        self.assertGreaterEqual(len(project), 80)
+        for expected in (
+            "AGENTDESK_ROOT_DIR",
+            "AGENTDESK_API_URL",
+            "AGENTDESK_TOKEN",
+            "AGENTDESK_RELAY_CIRCUIT_STAMP",
+            "RUST_LOG",
+        ):
+            self.assertIn(expected, variables, expected)
+        # README used to document this one; nothing in src/ reads it.
+        self.assertNotIn("AGENTDESK_SERVER_PORT", variables)
+        for variable in variables.values():
+            for site in variable.sites:
+                self.assertFalse(site.path.startswith("target/"), site.path)
+                self.assertNotIn("/tests/", site.path)
+
+
+if __name__ == "__main__":
+    unittest.main()