docs: document reasoning ownership and explicit cache migration

.env.example

@@ -17,11 +17,13 @@ LLM__QWEN__1__TIMEOUT_S=120
 # LLM__QWEN__1__TTFT_TIMEOUT_S=30        # 须与 INTER_TOKEN 成对;0 < inter < ttft < timeout
 # LLM__QWEN__1__INTER_TOKEN_TIMEOUT_S=15
 # LLM__QWEN__1__ENABLE_THINKING=true     # 三态: 缺省=不表态 / true=要求开启 / false=要求关闭
-#   本键是 REASONING_EFFORT 的语法糖: true ≡ auto、false ≡ none、缺省 ≡ 不表态
-#   "要求开启"注入什么随 provider 段而定: openai/anthropic/google 三段的开启形态是
-#   on_base={}——一个字节都不注入,走模型自己的默认档(该默认档若不推理,本键不会报错
-#   也不会开推理,见 CHANGELOG 1.3.3「已知限制」/ issue #21);要确保开启请配 REASONING_EFFORT
-# LLM__QWEN__1__REASONING_EFFORT=low     # 本源默认推理档位;缺省=不表态(随模型自己的默认档)
+#   本键是语法糖: true ≡ auto、false ≡ none、缺省 ≡ 不表态。
+#   已登记模型须清单含 AUTO 才接受 true；nearest 不代选强度。
+#   未登记仍尽力＋warning，空 wire 可能零推理字节，不保证开启。
+#   M3 删除糖并选 medium 等表内档；M2.5/M2.7 AUTO 不再偷带 medium。
+#   完整 M1–M9 与缺测见 README「1.3.4 推理配置迁移」。
+#   有受管意图时 EXTRA_BODY/overlay 推理控制同值也拒绝；raw-only 须退出所有意图。
+# LLM__QWEN__1__REASONING_EFFORT=auto     # 本源默认推理档位;缺省=不表态(随模型自己的默认档)
 #   八档(封闭词汇): none | auto | minimal | low | medium | high | xhigh | max
 #     none = 要求不推理(与"缺省不表态"是两回事);auto = 要求推理但不指定强度
 #   与 ENABLE_THINKING 语义矛盾会在装配期报错(如 true + none、false + low),
@@ -114,6 +116,9 @@ PGW_TELEMETRY_BACKEND=none               # sqlite | postgres | none(必填)
 # PGW_PRICING_PATH=config/prices.json           # 可选: {"<model>": {"input_per_1m": x, "output_per_1m": y}};缺省 cost 恒 None
 #                                               # 可选第三档 "cached_input_per_1m": z —— 供应商 prompt cache 命中部分的单价;
 #                                               # 不填即命中部分也按 input 全额计(库不猜折扣率),cost 会偏高
+# 推理语义/fallback/能力表/wire 变化前须换从未使用的新 namespace 或 salt。
+# 保留租户前缀与 epoch；per-call 覆盖也要迁移，只改此处无效。
+# 未迁移仍可回放旧语义并绕过新拒绝；回滚旧身份会重见旧值，库不自动隔离。
 # PGW_CACHE_NAMESPACE=<项目名或租户前缀>          # 缓存启用时必填(防跨项目毒化)
 # PGW_CACHE_TTL_S=604800                        # 缓存启用时必填,须 > 0
 # PGW_STRUCTURED_MAX_RETRIES=2                  # 缺省 2(M2.5);0 = 解析失败不重问(CHS 策略)