docs: add clap compatibility matrix

[jdx]

Summary

• add a clap compatibility matrix pinned to clap 4.6.6 and clap_derive 4.6.4
• distinguish direct usage support from clap-to-spec bridge fidelity
• record partial support, intentional differences, unsupported features, and architectural non-goals
• link the matrix from the Rust and clap integration documentation

Why

A clap user needs to know whether behavior survives before changing parsers. The existing plan audits gaps, but it is not presented as a migration-facing, versioned reference and does not clearly separate usage-native support from bridge loss.

This establishes the first public baseline. It intentionally does not close the plan item yet: an exhaustive inventory of every forwarded builder method still remains.

Validation

• git diff --check
• prettier --check docs/rust/clap-compatibility.md docs/rust/index.md docs/spec/integrations/clap.md

This PR is stacked on #1027.

This pull request was generated by Codex.

---

Note

Low Risk
Documentation-only; no runtime, parser, or bridge code changes.

Overview
Adds a versioned clap compatibility matrix (clap 4.6.6 / clap_derive 4.6.4) at /rust/clap-compatibility, aimed at migration and clap_usage bridge expectations.

The page defines status labels (Supported, Usage only, Partial, Different, Unsupported, Non-goal) and tables for derives/types, arguments, relationships/routing, and help/generated artifacts. It separates native usage declarations from clap::Command → spec fidelity and calls out bridge losses (e.g. setter-only clap APIs) and usage-only extensions.

Rust docs and clap integration pages now link to the matrix from “Where to go next” and “Links”.

^{Reviewed by Cursor Bugbot for commit 6296f88. 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: ba2439f8-c41d-4ff7-8193-9ce4e4be0a93

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

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.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	4253	—
argh	6292	1.5x
clap	5893640	1385x
bpaf	21917948	5153x

                                              min       p01       p10    median
usage-rs: argv -> struct                      192       196       199       205  ns
argh: argv -> struct                          271       275       281       292  ns
clap: build tree + parse -> struct         483083    484801    491572    508298  ns
bpaf: build parser + parse -> struct      1588560   1588560   1606148   1657284  ns

usage: argv -> struct                             200 ns      0.20 µs
clap: build tree + parse -> struct             502747 ns    502.75 µs
clap: parse -> struct, tree reused              23586 ns     23.59 µs
clap: build tree only                          309567 ns    309.57 µs

_{6296f8819c54 vs 8aa13e2d2652 · measured on the runner, not pushed to the history.}