env-settings-map.json drifts silently from upstream docs

[samkeen]

Problem

catalog/env-settings-map.json is hand-maintained because upstream Claude Code JSON Schema doesn't expose env↔settings pairings as structured metadata — they live in the purpose prose of env vars. The weekly catalog-drift workflow (PR #13 is a recent example) re-pulls catalog/env-vars.json and catches that prose drift, but nothing reads the new prose to update the map. So the map slowly diverges from documented reality with no signal.

Evidence

A doc audit on 2026-05-13 against env-vars.md and settings.md found the previous 8-entry map had:

One entry that was actively wrong:

• CLAUDE_CODE_GLOB_NO_IGNORE → respectGitignore (inverted). Doc prose explicitly says the env var controls the Glob tool while the setting controls @ autocomplete — different scopes, not equivalents.

One entry that was unconfirmed in current docs:

• CLAUDE_CODE_SHELL → defaultShell. No mention of defaultShell in the env var's purpose; may be a stale guess or have never been wired.

Three documented pairs that were missing:

• CLAUDE_CODE_DISABLE_AGENT_VIEW → disableAgentView ("Equivalent to" language)
• CLAUDE_CODE_AUTO_CONNECT_IDE → autoConnectIde ("Takes precedence over"; pairing was newly added upstream and is in the open drift PR chore: sync catalog with upstream docs #13)
• CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL → autoInstallIdeExtension (inverted)

Patched manually in [catalog/env-settings-map.json]. New count: 9. This issue is about preventing the next round of silent drift.

Additional documented pairs that don't fit the current flat-projection schema and were deliberately skipped:

• CLAUDE_CODE_NO_FLICKER / CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN → tui.* (nested-object projection)
• CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY → feedbackSurveyRate (bool→rate shape mismatch)
• CLAUDE_CODE_API_KEY_HELPER_TTL_MS → apiKeyHelper (property-of, not swap)
• CLAUDE_CODE_SYNTAX_HIGHLIGHT → syntaxHighlightingDisabled (scope mismatch: env var is diff-only, setting is global)

These would benefit from a richer projection shape if we want full coverage.

Options

Option 1 — Reviewer discipline (lowest effort)

Add a step to the catalog-drift PR workflow body (.github/workflows/catalog-drift.yml) reminding reviewers to scan the env-vars.json diff for new "Takes precedence over the X setting", "Equivalent to the X setting", or [\\...\](/en/settings...) references and update env-settings-map.json in the same PR (or follow-up).

Pros: No new code. Catches everything a human sees.
Cons: Easy to forget; the moment the drift PR auto-merges without careful review (or the reviewer is in a hurry), drift creeps back.

Option 2 — Prose-extraction script (medium effort, my recommendation)

Add a scripts/sync-env-settings-map.js that reads catalog/env-vars.json, regex-scans purpose fields for the documented pairing patterns, and emits a proposed map. Output two artifacts:

• The mechanically derivable subset (high-confidence: clean [\setting`](/en/settings...)` references with unambiguous bool/string types).
• A diff report flagging ambiguous cases (inversion candidates from DISABLE_*/ENABLE_* names, nested-key projections, shape mismatches) for human judgment.

Wire it into the weekly drift workflow. The workflow opens its drift PR with both the synced env-vars catalog and any proposed map changes side-by-side, so a single review captures both.

Pros: Catches the easy 80% mechanically; surfaces the hard 20% for explicit human sign-off. Same workflow shape as the existing sync scripts. Same shape would also work for catalog/cli-settings-map.json (the parallel CLI flag→setting map mentioned in scripts/sync-cli-reference.js:22).
Cons: Real implementation work. Regex over prose has false positives/negatives. Inversion detection (DISABLE_X=1 means xEnabled=false) is a heuristic, not a guarantee.

Option 3 — Accept drift, lean on EnvVarsPanel (zero effort)

Document that the map is best-effort and the env precedence layer is intentionally narrow. The EnvVarsPanel (which reads the full 220+ env-var catalog) is the SSOT for env-var visibility; the precedence layer is a value-add for the small set of dual-surfaced vars where users actually need to know "which wins."

Pros: No work. Conceptually defensible — the panel does the real heavy lifting.
Cons: Users still hit the precedence-resolution case when their ANTHROPIC_MODEL overrides settings.json:model, and they expect the rail to reflect that. Missing entries → silent precedence bugs in the inspector.

Recommendation

Option 2. The pattern matching is well-bounded (the doc prose is consistent: "Takes precedence over", "Equivalent to", [\name`](/en/settings...)link form) and the same infrastructure handlescli-settings-map.json` for free. Option 1 is the right fallback if 2 turns out harder than it looks.

Acceptance criteria

• Choose an option.
• If 2: ship scripts/sync-env-settings-map.js, integrate it into .github/workflows/catalog-drift.yml, document the projection contract (flat-only vs nested) in spec/settings-display.md.
• If 1: update workflow PR body template with reviewer checklist.
• If 3: add note to spec/settings-display.md Phase 3 explaining the intentional drift tolerance.