docs(cliproxy): document strip-vs-overlay launch-settings siblings and model-key superset

Cross-reference the two helpers that solve the persisted-settings-env
override (overlay in launch-settings.ts, strip in
openai-compat-launch-settings.ts) and mark shell-executor's
ANTHROPIC_MODEL_ENV_KEYS as the intentional superset distinct from the
4-key list in extended-context-utils. See issue #1609.

src/cliproxy/executor/launch-settings.ts

@@ -27,6 +27,13 @@ import * as path from 'path';
 
 import { ANTHROPIC_MODEL_ENV_KEYS, ANTHROPIC_ROUTING_ENV_KEYS } from '../../utils/shell-executor';
 
+// SIBLING HELPER: src/utils/openai-compat-launch-settings.ts solves the same
+// "persisted --settings env clobbers runtime routing env" problem by STRIPPING
+// routing keys (process env wins by absence). This module instead OVERLAYS the
+// resolved values (settings wins by overwrite). The two differ intentionally:
+// strip vs overlay diverge when a key is present on disk but absent from the
+// process env. Unifying them needs an explicit force-absent API — see issue #1609.
+
 /**
  * Environment keys that control provider routing/model selection and are read
  * by Claude from the settings `env` block. These must reflect the resolved

src/utils/openai-compat-launch-settings.ts

@@ -10,6 +10,12 @@ export interface OpenAICompatLaunchSettings {
   cleanup: () => void;
 }
 
+// SIBLING HELPER: src/cliproxy/executor/launch-settings.ts (prepareLaunchSettings)
+// solves the same problem by OVERLAYING resolved routing values instead of
+// stripping them. This strip-based variant is required where callers deliberately
+// delete a routing key (e.g. ANTHROPIC_API_KEY in settings-flow) and need it
+// ABSENT from the launch settings. Do not unify without an explicit force-absent
+// key list — see issue #1609.
 export function createOpenAICompatLaunchSettings(
   settingsPath: string,
   settings: Settings

src/utils/shell-executor.ts

@@ -40,6 +40,10 @@ export const ANTHROPIC_ROUTING_ENV_KEYS = [
   'ANTHROPIC_API_KEY',
 ];
 const ANTHROPIC_ROUTING_ENV_KEY_SET = new Set(ANTHROPIC_ROUTING_ENV_KEYS);
+// NOTE: This is the intentional routing-overlay SUPERSET of model env keys
+// (includes ANTHROPIC_SMALL_FAST_MODEL). A separate 4-key `ANTHROPIC_MODEL_ENV_KEYS`
+// exists in src/shared/extended-context-utils.ts (re-exported as MODEL_ENV_VAR_KEYS).
+// The two are NOT interchangeable — import deliberately by purpose. See issue #1609.
 export const ANTHROPIC_MODEL_ENV_KEYS = [
   'ANTHROPIC_MODEL',
   'ANTHROPIC_DEFAULT_OPUS_MODEL',