docs: generate env and CLI reference tables from source

[itismyfield]

Summary

README carried a hand-written environment-variable table (12 rows) and a ## CLI Reference block that had drifted from the code. Both are now generated from src/ and linked from README; CI regenerates them and fails on drift.

What is generated

Generator	Output	Source
scripts/generate_env_reference.py	docs/generated/env-reference.md — 87 AGENTDESK_*/ADK_* variables + 27 platform/third-party variables (114 rows), sorted by name, columns Variable | Defined at (file:line) | Description	env::var / env::var_os / std::env::var literal reads, const X_ENV: &str = "AGENTDESK_…" name constants (plus indirect env::var(CONST) reads), *env*("AGENTDESK_…") helper calls, EnvFilter::from_default_env() (RUST_LOG). tests.rs, src/**/tests/, #[cfg(test)] mod blocks and target/ are excluded.
scripts/generate_cli_reference.py	docs/generated/cli-reference.md — 53 top-level commands, 93 including nested subcommands; global options, command index, per-command usage line and argument table (value-enum choices, defaults, required, aliases, after_help, #[cfg(unix)]/hidden notes)	Parses the clap derive items (Parser/Subcommand/Args/ValueEnum) in src/cli/args.rs, src/cli/provider_cli/mod.rs, src/cli/migrate.rs — no cargo build. tests/test_generate_cli_reference.py asserts the derived top-level command list equals the clap snapshot test top_level_command_name_snapshot_preserves_public_cli_surface in args.rs, so the Python name derivation cannot silently diverge from clap.

README changes

• ### Environment Variables: table removed, replaced by a link to docs/generated/env-reference.md and a 5-item "commonly used" list (AGENTDESK_ROOT_DIR, AGENTDESK_CONFIG, AGENTDESK_API_URL, AGENTDESK_TOKEN, RUST_LOG).
  • Dropped because the binary does not read them: AGENTDESK_SERVER_PORT (only scripts/deploy.sh reads it as a health-check port), AGENTDESK_CODEX_PATH, AGENTDESK_GEMINI_PATH (read nowhere), AGENTDESK_INSTALL_PORT (installer shell variable; still documented in Quick Start).
  • The other former rows (AGENTDESK_REPO_DIR, AGENTDESK_DCSERVER_LABEL, AGENTDESK_STATUS_INTERVAL_SECS, AGENTDESK_TURN_TIMEOUT_SECS, AGENTDESK_GH_PATH, AGENTDESK_HEADLESS_DISCORD_NONCE) are in the generated document.
• ## CLI Reference: the 60-line hand-written block removed, replaced by a link to docs/generated/cli-reference.md plus an 8-line "frequently used entry points" snippet. emit-launchd-plist --flavor release|dev is gone: LaunchdPlistFlavorArg has a single Release variant, and the generated doc now shows --flavor <FLAVOR> with choices release. The retired migrate postgres-cutover note is kept as one sentence.

CI drift gate

scripts/ci-script-checks.sh gained one section after the inventory-docs step: run both generators, run tests.test_generate_env_reference + tests.test_generate_cli_reference, then the existing git diff --exit-code tracked-doc gate now also lists docs/generated/env-reference.md and docs/generated/cli-reference.md (one gate, no duplicate check). docs/generated/README.md records these two as the explicit exception to the warning-only drift policy (cheap source parsers, only change when an env read site or clap definition changes).

deny_unknown_fields is untouched.

Verification

python3 scripts/generate_env_reference.py; cp …/env1.md; python3 scripts/generate_env_reference.py; diff  → identical (ENV_SAME)
python3 scripts/generate_cli_reference.py; cp …/cli1.md; python3 scripts/generate_cli_reference.py; diff  → identical (CLI_SAME)
python3 -m unittest tests.test_generate_env_reference tests.test_generate_cli_reference  → Ran 11 tests, OK
python3 -m unittest tests.test_script_python_policy  → Ran 6 tests, OK
shellcheck -S warning scripts/ci-script-checks.sh  → clean
python3 scripts/check-portable-paths.py  → OK: scanned 91 portable deployable file(s)
git diff --exit-code -- ARCHITECTURE.md docs/generated/{route,worker}-inventory.md docs/generated/{env,cli}-reference.md (after regenerating)  → no drift

Coverage checks: env table 114 rows (≥100); CLI table contains send-to-agent, query, health, machine-compare.

Not run locally: the full scripts/ci-script-checks.sh (its --verify-lib-inventory step needs a cargo build). tests.test_portable_docs_examples fails on main as well (agentdesk.example.yaml contains mac-book-release) and is unrelated to this PR.

Known gaps

• Env names that only appear inside array literals iterated with env::var(key) (e.g. ["AGENTDESK_TEST_GIT", "AGENTDESK_GIT"] in src/services/platform/binary_resolver.rs) and the AGENTDESK_* profile-name arrays in src/services/routines/migrated.rs are not captured (5 names). Adding a dedicated pattern is a follow-up.

🤖 Generated with Claude Code