feat(spec): add deprecated config environment aliases

[jdx]

Replaces #1147, 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

Medium Risk
Changes environment-layer precedence and warning behavior for settings, which can alter which value wins when both current and old variables are set. Coverage is strong, but this is user-visible config resolution.

Overview
Config props can now declare deprecated_env names separately from current env aliases. Current names stay ordered and win; deprecated names are consulted afterwards, emit a deprecation warning when they actually set a value, and show up in generated registries and docs.

The env layer prefers every current name (including a renamed setting that folds into the same target) over every deprecated alias. Unused deprecated names do not warn. When a deprecated alias is used, the message points at the replacement setting’s current env name, not the old key.

^{Reviewed by Cursor Bugbot for commit 584b159. 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: db59d026-7228-497e-a6ae-45379d4f6cc0

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

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁██	226,081,956 → 226,116,539	+0.02%	22.17 → 20.67ms	-6.76%
startup	▁▇█	1,226,955 → 1,227,348	+0.03%	1.43 → 1.41ms	-1.40%

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

                                              min       p01       p10    median
usage-rs: argv -> struct                      408       411       414       419  ns
argh: argv -> struct                          288       291       295       305  ns
clap: build tree + parse -> struct         519714    520676    522158    525260  ns
bpaf: build parser + parse -> struct      1592188   1592188   1598900   1607382  ns

usage: argv -> struct                             453 ns      0.45 µs
clap: build tree + parse -> struct             529583 ns    529.58 µs
clap: parse -> struct, tree reused              22318 ns     22.32 µs
clap: build tree only                          326976 ns    326.98 µs

_{584b15941f60 vs e4549028527f · measured on the runner, not pushed to the history.}