docs: dependency comparison and rust docs expansion

[jdx]

Summary

Started as the missing dependency-footprint comparison; grew into a sweep of the Rust framework docs.

Selling the comparison

• Migrating from clap: measured dependency table — clap links 8 third-party crates into your binary, usage links 0 (graph: 17 vs 7 crates; usage's four are the proc-macro stack serde/clap_derive users already compile). Opt-in validation caveat stated.
• Performance: the gate already builds argh and bpaf shadows of the same mise spec — the page now reports them: usage 7.4k instructions / 350 ns, argh 6.3k / 275 ns, clap 6.3M / 513 µs, bpaf 21.9M / 1.6 ms, with the honest note that argh is slightly cheaper because its shadow expresses far less. Plus a stripped-binary size table (usage 1.5 MB, clap 3.1 MB at mise scale) and method notes.
• Testing: one sentence on completion assertions having no clap equivalent.

New page

• Quickstart (/rust/quickstart): a small CLI end to end — declare, run, complete, generate docs. Every output on the page captured from a real build of the shown code, including the passing test.

Fixes

• args-and-flags: duplicate env row removed; the 50-row attribute table split into grouped tables (naming, values, env/defaults, parsing, relationships, deprecation, presentation, completion); setting = row links to the Settings page
• index: crate table gains usage-config, features table gains config, next-steps gains Quickstart/Settings/Testing/Performance, limitations gains Elvish and help_template
• dispatch: first example now defines the root struct it uses
• sidebar: Quickstart added; help entry retitled to match its page

Rebased on #1180 (usage::Config derive): an earlier revision of this PR added a /rust/config page documenting the usage-config-build path; that path and crate were removed by #1180 in favor of the derive and its /rust/settings page, so this PR now links to that page instead.

Measured numbers are pinned to clap 4.6.6 (the version the compatibility page audits) and one run of tasks/perf-shadow.sh.

This PR was generated by Claude Code.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes with no runtime, API, or security impact.

Overview
Expands the Rust framework docs with a Quickstart that walks a small CLI from declaration through run, completions, generated docs, and a parse test.

Adds clap vs usage dependency-footprint numbers (0 third-party crates in the binary) and argh/bpaf parse-cost and stripped-binary tables, with the caveat that argh’s cheaper numbers come from a much smaller grammar.

Splits the args-and-flags attribute dump into grouped tables, documents usage-config / the config feature, retitles Help, and fills small holes (dispatch example root struct, Elvish/help_template limitations, completion-testing vs clap).

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

[coderabbitai]

Warning

Review limit reached

@jdx, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 4 minutes

Limit details: You’ve used all 4 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 346e59a1-8427-4035-b371-8f263e0057b8

📥 Commits

Reviewing files that changed from the base of the PR and between f265f77 and 1232f79.

📒 Files selected for processing (8)

• docs/.vitepress/config.mts
• docs/rust/args-and-flags.md
• docs/rust/dispatch.md
• docs/rust/index.md
• docs/rust/migrating-from-clap.md
• docs/rust/performance.md
• docs/rust/quickstart.md
• docs/rust/testing.md

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch claude/usage-rs-clap-comparison-1f4aed

---

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	▇▇▇▇▄▄▂▂▁▆▆▆██	226,823,745 → 226,846,596	+0.01%	19.94 → 19.88ms	-0.31%
startup	████████▁▁▁▁▁▁	844,754 → 844,023	-0.09%	0.94 → 0.87ms	-7.89%

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	8352	—
argh	6307	0.8x
clap	6316072	756x
bpaf	21909147	2623x

                                              min       p01       p10    median
usage-rs: argv -> struct                      410       414       420       443  ns
argh: argv -> struct                          293       298       303       311  ns
clap: build tree + parse -> struct         521840    522750    524866    530214  ns
bpaf: build parser + parse -> struct      1585342   1585342   1593268   1623906  ns

usage: argv -> struct                             447 ns      0.45 µs
clap: build tree + parse -> struct             532902 ns    532.90 µs
clap: parse -> struct, tree reused              23035 ns     23.03 µs
clap: build tree only                          333584 ns    333.58 µs

_{1232f7968e6f vs 9e5c38989bf1 · measured on the runner, not pushed to the history.}