docs: sharpen the usage-rs pitch and cross-link framework completions

[jdx]

Three copy changes, one per commit.

/rust/ opening

Opened with what usage-rs is rather than how it works: a CLI framework for Rust applications and the reference implementation of the usage spec, fully featured against clap, with a parser up to thousands of times faster. The mechanics (structs and enums, clap-compatible derive spellings) moved into the second paragraph, and the speed claim now says where the speed comes from — static tables laid out at compile time instead of a parser built and validated on every run.

Numbers are the ones the gate measures: 855x fewer instructions than clap, 2,957x fewer than bpaf, 1.3 MB stripped against clap's 3.1 MB.

/rust/performance opening

Leads with the measured standing and the compile-time reason for it. Dropped the "Cold metadata for help, specs, and completions is not constructed on a successful parse" sentence — Why it is fast already covers it in context.

/cli/completions callout

Readers building with usage-rs or usage-go were landing on the spec-driven CLI workflow. A tip at the top sends them to the framework pages and notes that those binaries answer completions from compiled tables, with no spec file to ship and no usage runtime dependency for their users.

Verification

Built the site and read the rendered pages.

Rust framework landing page with the new opening

Parser performance page leading with the measured result

Completion scripts page with the new framework callout

_{To show artifacts inline, enable in settings.}

  

Summary by CodeRabbit

• Documentation
  • Clarified the distinction between framework-generated completions and scripts generated by the usage CLI.
  • Updated Rust framework documentation with expanded feature descriptions, migration guidance, and performance highlights.
  • Added quantified parser performance comparisons and explained how compiled command tables improve parsing efficiency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 35313691-7a55-44a2-9011-f4530e7a7993

📥 Commits

Reviewing files that changed from the base of the PR and between 8776bb8 and e6d794d.

📒 Files selected for processing (3)

• docs/cli/completions.md
• docs/rust/index.md
• docs/rust/performance.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation distinguishes framework-generated and CLI-generated completions. It also updates Rust framework positioning and parser performance descriptions with compile-time table details and measured comparisons.

Changes

CLI completion guidance

Layer / File(s)	Summary
Completion source guidance docs/cli/completions.md	The documentation distinguishes completions compiled into Rust and Go binaries from scripts generated by the usage CLI. It describes the supported input sources and runtime dependency behavior.

Rust framework documentation

Layer / File(s)	Summary
Framework positioning and performance docs/rust/index.md, docs/rust/performance.md	The documentation presents usage-rs as a fully featured framework and reference implementation. It adds static command-table details, migration wording, binary-size data, and measured parser comparisons.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to e6d79

This PR makes localized documentation and cross-linking updates with no actionable merge-blocking risk remaining after normal checks and review.

Poem

A rabbit reads the docs at night
Static tables shine bright
Completions hop from source to shell
Rust benchmarks ring their bell
New clear words make guides well steeped

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation updates to the usage-rs pitch and framework completion cross-links.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (3 skipped: 3 unsupported.)
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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	▄▄▄▄▆▆▇█▅▆▆▁▂▁▂	334,499,234 → 335,463,103	+0.29%	28.62 → 28.79ms	+0.59%
startup	▃███▆▆▇█▁▁▁▅▅▅▅	878,465 → 878,381	-0.01%	0.86 → 0.94ms	+10.31%

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	stripped binary, bytes
usage	1321264
bpaf	2493280
clap	3101832

framework	instructions, cold parse	vs usage
usage	8309	—
clap	6315556	760x
bpaf	21908997	2636x

                                              min       p01       p10    median
usage-rs: argv -> struct                      409       412       418       428  ns
clap: build tree + parse -> struct         520383    521856    527299    541120  ns
bpaf: build parser + parse -> struct      1618386   1618386   1648142   1671401  ns

usage: argv -> struct                             447 ns      0.45 µs
clap: build tree + parse -> struct             527156 ns    527.16 µs
clap: parse -> struct, tree reused              24135 ns     24.14 µs
clap: build tree only                          350243 ns    350.24 µs

_{e6d794d5c2bc vs 8776bb8f9de7 · measured on the runner, not pushed to the history.}