[AAASM-421] ✨ (aa-cli): aasm docs export — CLI reference auto-generation

[Chisanan232]

Description

Adds an aasm docs export subcommand that auto-generates the aasm CLI reference from the live clap command tree — never a hand-maintained list — so the docs cannot drift from the actual CLI surface.

• aasm docs export --format markdown --out docs/cli/ walks crate::Cli::command() recursively (get_subcommands()), emitting one Markdown file per command with: synopsis (from about/long_about), usage (clap's own rendered usage, rewritten to the full command path), an options table (flags, value placeholders + enumerated possible values, defaults, required markers), a subcommands table linking children by stable anchor, and an examples block sourced from #[command(after_help = …)].
• Each page carries a stable anchor #cmd-aasm-<path> (e.g. #cmd-aasm-agent-list) for durable cross-links.
• aasm docs export --check re-renders in memory and diffs against the on-disk docs/cli/ tree, exiting non-zero (and listing stale / missing / orphaned files) when they differ. This is what CI runs.
• The generated reference (81 files) is committed under docs/cli/ so --check has a baseline.

Type of Change

• ✨ New feature
• 🔧 Configuration / CI change

Breaking Changes

• No

Related Issues

• Related Jira ticket: AAASM-421

Deferred follow-up (depends on AAASM-303)

The stretch goal — firing repository_dispatch (event_type: docs-release, payload { tag, paths: ["docs/cli/"] }) to agent-assembly-docs on release — is deferred to AAASM-303. The docs-sync infra it depends on is not present in this repo (the only existing repository_dispatch wiring in release.yml targets the SDK repos with agent-assembly-release-published, not a docs-release event to agent-assembly-docs). Per the ticket, rather than invent cross-repo wiring, the export + --check + PR CI job are implemented now and the release-dispatch is left as a dependent follow-up under AAASM-303.

Testing

• Unit tests added / updated

12 unit tests in aa-cli/src/commands/docs/export.rs cover: a page per root + nested command, the help pseudo-command being skipped, stable anchor derivation, synopsis/options/subcommands sections, examples surfaced from after_help, subcommand links using stable anchors, and --check passing on fresh output / failing on modified / missing / orphaned pages.

Validation (scoped to -p aa-cli and deps; some workspace crates e.g. eBPF don't build on macOS):

• cargo build -p aa-cli — pass
• cargo clippy -p aa-cli --all-targets -- -D warnings — clean
• cargo fmt -p aa-cli --check — clean
• cargo nextest run -p aa-cli — 597 passed (incl. 12 new docs tests)
• aasm docs export then aasm docs export --check → exit 0 on fresh output; verified exit 1 (listing the exact stale files) when a clap about is changed without regenerating.

CI

New workflow .github/workflows/cli-reference.yml builds aasm and runs aasm docs export --check --out docs/cli/ on every PR (and master push) touching aa-cli/** or docs/cli/**. Note: org GitHub Actions billing has been intermittently blocked, so CI may not execute on this PR — validated locally as above (actionlint clean on the workflow).

Checklist

• Code follows project style guidelines (cargo fmt, cargo clippy)
• Self-review of the diff completed
• Documentation updated if behaviour changed
• All CI checks passing — see CI billing caveat above
• Commits are small and follow the Gitmoji convention

Held for review.

🤖 Generated with Claude Code

[Chisanan232]

🤖 Claude Code — PR review

Ticket: AAASM-421 — Implement aasm CLI reference auto-generation.

CI — ✅ all green

All required checks pass, including the new Verify docs/cli is up to date job (8m48s) and the CI Success gate. Build ✅ · Test ✅ · Clippy lint ✅ · Format check ✅ · Rust conformance ✅ · Integration tests ✅ · CodeQL ✅. Benchmark/Schema/OpenAPI/Spectral correctly skipped (out of changed-areas). Nothing to fix.

Scope vs. acceptance criteria

AC	Status	Notes
aasm docs export --format markdown --out docs/cli/, one file per command	✅	clap get_subcommands() walker → 81 docs/cli/*.md; synopsis/usage/options-table/examples from live metadata only (cannot drift)
Each page: synopsis, usage, options table, examples	✅	from get_about/render_usage/get_arguments/after_help
aasm docs export --check → non-zero on staleness; CI runs it on every PR	✅	byte-for-byte re-render diff; new cli-reference.yml; demonstrated exit 1 on a deliberately drifted about string, exit 0 after revert
Stable anchors (#cmd-aasm-agent-create)	✅	#cmd-aasm-agent-list style
On release: export + repository_dispatch → agent-assembly-docs (event_type: docs-release)	⏸️ deferred	The docs-sync infra (AAASM-302/303) is not present — the only existing dispatch targets the SDK repos. Per the ticket, cross-repo wiring was not invented; tracked under subtask AAASM-583
Docs-site nav "CLI Reference" section under SDKs sidebar	⏸️ deferred	Docs-site aggregation = AAASM-302; out of lane (docs/src/SUMMARY.md untouched)

Core feature is fully delivered and self-validating. The two ⏸️ items are genuinely blocked on docs-sync infra that doesn't exist yet — correctly deferred and noted in the PR body, with subtask AAASM-583 carrying the release-dispatch wiring.

Lane / conflict check — ✅ clean

Only aa-cli/, docs/cli/, .github/workflows/ touched. No edits to docs/src/SUMMARY.md, docs/concepts/ (parallel AAASM-419 lane), root files, or unrelated crates. 3 atomic commits.

Note for reviewer (non-blocking)

• The generated docs include the dev-only aasm run / aasm tools commands that .ci/strip-for-publish.sh removes before crate publish. Correct for a source-build reference of the live tree; if the published reference should exclude stripped commands, that's a follow-up (the export has no strip-for-publish awareness).

Readiness

Ready to merge pending one Pioneer-team approval. CI green, real Rust validated (cargo build/clippy -D warnings/fmt/nextest -p aa-cli → 597 pass incl. 12 new docs tests). Remaining ACs are infra-dependent and tracked (AAASM-583 / AAASM-302).

Recorded as a review note; no formal approval submitted.

[Chisanan232]

🏷️ Held open — do-not-merge.

This documentation is written out in full detail and the review is green/ready, but the team is still deliberating on the documentation content/structure. Per maintainer decision, keep this PR open and do not merge until that discussion concludes. The do-not-merge label reflects that hold — it is not a CI or quality blocker (CI is green; all in-scope ACs are met).

— Claude Code