docs(readme): consolidate truth-index and docs navigation

docs/SOURCE_OF_TRUTH.md

@@ -0,0 +1,173 @@
+# 文档真相索引
+
+日期：2026-05-21
+项目：`sub2api-cn-relay-manager`
+
+## 当前 Gate 结论
+
+当前最新 gate：`BLOCKED`
+
+原因不是基础导入链路仍未打通，而是：
+1. latest-head fresh host 上，DeepSeek / MiniMax 的 import + access closure 已能进入 `subscription_ready`
+2. account `credentials.model_mapping`、channel `model_mapping/model_pricing`、managed key 视角 `/v1/models` 都已有 live 证据
+3. 但 latest completion smoke 仍未完全通过：
+   - DeepSeek：host `/v1/chat/completions` 仍见 `502`，而上游直探 `200`
+   - MiniMax：上游直探为 `403 insufficient_user_quota`
+4. 因此当前不能宣称 `APPROVED`
+
+一句话：
+- “模型暴露与 access closure 已基本打通”是真
+- “真实 completion 可完全放行”还不是真
+
+## 当前真相文档（按优先级排序）
+
+### 1. `docs/EXECUTION_BOARD.md`
+用途：
+- 当前执行状态
+- 最新 gate
+- 剩余阻断
+- 最短 closure path
+
+解释规则：
+- 这是“当前执行真相”的第一来源
+- 当其他文档与它冲突时，以它为准
+
+### 2. `docs/PRODUCTION_CLOSURE_BOARD.md`
+用途：
+- 当前是否可按 PRD 首版范围放行
+- 哪些是代码门禁，哪些是外部/环境门禁
+- 哪些历史 PASS 不能再直接当当前真相
+
+解释规则：
+- 这是“上线收口真相”的第一来源
+- 若与历史评审/历史任务板冲突，以它为准
+
+### 3. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
+用途：
+- 真实宿主验收的标准步骤
+- 需要收集哪些 artifact
+- 需要验证哪些层级的证据
+
+解释规则：
+- 它定义“怎么验收”
+- 不直接定义当前 gate，当前 gate 仍以上面两份板为准
+
+### 4. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md`
+用途：
+- 已调通的细节
+- 高频误判点
+- 推荐诊断顺序
+- 经验性解释
+
+解释规则：
+- 它解释“为什么之前会误判、现在应该怎么查”
+- 用来辅助 runbook 和执行板，不单独决定 gate
+
+## 次级文档（仍有价值，但必须通过当前真相文档解释）
+
+### `docs/PRD.md`
+- 定义 PRD 首版范围
+- 只能回答“目标应该是什么”，不能单独回答“现在是否已完成”
+
+### `docs/TDD_PLAN.md`
+- 定义测试设计与实现计划
+- 不能单独代表当前真实验收状态
+
+### `docs/DEPLOYMENT.md`
+- 用于部署说明
+- 若与当前执行板冲突，以执行板/收口板为准
+
+### `docs/KNOWN_LIMITATIONS.md`
+- 用于记录仍存在的限制
+- 需要通过当前执行板一起理解，避免把旧限制当作已关闭或反过来
+
+### `docs/plans/2026-05-12-sub2api-cn-relay-manager-implementation-plan.md`
+- 说明最初实现路径
+- 是设计/计划文档，不是当前状态文档
+
+### `docs/2026-05-12-sub2api-cn-relay-manager-solution.md`
+- 说明方案设计与宿主接口认知
+- 可作为背景，但不能直接当当前 gate 依据
+
+## 历史快照文档（只可参考，不可作为当前实现真相）
+
+### `docs/2026-05-18-PRODUCTION_READINESS_REVIEW.md`
+- 性质：历史审查快照
+- 用途：回看当时发现了哪些系统性问题
+- 禁止用法：不能直接引用其中的 `REJECT / CONDITIONAL_APPROVED` 作为当前 gate
+
+### `docs/2026-05-18-PRODUCTION_REMEDIATION_TASK_BOARD.md`
+- 性质：历史整改执行板
+- 用途：回看 2026-05-18 那一轮整改任务是如何收口的
+- 禁止用法：不能直接拿其顶部 gate 文字当当前状态
+
+## artifact 解释规则
+
+### 当前优先证据
+优先看最新一轮、且与 latest-head / fresh host 对齐的 artifact：
+- `artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation`
+- `artifacts/real-host-acceptance/20260521_011544_remote43_minimax_key_import`
+- `artifacts/real-host-acceptance/20260521_011717_remote43_deepseek_key_import`
+- `artifacts/real-host-acceptance/20260521_064910_completion_smoke_calibration.md`
+
+### 历史参考证据
+以下可证明某个阶段“曾经打通过”，但不能直接代表当前真相：
+- `artifacts/real-host-acceptance/20260518_redeploy_matrix`
+- `artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service`
+- `artifacts/real-host-acceptance/20260518_reconcile_hostscope_subscription`
+
+### 证据解释红线
+1. 不能把 `/api/v1/admin/accounts/:id/models` 与 `/v1/models` 混为一谈
+2. 不能把 `/v1/models = 200` 自动推导成 `/v1/chat/completions = 200`
+3. 不能在未核对在线 CRM 进程版本时，就把 live 现象归因为源码仍有缺陷
+4. 不能把 direct probe artifact 的 401/403 单独当成产品主链路失败；先核对 probe key 语义与脚本参数
+
+## 当前执行红线 / 非回归规则
+
+1. channel 创建与纠偏必须同时覆盖：
+   - `model_mapping`
+   - `model_pricing`
+   - `restrict_models=true`
+   - `billing_model_source=channel_mapped`
+
+2. subscription 场景的 gateway probe 语义必须保持：
+   - 最终 probe key 是宿主 managed key
+   - 不是外部原始 `access_api_key`
+
+3. 任何 live 结论都必须先确认：
+   - 在线 CRM 进程启动时间
+   - 对应 git 提交
+   - `PACK_PATH`
+   - `CRM_HOST_BASE`
+
+4. 真实宿主验收必须分三层落证据：
+   - account 视角
+   - managed key / 普通用户 `/v1/models` 视角
+   - completion smoke 视角
+
+## 推荐阅读顺序
+
+### 想知道“现在到底是什么状态”
+1. `docs/SOURCE_OF_TRUTH.md`
+2. `docs/EXECUTION_BOARD.md`
+3. `docs/PRODUCTION_CLOSURE_BOARD.md`
+
+### 想继续做真实宿主验收
+1. `docs/SOURCE_OF_TRUTH.md`
+2. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
+3. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md`
+4. 再看最新 artifact
+
+### 想回顾为什么会演化成现在这样
+1. `docs/SOURCE_OF_TRUTH.md`
+2. `docs/2026-05-18-PRODUCTION_READINESS_REVIEW.md`
+3. `docs/2026-05-18-PRODUCTION_REMEDIATION_TASK_BOARD.md`
+4. 再回到 `docs/EXECUTION_BOARD.md` 看最新真相
+
+## 明确禁止的错误读法
+
+- ❌ 把历史 review/task board 当当前 gate
+- ❌ 把历史 PASS artifact 当当前 latest-head 真相
+- ❌ 把 `/v1/models` 通过当成 completion 已通过
+- ❌ 把 subscription 场景原始 `access_api_key` 当成最终 probe key
+- ❌ 把 harness 参数错误（`PACK_PATH`、容器目标、probe auth）当成产品源码失败