docs: capture the remove-model merge-layer learning note

Author: 鲁工

learnings/2026-07-20-remove-model-merge-layer.md

@@ -0,0 +1,49 @@
+# Removing a built-in model is a no-op on the user's own machine
+
+**Problem (one line):** Asked to "remove qwen3.5", I deleted it from
+`DEFAULT_CONFIG` — but `ccmr models` still showed it, and `qwen` still
+defaulted to 3.5.
+
+## Approach
+
+1. Ran the Five Copies edit for the add/remove/add as usual.
+2. Verified the package with `new ConfigManager(null)` (defaults only) → all
+   correct: 3.5 gone, `qwen` → 3.8-max.
+3. Verified again with `node dist/cli.js models` → **3.5 still there.** The
+   two commands disagreed. That gap is the whole lesson.
+4. Cause: `ccmr models` goes through **config discovery**, which finds the
+   user's `~/.ccmr/models.yaml` (or a project `models.yaml`) and **merges it
+   over** `DEFAULT_CONFIG` at the *variant* level. Those files carry a full
+   `qwen:` block generated by an old `ccmr init`, so they re-declare the 3.5
+   variants and pin `default_variant: 3.5-plus`. User config wins → the
+   package deletion is invisible on that machine.
+5. Surfaced the gap, got the user's OK to also patch `~/.ccmr/models.yaml`
+   and `ccmr-start/models.yaml`, then re-verified `ccmr models` from each cwd.
+
+## Judgment calls (deliberately NOT done)
+
+- **Did not edit the user's live yaml silently.** Those files weren't named in
+  the request; editing `~/.ccmr` / `ccmr-start` is a "stop and ask" trigger.
+  I reported the merge gap and asked before touching them.
+- **Did not "fix" the 403 in code.** `qwen3.8-max` pay-go returned
+  `403 AccessDenied`; a control test (`qwen3.7-max` → OK on the same key)
+  proved key+endpoint+model_id are right and the 403 is account-side
+  (preview not granted). Account state, not a router bug.
+- **Did not guess a base_url from the lookalike domain.** The request pointed
+  at `platform.qianwenai.com` (not Alibaba's usual `dashscope.aliyuncs.com`).
+  Read the vendor's own Anthropic reference first: the API endpoint is the
+  official `dashscope.aliyuncs.com/apps/anthropic` with `x-api-key`; only the
+  subscription/key portal lives on qianwenai.com. So it's the same endpoint as
+  pay-go, differing only by an `sk-sp-` key → a separate provider
+  (`qwen-plan`, new `QWEN_PLAN_API_KEY`), same step/step-plan precedent.
+
+## Reusable rule
+
+When a request says **remove** (or re-default) a built-in model, the
+`DEFAULT_CONFIG` edit alone changes nothing on any machine whose
+`~/.ccmr/models.yaml` or project `models.yaml` re-declares that provider —
+user config merges over defaults per-variant. Always verify with
+`node dist/cli.js models` (discovery path), not just `ConfigManager(null)`;
+if they disagree, the user's live yaml must be patched too — and that's a
+scope decision to confirm, since those files are rarely named in the request.
+See also [[vendor-platform-split]].