feat(buzz-cli): render an agent-friendly command tree in --help

[salman1993]

Summary

crates/buzz-acp/src/base_prompt.md carries a hand-maintained Group | Key commands table of the buzz CLI. It is a second copy of a surface that already documents itself, and it has drifted: it lists 16 of the CLI's 23 groups (missing emoji, gifs, notes, patches, media, moderation, pack) and omits roughly two-thirds of the subcommands under the groups it does list. Nothing in it is wrong — it is incomplete, and structurally destined to stay that way, because nothing ties it to the parser. Every agent turn also carries the whole inventory whether or not the task touches the CLI at all.

The reason the base prompt duplicates that inventory is that buzz --help was not good enough to lean on. It listed 23 group names with nothing under them, so finding buzz messages send cost a second --help call and learning that buzz canvas set exists at all cost a third. An agent paying per group reasonably prefers a stale table it already has.

This PR fixes the help output so the prompt can point at it instead. buzz --help now prints the whole tree — every group, its subcommands, and their descriptions — in one invocation:

Before

Commands:
  messages    Send, read, search, and manage messages
  channels    Create, configure, and manage channels
  canvas      Get and set channel canvas documents

After

Commands:
  messages                      Send, read, search, and manage messages
    send                        Send a message to a channel
    send-diff                   Send a code diff / patch to a channel
    edit                        Edit a previously sent message
    ...
  repos                         Announce and discover git repositories (NIP-34)
    protect                     Manage branch and tag protection rules on one of your repositories
      list                      List the repository's protection rules

The tree is walked from clap's own command definition (get_subcommands, get_about, get_visible_aliases, is_hide_set, get_display_order), so it cannot drift from the commands that exist — merging origin/main mid-review added repos default-branch get/set, and it appeared in the tree with no edit here. No new dependencies. Amp's CLI does the same thing, and its layout is what the column formatting follows.

Wiring uses clap's existing short/long help split rather than a custom help path: -h keeps the group-level summary via after_help, --help gets full depth via after_long_help. The root help_template drops {subcommands} so the group list is not printed twice, and spells out the Commands:/Options: headings itself, because the {options} and {subcommands} tags emit no heading of their own. Long help is 199 lines / 12.7 KB, comfortably under buzz-dev-mcp's output caps (50 KB / 2000 lines), so it is not tail-truncated for agents.

This change is formatting only: it adds no new data and no new commands. --version still does not exist, and is deliberately left out — the crate version is not bumped, so the flag would report a number that means nothing.

Follow-up PR removes the Group | Key commands table from base_prompt.md, replacing it with a pointer at buzz --help plus the corrected exit codes (the prompt currently stops at 4; the CLI has a 5th, write conflict). Everything else in that section stays — it is all non-discoverable semantics that --help cannot express. That PR will carry its own known risk (the table is also an inventory: it is how an agent learns buzz canvas exists without being told to look) and will be validated against the benchmarks/buzz-dataset tasks, which grade behavior that comes from the production base prompt rather than the task instruction.

Related issue

None found.

Testing

cargo test -p buzz-cli — 473 pass, 7 new in help_tree.rs. cargo clippy -p buzz-cli --all-targets -- -D warnings, cargo fmt --check, and just file-size-check clean. All pre-push lanes green.

The new assertions are column-exact, and I falsified them rather than assuming they bite: shifting the description column from 32 to 30 fails 4 of the 7. That matters because clap runs StyledStr::wrap over after_help, which is a no-op only because this crate builds clap without the wrap_help feature. If workspace feature unification ever enables it — the same mechanism behind the rustls double-provider workaround in buzz-cli/src/lib.rs — clap reflows the tree and destroys the alignment. A looser contains("send") assertion would not notice.

Verified by hand on the built binary: third-level nesting renders (repos protect, repos default-branch); the emoji description that used to overflow 100 columns now wraps into the description column; buzz messages --help and buzz help messages are unchanged; and the error paths still exit 1 with JSON on stderr for both a bad flag and a missing subcommand.

One behavior change worth a reviewer's eye: buzz -h now uses the same 32-column description alignment as --help instead of clap's auto-fit 12-column layout. Same 37 lines, wider. Happy to revert that one line if you'd rather short help stay narrow.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-11T15:39:55.080591Z	016c9b7	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

🔐 Codex Security Review

Status: review required for the current range.

The current range is d074576871a66c72e4a9eb5ad59ec0b22a7f0081...629f06e3377b2b3a99727b02dfd73825af2e0dff.
A new review must complete for this exact range. When manual authorization
is required, a Block organization member must comment exactly
@buzz-security-review 629f06e3377b2b3a99727b02dfd73825af2e0dff to authorize a new review.
Any previous review applies only to its recorded range.

[salman1993]

screenshot of what it looks like now:

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Review clear: no blocking findings

Reviewed head 629f06e3377b2b3a99727b02dfd73825af2e0dff against base d074576871a66c72e4a9eb5ad59ec0b22a7f0081.

• The change supports the agent-first discovery contract: root long help walks the authoritative clap command tree, including third-level repository commands, while short help remains group-level. The wider short-help alignment is intentional; the base-prompt rewrite is outside this PR.
• Traced the standalone CLI and MCP bundled buzz entry points, root/group/leaf help construction, argument conversion, error/exit routing, command dispatch, ordering/filtering, description wrapping, and the seven new help tests. An independent parser-compatibility source pass also found no blocker. No wire, authorization, persistence, or desktop/mobile UI changes require expansion into those service workflows.
• Validation is source-only. No checkout, build, test, or PR-code execution was performed. Runtime output and the author's test claims were not independently verified; CI analysis was unavailable through the installed tooling. This is a COMMENTED review, not GitHub approval.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

No blocking findings. Reviewed head 629f06e3377b2b3a99727b02dfd73825af2e0dff against base/merge-base d074576871a66c72e4a9eb5ad59ec0b22a7f0081.

• Built both revisions locally with the pinned toolchain. A 737-case differential probe covered all 145 command paths: nested -h, --help, help <path>, missing arguments, and invalid flags retain their prior output and exit behavior. Additional valid relay-command inputs reached the same authentication boundary without making relay requests.
• The root tree exactly matches the recursively discovered base inventory, including order and third-level commands: 23 groups, 145 total entries. Root --help and help agree; -h remains group-only. Long help is 12,974 bytes / 199 lines, below the repository MCP shell’s truncation thresholds. Configured credential sentinels remain hidden. Independent formatter review also found no defects.
• Release-package feature resolution does not enable clap wrap_help. The wider short-help layout is intentional; removing the ACP prompt inventory is correctly left to the follow-up.

Validation limits: this was a local macOS debug-binary/source review, not a live-relay or cross-platform runtime exercise. I did not rerun the broad unit suite. At the CI snapshot, Rust lint passed and several test/build lanes were still pending; current-range security review also remained a separate merge gate. This is a review comment, not an approval.