docs: mark go and rust frameworks experimental, document both

[jdx]

What

• The landing page's Rust and Go framework tiles now carry an experimental pill, tooltips noting APIs may change, and link to new docs sections instead of GitHub. Hero copy reads "Experimental reference frameworks".
• New comprehensive docs section per framework, wired into the nav ("Frameworks" dropdown) and sidebar:
  • /rust/ (7 pages): getting started (crates, cargo features and their footguns), args and flags (type-driven cardinality, full attribute tables, resolution order), subcommands (Subcommands/Args, flatten, ValueEnum, mounts), validation, help/version/errors, completions, and spec output (to_kdl(), round-trip guarantee, feeding usage-cli).
  • /go/ (6 pages): overview with a working quick start (including the help/version/error exit switch), usage generate go and the generated structs/Parse, the zero-allocation event parser, binding and typed values, help pages and error rendering, and completions.

Notes

• Written as if the in-flight PR stacks have landed: feat(derive): declare a group where the flags are declared #934, feat(spec): a flag that has to be given on its own #941, feat(spec): split a value the way clap splits one #961, fix(derive): a global flag may be given once per command, not once per line #991 (Rust/spec) and feat(go): render the page -h prints, matching usage-lib on all 211 of mise's #974, feat(go): render --help too, matching usage-lib on all 211 of mise's long pages #975, feat(go): render a failure as something a person can act on #977, feat(go): turn bound text into the type a field wants #978, feat(go): answer what could go where the cursor is #984, feat(go): write an answer the way each shell reads it #989, feat(go): generate a struct per command, and the Parse that fills them #990 (Go). This PR should merge after those.
• The Go docs state the current gaps plainly: generated Parse does not apply overrides, does not print help/version itself, and __complete_word__ wiring is manual. If any of those change before release, trim the "Current limitations" list on /go/.
• go/README.md still claims the generator and typed front door don't exist yet — stale once feat(go): generate a struct per command, and the Parse that fills them #990 lands; not touched here since it isn't part of the docs site.
• vitepress build passes; prettier run over the changed files.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and VitePress theme/config only; no application or library runtime behavior changes.

Overview
Adds first-class Rust and Go framework documentation on the VitePress site and surfaces them from the home page and navigation.

The hero now labels both frameworks as experimental (cyan pill + tooltip), calls them “Experimental reference frameworks,” and links tiles to /rust/ and /go/ instead of GitHub. Nav gains a Frameworks dropdown; the sidebar lists seven Rust pages (getting started through spec output) and six Go pages (overview through completions).

New draft pages describe derive-based Rust (Cli/Args, validation, completions, to_kdl()) and spec-generated Go (usage generate go, argv parser, binding, help/errors, manual completion wiring), including honest current limitations (e.g. Go Parse skips overrides and auto help).

^{Reviewed by Cursor Bugbot for commit d634d9b. 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 under your plan.

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?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling 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: 46e29e79-9b3d-4837-b439-33272057483c

📥 Commits

Reviewing files that changed from the base of the PR and between ae87c7b and d634d9b.

📒 Files selected for processing (16)

• docs/.vitepress/config.mts
• docs/.vitepress/theme/UsageHero.vue
• docs/.vitepress/theme/custom.css
• docs/go/binding.md
• docs/go/completions.md
• docs/go/generated-code.md
• docs/go/help.md
• docs/go/index.md
• docs/go/parser.md
• docs/rust/args-and-flags.md
• docs/rust/completions.md
• docs/rust/help.md
• docs/rust/index.md
• docs/rust/spec.md
• docs/rust/subcommands.md
• docs/rust/validation.md

---

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.}

[greptile-apps]

Greptile Summary

The PR adds draft documentation for the experimental Rust and Go frameworks and makes those guides discoverable through the VitePress navigation and landing-page framework tiles.

• Adds seven Rust guides covering derives, validation, help, completions, subcommands, and spec output.
• Adds six Go guides covering generated code, parsing, binding, help, and completions.
• Marks both frameworks experimental and links their landing-page tiles to the new documentation.

Confidence Score: 5/5

The PR appears safe to merge after the prerequisite framework stacks identified in its description have landed.

The navigation and internal documentation links resolve consistently, and no concrete defect remains beyond API mismatches that the PR explicitly acknowledges as dependent on in-flight prerequisite changes.

Important Files Changed

Filename	Overview
docs/.vitepress/config.mts	Adds valid navigation and sidebar entries for all new Rust and Go documentation pages.
docs/.vitepress/theme/UsageHero.vue	Relabels the frameworks as experimental and replaces repository links with valid documentation routes.
docs/.vitepress/theme/custom.css	Reuses the existing pill styling for the new experimental labels with a cyan color variant.
docs/go/index.md	Introduces the Go framework, its generated-code workflow, error handling, and explicitly documented current limitations.
docs/go/generated-code.md	Documents the proposed generated Go API and clearly presents it as draft material dependent on in-flight work.
docs/go/completions.md	Documents the proposed completion API and the manual integration currently required on the Go side.
docs/rust/index.md	Introduces the Rust framework, installation features, parsing entry points, and experimental status.
docs/rust/args-and-flags.md	Provides a comprehensive draft reference for type-driven cardinality, derive attributes, resolution, and global flags.
docs/rust/completions.md	Documents opt-in completion support, generated methods, value hints, and custom completers.

_{Reviews (1): Last reviewed commit: "docs: mark the framework docs as draft" | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▇█▇██▃▁▂▁▁	196,170,622 → 196,153,553	-0.01%	18.36 → 19.02ms	+3.56%
startup	█████▁▁▁▁▁	824,522 → 824,554	+0.00%	0.87 → 0.92ms	+5.34%

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.

	usage	clap	ratio
instructions, cold parse	63866	5893640	92x

usage: argv -> struct                            1100 ns      1.10 µs
clap: build tree + parse -> struct             508383 ns    508.38 µs
clap: parse -> struct, tree reused              23097 ns     23.10 µs
clap: build tree only                          342830 ns    342.83 µs

_{d634d9b067cc vs 5ca210a22bff · measured on the runner, not pushed to the history.}