docs: record remaining 6.x design decisions

[jdx]

Replaces #1151, which GitHub automatically marked merged when dependent branch refs temporarily matched during a restack. This is the same layer on the corrected stack.\n\n_This pull request was generated by Codex._

---

Note

Low Risk
Documentation-only updates to PLAN.md; no runtime, API, or security impact.

Overview
Adds Design input needed notes to PLAN.md for remaining 6.x choices, without changing implementation.

The notes cover JS/Python generator packaging and parity, group-as-enum derive surface, nested-subcommand redirects, config derive vs registry, repo vs split crates, incremental fleet adoption, and whether fnox should gain config-file settings.

^{Reviewed by Cursor Bugbot for commit 46baba1. 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: 672ac49d-127b-4137-be2e-16b8a9d625aa

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	8316	—
argh	6307	0.8x
clap	6316365	759x
bpaf	21909147	2634x

                                              min       p01       p10    median
usage-rs: argv -> struct                      403       406       412       422  ns
argh: argv -> struct                          273       277       281       288  ns
clap: build tree + parse -> struct         524432    526398    531808    545830  ns
bpaf: build parser + parse -> struct      1595547   1595547   1599785   1610741  ns

usage: argv -> struct                             420 ns      0.42 µs
clap: build tree + parse -> struct             529613 ns    529.61 µs
clap: parse -> struct, tree reused              22940 ns     22.94 µs
clap: build tree only                          324557 ns    324.56 µs

_{f31ec4c89338 vs 838b96fdafb4 · measured on the runner, not pushed to the history.}