feat(docs): support flattened subcommand help

[jdx]

Summary

• carry flatten_help through typed derives, KDL, the clap bridge, and conformance tables
• render flattened usage alternatives and subcommand details in Rust, usage-lib, and generated Go help
• emit subcommand_required into generated Go help tables so flattened usage preserves required-command semantics
• document the compatibility surface and close the PLAN gap

Test plan

• cargo clippy --all --all-features -- -D warnings
• cargo test --all --all-features
• go test ./...
• mise run render
• mise run gen-shadow
• mise run gen-go
• git diff --check

---

Note

Medium Risk
Broad help-output changes across Rust, Go, and docs generators; behavior is covered by new tests but any CLI relying on exact help formatting could see differences when flatten_help is enabled.

Overview
Adds clap-style flatten_help: when set on a command, help drops the usual Commands list and instead prints multiple usage lines plus per-subcommand sections (about, args, flags), including nested flattening on descendants.

The flag is wired through CommandMeta / KDL / #[usage(flatten_help)] / clap bridge and is no longer treated as a fidelity loss. Rust (argv/help.rs), usage-lib CLI templates, and generated Go (usageLines, flatCommandsShort/Long) share the same layout rules; Go help metadata also gains SubcommandRequired (and shadow mise tables are regenerated) so flattened usage respects required-subcommand semantics.

Docs and PLAN.md mark flatten_help done; markdown rendering switches to render_with so multi-page output does not deep-clone the full command tree per page.

^{Reviewed by Cursor Bugbot for commit b060f15. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: efe09084-66fd-417d-8bba-5a17902efde5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▂█▁	207,853,342 → 194,747,705	-6.31%	19.31 → 18.31ms	-5.20%
startup	▃▁█	1,216,618 → 1,222,136	+0.45%	1.48 → 1.35ms	-8.59%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	instructions, cold parse	vs usage
usage	4343	—
argh	6292	1.4x
clap	5895248	1357x
bpaf	21917778	5046x

                                              min       p01       p10    median
usage-rs: argv -> struct                      190       193       195       200  ns
argh: argv -> struct                          305       309       312       317  ns
clap: build tree + parse -> struct         481218    482388    484180    488914  ns
bpaf: build parser + parse -> struct      1606762   1606762   1610900   1616857  ns

usage: argv -> struct                             193 ns      0.19 µs
clap: build tree + parse -> struct             489899 ns    489.90 µs
clap: parse -> struct, tree reused              22939 ns     22.94 µs
clap: build tree only                          304506 ns    304.51 µs

_{b060f15a0728 vs d9ec8b579ada · measured on the runner, not pushed to the history.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 11c20fd. Configure here.}