diff --git a/doc/animation-dictionary.md b/doc/animation/动画字典.md
similarity index 99%
rename from doc/animation-dictionary.md
rename to doc/animation/动画字典.md
index 814624a..c72d02e 100644
--- a/doc/animation-dictionary.md
+++ b/doc/animation/动画字典.md
@@ -1,4 +1,4 @@
-# 动画字典 v1
+# 动画字典 v1
 
 ## 1. 目的
 
@@ -355,3 +355,4 @@
 
 **按动画字典逐项补齐高频体验链。**
 
+
diff --git a/doc/animation-integration-workflow.md b/doc/animation/动画接入工作流.md
similarity index 66%
rename from doc/animation-integration-workflow.md
rename to doc/animation/动画接入工作流.md
index fdebce5..c5a6426 100644
--- a/doc/animation-integration-workflow.md
+++ b/doc/animation/动画接入工作流.md
@@ -1,4 +1,4 @@
-# 动画接入工作流
+# 动画接入工作流
 
 ## 1. 目的
 
@@ -266,3 +266,99 @@
 
 **拿到设计稿 -> 转成动画规格 -> 纳入动画字典 -> 选技术实现 -> 做性能分级 -> 再接程序**
 
+---
+
+## 9. 规格模板
+
+后续和设计公司、外包或内部设计协作时，建议每个动画至少补齐下面这些字段：
+
+- 动画 ID
+- 动画名称
+- 所属页面/模块
+- 所属层级：地图空间 / HUD / UI反馈 / 过场
+- 触发事件
+- 触发条件
+- 是否高频
+- 作用对象
+- 起始状态 / 结束状态
+- 动画形式：程序动画 / Lottie / 序列帧 / 视频
+- 资源文件
+- 时长 / 延迟 / 缓动
+- 是否循环
+- 是否可中断
+- 重复触发策略：覆盖 / 忽略 / 重启 / 排队
+- `standard` 表现
+- `lite` 表现
+- 是否允许关闭
+- 验收标准
+
+推荐最小记录格式：
+
+```md
+动画 ID：
+动画名称：
+所属页面/模块：
+所属层级：
+触发事件：
+触发条件：
+动画形式：
+时长：
+缓动：
+是否循环：
+是否可中断：
+重复触发策略：
+standard 表现：
+lite 表现：
+验收标准：
+```
+
+---
+
+## 10. 接入评审清单
+
+在接设计稿或准备开发前，至少先过一遍这份清单：
+
+### 设计侧
+
+- 动画目标是否明确
+- 触发条件是否明确
+- 是否有完整规格和资源
+- 是否提供 `lite` 降级方案
+
+### 技术侧
+
+- 动画属于哪一层
+- 最合适的实现方式是什么
+- 是否真的需要资源文件，还是纯程序动画就够
+
+### 性能侧
+
+- 是否高频触发
+- `lite` 下是保留、简化还是关闭
+- 是否会带来高频 `setData`、持续循环动画或额外桥接成本
+
+### 交互侧
+
+- 是否可中断
+- 多次连续触发会怎样
+- 是否会和现有地图 pulse、HUD 动效、stage 效果冲突
+
+### 验收侧
+
+- 触发时机是否正确
+- 结束时机是否正确
+- 连续触发是否稳定
+- `standard / lite` 是否都可用
+- 低端机是否可接受
+
+---
+
+## 11. 归档说明
+
+原来的：
+
+- `animation-integration-spec.md`
+- `animation-review-checklist.md`
+
+已经归档到 [archive/animation](/D:/dev/cmr-mini/doc/archive/animation)，当前以本文件为统一入口。
+
diff --git a/doc/animation-pipeline-summary.md b/doc/animation/动画管线总结.md
similarity index 99%
rename from doc/animation-pipeline-summary.md
rename to doc/animation/动画管线总结.md
index 46f2280..b5d0a2b 100644
--- a/doc/animation-pipeline-summary.md
+++ b/doc/animation/动画管线总结.md
@@ -1,4 +1,4 @@
-# 动画体系阶段性小结
+# 动画体系阶段性小结
 
 ## 1. 当前定位
 
@@ -190,3 +190,4 @@
 
 **把现有能力收成动画字典，并优先打磨目标切换与跳点这两条高频体验链。**
 
+
diff --git a/doc/animation-integration-spec.md b/doc/archive/animation/动画接入规格模板.md
similarity index 98%
rename from doc/animation-integration-spec.md
rename to doc/archive/animation/动画接入规格模板.md
index e12a5b4..2187efc 100644
--- a/doc/animation-integration-spec.md
+++ b/doc/archive/animation/动画接入规格模板.md
@@ -1,4 +1,4 @@
-# 动画接入规格模板
+# 动画接入规格模板
 
 ## 1. 用途
 
@@ -161,3 +161,4 @@ lite 表现：透明度降低 50%，时长缩短到 220ms
 这份模板的目的是把动画从“视觉稿”变成“工程规格”。  
 只有规格明确，程序才能稳定接入。
 
+
diff --git a/doc/animation-review-checklist.md b/doc/archive/animation/动画接入评审清单.md
similarity index 98%
rename from doc/animation-review-checklist.md
rename to doc/archive/animation/动画接入评审清单.md
index a513cbd..96f7100 100644
--- a/doc/animation-review-checklist.md
+++ b/doc/archive/animation/动画接入评审清单.md
@@ -1,4 +1,4 @@
-# 动画接入评审清单
+# 动画接入评审清单
 
 ## 1. 用途
 
@@ -160,3 +160,4 @@
 动画接入前，只要这份清单里有明显回答不出来的问题，就不应该直接开做。  
 先补规格，再接程序。
 
+
diff --git a/doc/animation-design-proposal.md b/doc/archive/animation/动画设计方案.md
similarity index 99%
rename from doc/animation-design-proposal.md
rename to doc/archive/animation/动画设计方案.md
index af32eea..25bb600 100644
--- a/doc/animation-design-proposal.md
+++ b/doc/archive/animation/动画设计方案.md
@@ -1,4 +1,4 @@
-# 动效系统设计方案
+# 动效系统设计方案
 
 本文档用于整理当前项目后续的动画 / 动效建设方案，目标不是单纯“让界面更花”，而是把动画正式纳入现有架构，成为：
 
@@ -448,3 +448,4 @@
 一句话总结：
 
 **后续动画建设应以“打点成功”和“目标状态”两条高频体验为起点，把动画正式纳入现有架构，而不是继续做零散样式补丁。**
+
diff --git a/doc/backend-config-management-proposal.md b/doc/archive/config/后台配置管理方案.md
similarity index 99%
rename from doc/backend-config-management-proposal.md
rename to doc/archive/config/后台配置管理方案.md
index e62506e..d9e3f47 100644
--- a/doc/backend-config-management-proposal.md
+++ b/doc/archive/config/后台配置管理方案.md
@@ -1,4 +1,4 @@
-# 配置驱动应用的后台管理方案建议
+# 配置驱动应用的后台管理方案建议
 
 本文用于整理当前这类“配置驱动型地图游戏应用”的后台管理建议，面向：
 
@@ -414,3 +414,4 @@ Go 中间层实现“装配成最终 JSON”。
 - 可审核
 - 可回滚
 - 可稳定运行
+
diff --git a/doc/config-template-score-o.md b/doc/archive/config/积分赛配置模板.md
similarity index 99%
rename from doc/config-template-score-o.md
rename to doc/archive/config/积分赛配置模板.md
index 436ce88..8adba5a 100644
--- a/doc/config-template-score-o.md
+++ b/doc/archive/config/积分赛配置模板.md
@@ -1,4 +1,4 @@
-# 积分赛配置文档（基础版）
+# 积分赛配置文档（基础版）
 
 本文档用于给服务端和后台配置设计提供一份可直接落地的积分赛基础模板。  
 目标是先把积分赛入口结构定稳，后续程序功能再逐步细化。
@@ -353,3 +353,4 @@
 - 用 `playfield.controlOverrides` 承载点位分值
 - 用 `game.scoring / game.punch / game.guidance / game.finish` 承载玩法规则
 - 先把静态积分赛入口结构定稳，后续再扩动态积分与更复杂玩法
+
diff --git a/doc/config-design-proposal.md b/doc/archive/config/配置设计方案.md
similarity index 99%
rename from doc/config-design-proposal.md
rename to doc/archive/config/配置设计方案.md
index 42101bb..028592a 100644
--- a/doc/config-design-proposal.md
+++ b/doc/archive/config/配置设计方案.md
@@ -1,4 +1,4 @@
-# 游戏配置文件设计方案（阶段讨论稿）
+# 游戏配置文件设计方案（阶段讨论稿）
 
 本文档用于整理当前阶段推荐的配置文件设计方案，供后端、客户端和后台管理设计参考。  
 目标是让配置真正成为游戏的驱动入口，同时兼顾后续多玩法、多资源、多活动复用。
@@ -585,3 +585,4 @@ KML 适合描述：
 一句话总结：
 
 **KML 描述空间事实，配置描述玩法解释；主配置按 `map / playfield / game / resources / debug` 分层，后续再升级成 manifest 组合。**
+
diff --git a/doc/config-template-classic-sequential.md b/doc/archive/config/顺序赛配置模板.md
similarity index 99%
rename from doc/config-template-classic-sequential.md
rename to doc/archive/config/顺序赛配置模板.md
index bc3a558..a56f9cf 100644
--- a/doc/config-template-classic-sequential.md
+++ b/doc/archive/config/顺序赛配置模板.md
@@ -1,4 +1,4 @@
-# 顺序赛配置文档（基础版）
+# 顺序赛配置文档（基础版）
 
 本文档用于给服务端和后台配置设计提供一份可直接落地的顺序赛基础模板。  
 目标是先把入口配置结构定稳，后续程序功能再逐步细化。
@@ -311,3 +311,4 @@
 - 用 KML 承载空间底稿
 - 用 `game.session / game.punch / game.sequence / game.guidance` 承载玩法规则
 - 先把基础入口结构定稳，后续再细化跳点、惩罚、特殊引导等高级规则
+
diff --git a/doc/config-default-template.md b/doc/archive/config/默认配置模板.md
similarity index 99%
rename from doc/config-default-template.md
rename to doc/archive/config/默认配置模板.md
index 9e3e80c..553a537 100644
--- a/doc/config-default-template.md
+++ b/doc/archive/config/默认配置模板.md
@@ -413,3 +413,4 @@
 
 始终保持一致。
 
+
diff --git a/doc/h5-experience-integration-proposal.md b/doc/archive/experience/H5体验接入方案.md
similarity index 98%
rename from doc/h5-experience-integration-proposal.md
rename to doc/archive/experience/H5体验接入方案.md
index 931674f..ffb94de 100644
--- a/doc/h5-experience-integration-proposal.md
+++ b/doc/archive/experience/H5体验接入方案.md
@@ -1,4 +1,4 @@
-# H5 体验接入方案
+# H5 体验接入方案
 
 本文档用于定义当前项目中 **原生小程序 + H5 定制内容** 的混合接入方案。
 
@@ -410,4 +410,5 @@ H5 接入时必须注意：
 
 详细说明见：
 
-- [platform-capability-notes.md](D:/dev/cmr-mini/doc/platform-capability-notes.md)
+- [platform-capability-notes.md](D:/dev/cmr-mini/doc/debug/平台能力说明.md)
+
diff --git a/doc/experience-shell-proposal.md b/doc/archive/experience/体验壳子方案.md
similarity index 99%
rename from doc/experience-shell-proposal.md
rename to doc/archive/experience/体验壳子方案.md
index 1033869..4bcd6c6 100644
--- a/doc/experience-shell-proposal.md
+++ b/doc/archive/experience/体验壳子方案.md
@@ -1,4 +1,4 @@
-# Experience Shell 方案
+# Experience Shell 方案
 
 本文档用于定义小程序中 H5 定制内容的承载方式。目标不是把 H5 做成真正的同页弹窗，而是做成：
 
@@ -230,3 +230,4 @@ H5 可以通过 bridge 发：
 最稳的方案是：
 
 **独立页面承载，但由原生壳子把它做成 `sheet / dialog / fullscreen` 三种体验形态。**
+
diff --git a/doc/content-experience-layer-proposal.md b/doc/archive/experience/内容体验层方案.md
similarity index 99%
rename from doc/content-experience-layer-proposal.md
rename to doc/archive/experience/内容体验层方案.md
index 7f9661e..08f7a97 100644
--- a/doc/content-experience-layer-proposal.md
+++ b/doc/archive/experience/内容体验层方案.md
@@ -1,4 +1,4 @@
-# 游戏中文创体验层方案
+# 游戏中文创体验层方案
 
 ## 1. 目标
 
@@ -326,3 +326,4 @@ interface ExperienceRuntimeState {
 **把游戏中途的文创与故事体验正式抽成一层独立的 `ContentExperienceLayer`。**
 
 第一阶段先用“控制点完成触发内容卡”跑通最小闭环，后面再逐步扩成完整体验系统。
+
diff --git a/doc/result-scene-proposal.md b/doc/archive/experience/结果页方案.md
similarity index 99%
rename from doc/result-scene-proposal.md
rename to doc/archive/experience/结果页方案.md
index c697753..5906617 100644
--- a/doc/result-scene-proposal.md
+++ b/doc/archive/experience/结果页方案.md
@@ -1,4 +1,4 @@
-# 游戏结算层方案
+# 游戏结算层方案
 
 ## 1. 目标
 
@@ -291,3 +291,4 @@ interface ResultSceneState {
 **正式增加一层 `ResultScene`，承接顺序赛、积分赛以及未来更多玩法的统一结算体验。**
 
 第一阶段先做基础 summary，后续再逐步接入文创奖励、奖章、排名和过场动画。
+
diff --git a/doc/GeminiAnlysis.md b/doc/archive/notes/Gemini分析.md
similarity index 98%
rename from doc/GeminiAnlysis.md
rename to doc/archive/notes/Gemini分析.md
index a13de7a..b26ef27 100644
--- a/doc/GeminiAnlysis.md
+++ b/doc/archive/notes/Gemini分析.md
@@ -1,4 +1,4 @@
-# CMR-Mini 项目深度分析报告 (GeminiAnalysis.md)
+# CMR-Mini 项目深度分析报告 (GeminiAnalysis.md)
 
 ## 1. 项目定位与核心愿景
 **CMR-Mini** 是一个运行在微信小程序环境中的高性能**定向越野 (Orienteering)** 实时竞赛/练习引擎。其核心竞争力在于通过自研的 **WebGL 地图渲染管线** 提供流畅的地图交互，并结合高精度多传感器融合技术（GPS、罗盘、心率、加速度计等）实现精准的运动反馈。
@@ -48,3 +48,4 @@ CMR-Mini 已经建立了一个非常坚实的专业定向越野引擎基础。
 
 ---
 *Generated by Gemini CLI Analysis Tool*
+
diff --git a/doc/temp-gameplay-discussion.md b/doc/archive/notes/临时玩法讨论.md
similarity index 99%
rename from doc/temp-gameplay-discussion.md
rename to doc/archive/notes/临时玩法讨论.md
index 815f920..8db2330 100644
--- a/doc/temp-gameplay-discussion.md
+++ b/doc/archive/notes/临时玩法讨论.md
@@ -1,4 +1,4 @@
-# 临时玩法讨论记录
+# 临时玩法讨论记录
 
 本文档用于临时记录以下讨论内容：
 
@@ -207,3 +207,4 @@
 
 当前这套架构不仅适合传统定向和积分赛，也适合继续承载更游戏化的运动玩法。  
 像贪吃蛇式玩法和区域拾金币玩法，都更像是“新增玩法插件”，而不是“推翻现有底座”。
+
diff --git a/doc/todo-sensor-integration-plan.md b/doc/archive/notes/传感器接入待办.md
similarity index 99%
rename from doc/todo-sensor-integration-plan.md
rename to doc/archive/notes/传感器接入待办.md
index 1b540b1..e3db523 100644
--- a/doc/todo-sensor-integration-plan.md
+++ b/doc/archive/notes/传感器接入待办.md
@@ -1,4 +1,4 @@
-# 传感器接入待开发方案
+# 传感器接入待开发方案
 
 本文档用于整理当前项目后续可利用的传感器能力，分为：
 
@@ -568,3 +568,4 @@
 两端都应遵守同一个原则：
 
 **原始传感器进 `engine/sensor`，高级状态进 `telemetry`，上层只消费统一状态。**
+
diff --git a/doc/todo-multi-user-simulator.md b/doc/archive/notes/多人模拟器待办.md
similarity index 99%
rename from doc/todo-multi-user-simulator.md
rename to doc/archive/notes/多人模拟器待办.md
index 28fbf5d..c60ddcf 100644
--- a/doc/todo-multi-user-simulator.md
+++ b/doc/archive/notes/多人模拟器待办.md
@@ -1,4 +1,4 @@
-# 多人模拟器改造待开发文档
+# 多人模拟器改造待开发文档
 
 本文档用于记录“公网模拟器支持多人开发/多人联调”的待开发方案。  
 当前仅作为设计与排期参考，不代表已经进入实现阶段。
@@ -328,3 +328,4 @@ type ClientSession = {
 
 这项改造建议先保留为待开发事项。  
 当前阶段不急着实现，但应作为后续多人开发与多人玩法联调的重要底座能力。
+
diff --git a/doc/MyToDo.md b/doc/archive/notes/我的待办.md
similarity index 98%
rename from doc/MyToDo.md
rename to doc/archive/notes/我的待办.md
index b1f225c..6885ff3 100644
--- a/doc/MyToDo.md
+++ b/doc/archive/notes/我的待办.md
@@ -1,4 +1,5 @@
-
+
 结果页会根据客户的要求不停的变换，用什么方案能实现这个需求，其实其他的弹出内容也都存在这个问题，样式，内容都时根据客户需求变化的，怎样一种方案设计比较好呢？
 
 
+
diff --git a/doc/archive/归档索引.md b/doc/archive/归档索引.md
new file mode 100644
index 0000000..3182230
--- /dev/null
+++ b/doc/archive/归档索引.md
@@ -0,0 +1,26 @@
+# 文档归档索引
+
+这里存放的是已经完成历史使命的阶段性方案稿、重复模板和临时记录。
+
+这些文档仍然保留，目的是：
+
+- 方便回看历史讨论
+- 追踪某个方案为什么被放弃
+- 避免直接删除造成信息丢失
+
+但它们已经不是当前推荐的主阅读入口。
+
+## 归档分类
+
+- [配置归档](/D:/dev/cmr-mini/doc/archive/config)
+- [动画归档](/D:/dev/cmr-mini/doc/archive/animation)
+- [体验归档](/D:/dev/cmr-mini/doc/archive/experience)
+- [临时笔记归档](/D:/dev/cmr-mini/doc/archive/notes)
+
+## 当前推荐入口
+
+- 总索引：[doc/index.md](/D:/dev/cmr-mini/doc/文档索引.md)
+- 配置索引：[config-docs-index.md](/D:/dev/cmr-mini/doc/config/配置文档索引.md)
+- 动画工作流：[animation-integration-workflow.md](/D:/dev/cmr-mini/doc/animation/动画接入工作流.md)
+- 混合体验架构：[hybrid-experience-architecture.md](/D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
+
diff --git a/doc/backend-config-management-v2.md b/doc/config/后台配置管理方案V2.md
similarity index 99%
rename from doc/backend-config-management-v2.md
rename to doc/config/后台配置管理方案V2.md
index e83153a..607f651 100644
--- a/doc/backend-config-management-v2.md
+++ b/doc/config/后台配置管理方案V2.md
@@ -1,4 +1,4 @@
-# 配置频繁变更场景下的后台管理方案
+# 配置频繁变更场景下的后台管理方案
 
 本文用于整理一套更适合“配置项变化很频繁”的后台方案。
 
@@ -404,3 +404,4 @@ Go 中间层先做最小装配功能。
 这套更适合频繁变化配置项的后台方案是：
 
 **PostgreSQL 存“版本化对象 + jsonb 内容”，Go 中间层做“装配 + 校验 + 发布”，客户端只读静态发布结果。**
+
diff --git a/doc/config-template-full-current.md b/doc/config/当前最全配置模板.md
similarity index 98%
rename from doc/config-template-full-current.md
rename to doc/config/当前最全配置模板.md
index c3789c4..4730a2f 100644
--- a/doc/config-template-full-current.md
+++ b/doc/config/当前最全配置模板.md
@@ -1,4 +1,4 @@
-# 游戏配置全量模板（当前开发实现版）
+# 游戏配置全量模板（当前开发实现版）
 
 本文档提供一份 **截至当前开发状态，客户端已实现或已正式消费的较完整配置模板**。
 
@@ -645,6 +645,7 @@
 
 ## 11. 推荐配套阅读
 
-- [D:\dev\cmr-mini\doc\config-template-minimal-game.md](D:/dev/cmr-mini/doc/config-template-minimal-game.md)
-- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md)
-- [D:\dev\cmr-mini\doc\config-docs-index.md](D:/dev/cmr-mini/doc/config-docs-index.md)
+- [D:\dev\cmr-mini\doc\config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
+- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+- [D:\dev\cmr-mini\doc\config-docs-index.md](D:/dev/cmr-mini/doc/config/配置文档索引.md)
+
diff --git a/doc/config-template-minimal-game.md b/doc/config/最小游戏配置模板.md
similarity index 96%
rename from doc/config-template-minimal-game.md
rename to doc/config/最小游戏配置模板.md
index 75d347d..e4c155f 100644
--- a/doc/config-template-minimal-game.md
+++ b/doc/config/最小游戏配置模板.md
@@ -1,4 +1,4 @@
-# 游戏最小可跑配置模板
+# 游戏最小可跑配置模板
 
 本文档提供一份 **去掉大部分选配项之后，当前客户端可以直接跑起来的最小配置模板**。
 
@@ -197,5 +197,6 @@
 
 如果要做正式项目，请继续参考：
 
-- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
-- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md)
+- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
+- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+
diff --git a/doc/config-template-minimal-score-o.md b/doc/config/积分赛最小配置模板.md
similarity index 97%
rename from doc/config-template-minimal-score-o.md
rename to doc/config/积分赛最小配置模板.md
index ed95deb..bde058d 100644
--- a/doc/config-template-minimal-score-o.md
+++ b/doc/config/积分赛最小配置模板.md
@@ -1,4 +1,4 @@
-# 积分赛最小配置模板
+# 积分赛最小配置模板
 
 本文档提供一份 **积分赛（`score-o`）最小可跑配置模板**。
 
@@ -195,5 +195,6 @@
 
 如果要看更完整版本，请继续参考：
 
-- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
+- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
 - [D:\dev\cmr-mini\event\score-o.json](D:/dev/cmr-mini/event/score-o.json)
+
diff --git a/doc/config-docs-index.md b/doc/config/配置文档索引.md
similarity index 50%
rename from doc/config-docs-index.md
rename to doc/config/配置文档索引.md
index 8a1544e..93ff8f9 100644
--- a/doc/config-docs-index.md
+++ b/doc/config/配置文档索引.md
@@ -11,28 +11,54 @@
 
 ---
 
-## 1. 配置设计总方案
+## 1. 配置核心结构
 
-### [config-design-proposal.md](D:/dev/cmr-mini/doc/config-design-proposal.md)
+当前项目的配置主入口已经稳定在：
 
-作用：
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.30",
+  "app": {},
+  "map": {},
+  "playfield": {},
+  "game": {},
+  "resources": {},
+  "debug": {}
+}
+```
 
-- 说明为什么配置要按 `app / map / playfield / game / resources / debug` 分层
-- 说明 `KML` 和配置的职责边界
-- 说明为什么上位概念用 `playfield`
-- 适合做总体架构参考
+顶层职责建议固定为：
 
-适合阅读时机：
+- `app`
+  活动级基础信息
+- `map`
+  地图底图与空间底座
+- `playfield`
+  当前玩法使用的空间对象定义
+- `game`
+  当前玩法规则配置
+- `resources`
+  资源包与 profile
+- `debug`
+  调试与开发开关
 
-- 设计配置结构
-- 设计客户端读取链
-- 和后端讨论顶层模型时
+当前推荐的核心原则：
+
+- 配置只描述，不执行逻辑
+- `KML` 描述空间事实，配置描述玩法解释
+- `playfield` 是上位概念，`course` 只是其中一种 `kind`
+- 当前阶段继续以单文件配置为主，后续再逐步升级成 manifest 组合
+
+如果你需要看旧版长文讨论稿，已经移到归档：
+
+- [config-design-proposal.md](/D:/dev/cmr-mini/doc/archive/config/配置设计方案.md)
 
 ---
 
 ## 2. 配置选项字典
 
-### [config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md)
+### [config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
 
 作用：
 
@@ -46,7 +72,7 @@
 - 想知道字段应该怎么写
 - 想确认默认行为时
 
-### [track-visualization-proposal.md](D:/dev/cmr-mini/doc/track-visualization-proposal.md)
+### [track-visualization-proposal.md](D:/dev/cmr-mini/doc/rendering/轨迹可视化方案.md)
 
 作用：
 
@@ -54,7 +80,7 @@
 - 说明拖尾轨迹的默认策略与推荐参数
 - 说明当前轨迹样式的配置结构
 
-### [gps-marker-style-system-proposal.md](D:/dev/cmr-mini/doc/gps-marker-style-system-proposal.md)
+### [gps-marker-style-system-proposal.md](D:/dev/cmr-mini/doc/rendering/GPS点样式系统方案.md)
 
 作用：
 
@@ -62,7 +88,7 @@
 - 说明默认样式、朝向小三角和品牌 logo 扩展思路
 - 说明第一阶段最小实现字段和长期演进方向
 
-### [gps-marker-animation-system-proposal.md](D:/dev/cmr-mini/doc/gps-marker-animation-system-proposal.md)
+### [gps-marker-animation-system-proposal.md](D:/dev/cmr-mini/doc/rendering/GPS点动画系统方案.md)
 
 作用：
 
@@ -72,23 +98,9 @@
 
 ---
 
-## 3. 默认配置模板
+## 3. 当前推荐模板
 
-### [config-default-template.md](D:/dev/cmr-mini/doc/config-default-template.md)
-
-作用：
-
-- 提供当前推荐的默认配置模板
-- 包含顺序赛和积分赛的基础默认示例
-- 用于服务端、后台、联调时直接起步
-
-适合阅读时机：
-
-- 新建一份活动配置
-- 想直接照着填配置
-- 想知道最小可运行模板长什么样
-
-### [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config-template-minimal-game.md)
+### [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
 
 作用：
 
@@ -96,21 +108,21 @@
 - 去掉绝大部分选配项
 - 适合快速起步、联调和排查配置链
 
-### [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config-template-minimal-classic-sequential.md)
+### [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config/顺序赛最小配置模板.md)
 
 作用：
 
 - 提供顺序赛最小可跑模板
 - 适合快速起顺序赛活动
 
-### [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config-template-minimal-score-o.md)
+### [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config/积分赛最小配置模板.md)
 
 作用：
 
 - 提供积分赛最小可跑模板
 - 适合快速起积分赛活动
 
-### [config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
+### [config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
 
 作用：
 
@@ -120,27 +132,7 @@
 
 ---
 
-## 4. 按玩法拆分的配置模板文档
-
-### [config-template-classic-sequential.md](D:/dev/cmr-mini/doc/config-template-classic-sequential.md)
-
-作用：
-
-- 解释顺序赛配置结构
-- 说明顺序赛的必填字段和默认值
-- 适合给后端和后台做顺序赛专项参考
-
-### [config-template-score-o.md](D:/dev/cmr-mini/doc/config-template-score-o.md)
-
-作用：
-
-- 解释积分赛配置结构
-- 说明积分赛的必填字段和默认值
-- 适合给后端和后台做积分赛专项参考
-
----
-
-## 5. 运行中的样例配置
+## 4. 运行中的样例配置
 
 ### [event/classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
 
@@ -160,16 +152,9 @@
 
 ---
 
-## 6. 后台与服务端配置管理方案
+## 5. 后台与服务端配置管理方案
 
-### [backend-config-management-proposal.md](D:/dev/cmr-mini/doc/backend-config-management-proposal.md)
-
-作用：
-
-- 第一版后台配置管理建议
-- 适合了解 `Map / Playfield / GameMode / ResourcePack / Event` 这套核心对象
-
-### [backend-config-management-v2.md](D:/dev/cmr-mini/doc/backend-config-management-v2.md)
+### [backend-config-management-v2.md](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
 
 作用：
 
@@ -185,33 +170,33 @@
 
 ---
 
-## 7. 推荐阅读顺序
+## 6. 推荐阅读顺序
 
 如果你是第一次接触这套配置体系，建议按这个顺序看：
 
-1. [config-design-proposal.md](D:/dev/cmr-mini/doc/config-design-proposal.md)
-2. [config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md)
-3. [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config-template-minimal-game.md)
-4. [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config-template-minimal-classic-sequential.md)
-5. [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config-template-minimal-score-o.md)
-6. [config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
+1. 本页“配置核心结构”一节
+2. [config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+3. [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
+4. [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config/顺序赛最小配置模板.md)
+5. [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config/积分赛最小配置模板.md)
+6. [config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
 7. [event/classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
 8. [event/score-o.json](D:/dev/cmr-mini/event/score-o.json)
-9. [backend-config-management-v2.md](D:/dev/cmr-mini/doc/backend-config-management-v2.md)
+9. [backend-config-management-v2.md](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
 
 ---
 
-## 8. 维护约定
+## 7. 维护约定
 
 后续每次新增配置能力时，建议至少同步更新这几处：
 
-1. [config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md)
-2. [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config-template-minimal-game.md)
-3. [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config-template-minimal-classic-sequential.md)
-4. [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config-template-minimal-score-o.md)
-5. [config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
+1. [config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+2. [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
+3. [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config/顺序赛最小配置模板.md)
+4. [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config/积分赛最小配置模板.md)
+5. [config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
 6. 对应玩法的 `event/*.json` 样例
-7. 如果涉及顶层结构变化，再更新 [config-design-proposal.md](D:/dev/cmr-mini/doc/config-design-proposal.md)
+7. 如果涉及顶层结构变化，先更新本页“配置核心结构”一节，再视情况补充归档讨论稿
 
 这样可以保证：
 
@@ -221,3 +206,15 @@
 - 后台录入
 
 保持一致。
+
+---
+
+## 8. 已归档文档
+
+下列文档仍保留在归档目录，但不再作为当前主入口：
+
+- [config-default-template.md](/D:/dev/cmr-mini/doc/archive/config/默认配置模板.md)
+- [config-design-proposal.md](/D:/dev/cmr-mini/doc/archive/config/配置设计方案.md)
+- [config-template-classic-sequential.md](/D:/dev/cmr-mini/doc/archive/config/顺序赛配置模板.md)
+- [config-template-score-o.md](/D:/dev/cmr-mini/doc/archive/config/积分赛配置模板.md)
+- [backend-config-management-proposal.md](/D:/dev/cmr-mini/doc/archive/config/后台配置管理方案.md)
diff --git a/doc/config-option-dictionary.md b/doc/config/配置选项字典.md
similarity index 99%
rename from doc/config-option-dictionary.md
rename to doc/config/配置选项字典.md
index 27c69bd..87e09cd 100644
--- a/doc/config-option-dictionary.md
+++ b/doc/config/配置选项字典.md
@@ -1,4 +1,4 @@
-# 配置选项字典（当前实现版）
+# 配置选项字典（当前实现版）
 
 本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。
 
@@ -1072,3 +1072,4 @@
 - 服务端可对照
 - 后台可录入
 - 客户端联调时有统一参考
+
diff --git a/doc/config-template-minimal-classic-sequential.md b/doc/config/顺序赛最小配置模板.md
similarity index 97%
rename from doc/config-template-minimal-classic-sequential.md
rename to doc/config/顺序赛最小配置模板.md
index 30d3633..5dd1577 100644
--- a/doc/config-template-minimal-classic-sequential.md
+++ b/doc/config/顺序赛最小配置模板.md
@@ -1,4 +1,4 @@
-# 顺序赛最小配置模板
+# 顺序赛最小配置模板
 
 本文档提供一份 **顺序赛（`classic-sequential`）最小可跑配置模板**。
 
@@ -160,5 +160,6 @@
 
 如果要看更完整版本，请继续参考：
 
-- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
+- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
 - [D:\dev\cmr-mini\event\classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
+
diff --git a/doc/sensor-current-summary.md b/doc/debug/传感器现状总结.md
similarity index 97%
rename from doc/sensor-current-summary.md
rename to doc/debug/传感器现状总结.md
index a9c704a..3bbe24a 100644
--- a/doc/sensor-current-summary.md
+++ b/doc/debug/传感器现状总结.md
@@ -1,4 +1,4 @@
-# 传感器现状总结
+# 传感器现状总结
 
 本文档用于说明当前小程序版本已经接入并实际使用的传感器/输入源、它们在系统中的作用，以及当前阶段的稳定边界。
 
@@ -231,4 +231,5 @@
 
 详细说明见：
 
-- [platform-capability-notes.md](D:/dev/cmr-mini/doc/platform-capability-notes.md)
+- [platform-capability-notes.md](D:/dev/cmr-mini/doc/debug/平台能力说明.md)
+
diff --git a/doc/platform-capability-notes.md b/doc/debug/平台能力说明.md
similarity index 98%
rename from doc/platform-capability-notes.md
rename to doc/debug/平台能力说明.md
index 4c32230..b2e6799 100644
--- a/doc/platform-capability-notes.md
+++ b/doc/debug/平台能力说明.md
@@ -1,4 +1,4 @@
-# 平台能力与主体限制说明
+# 平台能力与主体限制说明
 
 本文档用于记录当前项目在 **微信小程序平台能力** 上已经确认的边界，避免后续把环境或主体限制误判成代码问题。
 
@@ -142,3 +142,4 @@
 - 原生主流程继续开发
 - H5 和高级传感器按“预留 + 待验证”处理
 - 待企业主体生效后，再统一回归验证
+
diff --git a/doc/mock-simulator-debug-log-proposal.md b/doc/debug/模拟器调试日志方案.md
similarity index 98%
rename from doc/mock-simulator-debug-log-proposal.md
rename to doc/debug/模拟器调试日志方案.md
index 24c71b6..57e657b 100644
--- a/doc/mock-simulator-debug-log-proposal.md
+++ b/doc/debug/模拟器调试日志方案.md
@@ -1,4 +1,4 @@
-# 模拟器调试日志方案
+# 模拟器调试日志方案
 
 ## 目标
 
@@ -123,3 +123,4 @@
 ## 当前结论
 
 先把 `gps-logo` 调试链打通，再回头用模拟器日志查 logo 为什么不显示，比继续把临时字段堆在调试面板里更稳。
+
diff --git a/doc/compass-debugging-notes.md b/doc/debug/罗盘排障记录.md
similarity index 99%
rename from doc/compass-debugging-notes.md
rename to doc/debug/罗盘排障记录.md
index 536d676..0b4d96a 100644
--- a/doc/compass-debugging-notes.md
+++ b/doc/debug/罗盘排障记录.md
@@ -1,4 +1,4 @@
-# 罗盘问题排查记录
+# 罗盘问题排查记录
 
 ## 背景
 
@@ -210,3 +210,4 @@
 ## 一句话经验
 
 **在微信小程序里，Android 罗盘监听的稳定性比 iOS 更脆；某些看似冗余的 `start()` 调用，实际是平台兼容补丁，不应该在没有真机回归的情况下清理。**
+
diff --git a/doc/debug/调试文档索引.md b/doc/debug/调试文档索引.md
new file mode 100644
index 0000000..ba2724f
--- /dev/null
+++ b/doc/debug/调试文档索引.md
@@ -0,0 +1,34 @@
+# 调试文档索引
+
+这一组文档用于记录：
+
+- 平台能力边界
+- 传感器问题排查
+- 模拟器日志方案
+- 当前调试约束和回归重点
+
+## 当前主文档
+
+- [平台能力说明](/D:/dev/cmr-mini/doc/debug/平台能力说明.md)
+  用于记录主体能力、`web-view`、传感器等平台边界。
+- [模拟器调试日志方案](/D:/dev/cmr-mini/doc/debug/模拟器调试日志方案.md)
+  用于说明 mock simulator 的日志旁路与 `debug-log` 协议。
+- [传感器当前状态总结](/D:/dev/cmr-mini/doc/debug/传感器现状总结.md)
+  用于看当前已确认的传感器状态与调试结论。
+- [罗盘问题记录](/D:/dev/cmr-mini/doc/debug/罗盘排障记录.md)
+  用于回看 Android / iOS 罗盘保活链的排查过程。
+
+## 推荐阅读顺序
+
+1. [platform-capability-notes.md](/D:/dev/cmr-mini/doc/debug/平台能力说明.md)
+2. [sensor-current-summary.md](/D:/dev/cmr-mini/doc/debug/传感器现状总结.md)
+3. [mock-simulator-debug-log-proposal.md](/D:/dev/cmr-mini/doc/debug/模拟器调试日志方案.md)
+4. [compass-debugging-notes.md](/D:/dev/cmr-mini/doc/debug/罗盘排障记录.md)
+
+## 使用建议
+
+- 看“当前限制”和“为什么会这样”，优先看平台能力说明。
+- 看“现在系统是什么状态”，优先看传感器现状总结。
+- 看“以后日志怎么打”，优先看模拟器日志方案。
+- 看“为什么罗盘以前坏过”，再去看罗盘问题记录。
+
diff --git a/doc/native-h5-bridge-spec.md b/doc/experience/原生与H5桥接规范.md
similarity index 98%
rename from doc/native-h5-bridge-spec.md
rename to doc/experience/原生与H5桥接规范.md
index d5f69fa..7b98a57 100644
--- a/doc/native-h5-bridge-spec.md
+++ b/doc/experience/原生与H5桥接规范.md
@@ -1,4 +1,4 @@
-# 原生与 H5 Bridge 协议草案
+# 原生与 H5 Bridge 协议草案
 
 本文档定义当前项目中 **原生小程序** 与 **H5 定制内容页** 之间的基础通信协议。
 
@@ -30,7 +30,7 @@
 
 详细说明见：
 
-- [platform-capability-notes.md](D:/dev/cmr-mini/doc/platform-capability-notes.md)
+- [platform-capability-notes.md](D:/dev/cmr-mini/doc/debug/平台能力说明.md)
 
 ---
 
@@ -379,3 +379,4 @@ Bridge 的第一阶段目标，不是做成万能总线，而是：
 - 结果提交
 
 这 5 条做稳，就足够支撑第一波客户定制需求。
+
diff --git a/doc/hybrid-experience-architecture.md b/doc/experience/混合体验架构方案.md
similarity index 83%
rename from doc/hybrid-experience-architecture.md
rename to doc/experience/混合体验架构方案.md
index b9d0067..af2e164 100644
--- a/doc/hybrid-experience-architecture.md
+++ b/doc/experience/混合体验架构方案.md
@@ -1,4 +1,4 @@
-# 混合体验架构方案
+# 混合体验架构方案
 
 本文档用于说明当前项目在 **结果页、文创内容页、客户定制体验页** 上的长期承载方案。
 
@@ -451,3 +451,62 @@ H5 主要用于高自由度需求。
 **原生模板保底、原生有限 DSL 承担中度变化、H5 承担高定制内容。**
 
 这三层结合起来，既能保证核心体验稳定，也能承接客户高频变化需求。
+
+---
+
+## 13. 当前运行时分层
+
+结合目前已经落地的实现，当前项目的运行时分工已经比较明确：
+
+### 13.1 游戏中途内容
+
+- 即时弹出的内容：原生内容卡
+- 内容卡模板：原生模板系统
+- 内容卡上的 CTA：再进入 H5 详情页或互动任务页
+
+也就是：
+
+```text
+控制点触发
+  ↓
+原生内容卡
+  ↓
+查看详情 / 开始互动
+  ↓
+H5 详情页或任务页
+```
+
+### 13.2 结果页
+
+- 原生结果页始终保底
+- H5 结果页只做增强版
+- H5 打不开时，结果仍然可在原生层完整查看
+
+### 13.3 H5 壳子
+
+经过真机验证，`web-view` 不再承担局部弹窗职责。
+
+当前应统一按：
+
+- 内容详情页：整页 H5
+- 互动任务页：整页 H5
+- 定制结果页：整页 H5
+
+来理解它。
+
+---
+
+## 14. 当前主文档与归档关系
+
+当前建议优先阅读：
+
+- [hybrid-experience-architecture.md](D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
+- [native-h5-bridge-spec.md](D:/dev/cmr-mini/doc/experience/原生与H5桥接规范.md)
+
+已归档但仍可回看的阶段性方案：
+
+- [content-experience-layer-proposal.md](/D:/dev/cmr-mini/doc/archive/experience/内容体验层方案.md)
+- [result-scene-proposal.md](/D:/dev/cmr-mini/doc/archive/experience/结果页方案.md)
+- [experience-shell-proposal.md](/D:/dev/cmr-mini/doc/archive/experience/体验壳子方案.md)
+- [h5-experience-integration-proposal.md](/D:/dev/cmr-mini/doc/archive/experience/H5体验接入方案.md)
+
diff --git a/doc/gameplay-ideas-proposal.md b/doc/gameplay/玩法构想方案.md
similarity index 99%
rename from doc/gameplay-ideas-proposal.md
rename to doc/gameplay/玩法构想方案.md
index dcd393c..7a14375 100644
--- a/doc/gameplay-ideas-proposal.md
+++ b/doc/gameplay/玩法构想方案.md
@@ -1,4 +1,4 @@
-# 新玩法建议方案
+# 新玩法建议方案
 
 本文档用于整理当前阶段值得考虑的新游戏玩法方向，重点回答以下问题：
 
@@ -439,3 +439,4 @@
 
 当前这套架构已经不只是适合传统顺序赛和积分赛，也适合继续承载更游戏化、更有传播性的运动玩法。  
 如果只优先选一个最值得推进的新玩法，建议先做：`幽灵追逐赛`。
+
diff --git a/doc/cloudflare-tunnel-dev-guide.md b/doc/gateway/Cloudflare隧道开发说明.md
similarity index 99%
rename from doc/cloudflare-tunnel-dev-guide.md
rename to doc/gateway/Cloudflare隧道开发说明.md
index 07ee4af..64e50c8 100644
--- a/doc/cloudflare-tunnel-dev-guide.md
+++ b/doc/gateway/Cloudflare隧道开发说明.md
@@ -1,4 +1,4 @@
-# Realtime Gateway + Cloudflare Tunnel 本机联调说明
+# Realtime Gateway + Cloudflare Tunnel 本机联调说明
 
 本文档说明如何在**不正式部署到线上服务器**的前提下，把本机的 `realtime-gateway` 暴露给外部设备或远程联调方。
 
@@ -285,3 +285,4 @@ npm run mock-gps-sim
 5. 等你需要固定域名或更稳定的入口时，再切换 Named Tunnel
 
 这条路径最轻、最稳，也最符合你现在“先不正式上线”的目标。
+
diff --git a/doc/realtime-gateway-runbook.md b/doc/gateway/实时网关运行手册.md
similarity index 99%
rename from doc/realtime-gateway-runbook.md
rename to doc/gateway/实时网关运行手册.md
index d03a4f0..5d4ea3e 100644
--- a/doc/realtime-gateway-runbook.md
+++ b/doc/gateway/实时网关运行手册.md
@@ -1,4 +1,4 @@
-# Realtime Gateway 运行手册
+# Realtime Gateway 运行手册
 
 本文档用于整理当前 `realtime-gateway` 的构建、运行、联调和排障方式，覆盖今天已经落地的能力。
 
@@ -441,3 +441,4 @@ go run .\cmd\mock-consumer -channel-id ch-xxxx -token <consumer-token> -topics t
 - 先把网关本身的运行态、流量、实时查看能力做稳
 
 这也是当前最省风险的组合。
+
diff --git a/doc/realtime-device-gateway-architecture.md b/doc/gateway/实时设备网关架构.md
similarity index 99%
rename from doc/realtime-device-gateway-architecture.md
rename to doc/gateway/实时设备网关架构.md
index 9f191c7..85f659f 100644
--- a/doc/realtime-device-gateway-architecture.md
+++ b/doc/gateway/实时设备网关架构.md
@@ -1,4 +1,4 @@
-# 实时设备数据网关最终方案
+# 实时设备数据网关最终方案
 
 本文档用于收敛当前关于 GPS 模拟、中转、监控、规则判定、回放、通知分发等讨论，给出一版可直接进入实现设计的最终方案。
 
@@ -875,3 +875,4 @@ Business Server
 - 后续更多传感器接入
 
 同时又能把实时性能放在系统设计的首位。
+
diff --git a/doc/gateway-mvp-task-breakdown.md b/doc/gateway/网关MVP任务拆分.md
similarity index 98%
rename from doc/gateway-mvp-task-breakdown.md
rename to doc/gateway/网关MVP任务拆分.md
index 89d9bdb..818ed3f 100644
--- a/doc/gateway-mvp-task-breakdown.md
+++ b/doc/gateway/网关MVP任务拆分.md
@@ -1,4 +1,4 @@
-# 实时网关 MVP 拆分
+# 实时网关 MVP 拆分
 
 本文档用于把 `realtime-gateway` 第一阶段工作拆成可执行任务。
 
@@ -121,3 +121,4 @@ MVP 跑通后优先做：
 3. 模拟器对接新协议
 4. 简单规则插件
 5. Dispatcher 插件
+
diff --git a/doc/gateway-protocol-spec.md b/doc/gateway/网关协议规范.md
similarity index 99%
rename from doc/gateway-protocol-spec.md
rename to doc/gateway/网关协议规范.md
index b7c6660..993886d 100644
--- a/doc/gateway-protocol-spec.md
+++ b/doc/gateway/网关协议规范.md
@@ -1,4 +1,4 @@
-# 实时网关协议草案
+# 实时网关协议草案
 
 本文档描述 `realtime-gateway` 第一版协议草案，范围只覆盖 MVP。
 
@@ -342,3 +342,4 @@
 - `plugin_status`
 - `replay_control`
 - `auth_refresh`
+
diff --git a/doc/gateway/网关文档索引.md b/doc/gateway/网关文档索引.md
new file mode 100644
index 0000000..5c161b7
--- /dev/null
+++ b/doc/gateway/网关文档索引.md
@@ -0,0 +1,31 @@
+# 网关文档索引
+
+这一组文档用于承接：
+
+- 实时设备网关总体架构
+- 协议规范
+- MVP 拆分
+- 运行手册
+- Tunnel 开发说明
+
+## 当前主文档
+
+- [实时设备网关架构](/D:/dev/cmr-mini/doc/gateway/实时设备网关架构.md)
+  说明网关的总体定位、角色分工、消息模型和演进方向。
+- [网关协议规范](/D:/dev/cmr-mini/doc/gateway/网关协议规范.md)
+  说明消息结构、topic、角色和控制协议。
+- [运行手册](/D:/dev/cmr-mini/doc/gateway/实时网关运行手册.md)
+  说明本地构建、运行、联调和常见排障方式。
+
+## 补充文档
+
+- [MVP 拆分](/D:/dev/cmr-mini/doc/gateway/网关MVP任务拆分.md)
+- [Cloudflare Tunnel 开发说明](/D:/dev/cmr-mini/doc/gateway/Cloudflare隧道开发说明.md)
+
+## 推荐阅读顺序
+
+1. [realtime-device-gateway-architecture.md](/D:/dev/cmr-mini/doc/gateway/实时设备网关架构.md)
+2. [gateway-protocol-spec.md](/D:/dev/cmr-mini/doc/gateway/网关协议规范.md)
+3. [realtime-gateway-runbook.md](/D:/dev/cmr-mini/doc/gateway/实时网关运行手册.md)
+4. [gateway-mvp-task-breakdown.md](/D:/dev/cmr-mini/doc/gateway/网关MVP任务拆分.md)
+
diff --git a/doc/communication-guidelines.md b/doc/notes/沟通协作建议.md
similarity index 98%
rename from doc/communication-guidelines.md
rename to doc/notes/沟通协作建议.md
index eda02fb..5fa6cb5 100644
--- a/doc/communication-guidelines.md
+++ b/doc/notes/沟通协作建议.md
@@ -1,4 +1,4 @@
-# 沟通协作建议
+# 沟通协作建议
 
 这份文档用于约定后续在 UI 微调、交互细改、规则补充时，怎样沟通最有效，减少来回修改。
 
@@ -94,3 +94,4 @@
 后续最有效的协作方式是：
 
 **需求把边界说死，修改一次只动一层。**
+
diff --git a/doc/gps-marker-animation-system-proposal.md b/doc/rendering/GPS点动画系统方案.md
similarity index 99%
rename from doc/gps-marker-animation-system-proposal.md
rename to doc/rendering/GPS点动画系统方案.md
index 536c37b..5650c87 100644
--- a/doc/gps-marker-animation-system-proposal.md
+++ b/doc/rendering/GPS点动画系统方案.md
@@ -1,4 +1,4 @@
-# GPS 点动画系统方案
+# GPS 点动画系统方案
 
 ## 目标
 
@@ -208,3 +208,4 @@ GPS 点动画不应该做成单一固定动画，而应该做成：
 - `warning`
 
 这 4 种状态的程序化动画跑通，再决定后续是否继续开放更细粒度配置。
+
diff --git a/doc/gps-marker-style-system-proposal.md b/doc/rendering/GPS点样式系统方案.md
similarity index 98%
rename from doc/gps-marker-style-system-proposal.md
rename to doc/rendering/GPS点样式系统方案.md
index 17bf20f..edff34e 100644
--- a/doc/gps-marker-style-system-proposal.md
+++ b/doc/rendering/GPS点样式系统方案.md
@@ -1,4 +1,4 @@
-# GPS 点样式系统方案
+# GPS 点样式系统方案
 
 ## 目标
 
@@ -111,3 +111,4 @@ GPS 点应被视为独立样式系统，而不是固定蓝点。
 - 朝向三角
 
 做稳定，再逐步承接商业品牌化定制。
+
diff --git a/doc/track-visualization-proposal.md b/doc/rendering/轨迹可视化方案.md
similarity index 98%
rename from doc/track-visualization-proposal.md
rename to doc/rendering/轨迹可视化方案.md
index 5bbc71d..5b6c3e0 100644
--- a/doc/track-visualization-proposal.md
+++ b/doc/rendering/轨迹可视化方案.md
@@ -1,4 +1,4 @@
-# 轨迹可视化方案
+# 轨迹可视化方案
 
 本文档定义用户轨迹的显示模式、默认策略与配置结构。
 
@@ -83,3 +83,4 @@
 - 轨迹颜色按心率区间变化
 - 轨迹颜色按速度变化
 - `standard / lite` 下自动降级 glow
+
diff --git a/doc/文档索引.md b/doc/文档索引.md
new file mode 100644
index 0000000..e37f17c
--- /dev/null
+++ b/doc/文档索引.md
@@ -0,0 +1,43 @@
+# 文档索引
+
+## 配置
+
+- [配置文档索引](/D:/dev/cmr-mini/doc/config/配置文档索引.md)
+- [配置选项字典](/D:/dev/cmr-mini/doc/config/配置选项字典.md)
+- [当前最全配置模板](/D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
+
+## 动画
+
+- [动画管线阶段总结](/D:/dev/cmr-mini/doc/animation/动画管线总结.md)
+- [动画字典](/D:/dev/cmr-mini/doc/animation/动画字典.md)
+- [动画接入工作流](/D:/dev/cmr-mini/doc/animation/动画接入工作流.md)
+
+## 体验
+
+- [混合体验架构](/D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
+- [原生与 H5 Bridge 规范](/D:/dev/cmr-mini/doc/experience/原生与H5桥接规范.md)
+
+## 渲染
+
+- [GPS 点样式系统](/D:/dev/cmr-mini/doc/rendering/GPS点样式系统方案.md)
+- [GPS 点动画系统](/D:/dev/cmr-mini/doc/rendering/GPS点动画系统方案.md)
+- [轨迹可视化方案](/D:/dev/cmr-mini/doc/rendering/轨迹可视化方案.md)
+
+## 调试
+
+- [调试文档索引](/D:/dev/cmr-mini/doc/debug/调试文档索引.md)
+
+## 网关
+
+- [网关文档索引](/D:/dev/cmr-mini/doc/gateway/网关文档索引.md)
+
+## 玩法
+
+- [玩法构想方案](/D:/dev/cmr-mini/doc/gameplay/玩法构想方案.md)
+
+## 备注与归档
+
+- 长期保留的少量工作便签见 [notes](/D:/dev/cmr-mini/doc/notes)。
+- 历史方案稿和阶段性讨论稿已移到 [archive](/D:/dev/cmr-mini/doc/archive/归档索引.md)。
+- 正式阅读建议优先从本页和配置索引进入，不再直接平铺浏览全部文档。
+
diff --git a/readme-develop.md b/readme-develop.md
index e6e561f..ad509a2 100644
--- a/readme-develop.md
+++ b/readme-develop.md
@@ -1475,7 +1475,7 @@ GPS：
 
 详细说明见：
 
-- [platform-capability-notes.md](D:/dev/cmr-mini/doc/platform-capability-notes.md)
+- [平台能力说明.md](D:/dev/cmr-mini/doc/debug/平台能力说明.md)
 
 ---
 
diff --git a/realtime-gateway/README.md b/realtime-gateway/README.md
index 7321967..0d797cd 100644
--- a/realtime-gateway/README.md
+++ b/realtime-gateway/README.md
@@ -16,10 +16,10 @@
 
 优先看这几份：
 
-- 运行手册：[realtime-gateway-runbook.md](D:/dev/cmr-mini/doc/realtime-gateway-runbook.md)
-- 架构方案：[realtime-device-gateway-architecture.md](D:/dev/cmr-mini/doc/realtime-device-gateway-architecture.md)
-- 协议说明：[gateway-protocol-spec.md](D:/dev/cmr-mini/doc/gateway-protocol-spec.md)
-- Tunnel 联调：[cloudflare-tunnel-dev-guide.md](D:/dev/cmr-mini/doc/cloudflare-tunnel-dev-guide.md)
+- 运行手册：[实时网关运行手册.md](D:/dev/cmr-mini/doc/gateway/实时网关运行手册.md)
+- 架构方案：[实时设备网关架构.md](D:/dev/cmr-mini/doc/gateway/实时设备网关架构.md)
+- 协议说明：[网关协议规范.md](D:/dev/cmr-mini/doc/gateway/网关协议规范.md)
+- Tunnel 联调：[Cloudflare隧道开发说明.md](D:/dev/cmr-mini/doc/gateway/Cloudflare隧道开发说明.md)
 - 老模拟器桥接说明：[README.md](D:/dev/cmr-mini/tools/mock-gps-sim/README.md)
 
 ## 快速开始
@@ -146,4 +146,4 @@ go run .\cmd\mock-consumer -channel-id ch-xxxx -token <consumer-token> -topics t
 
 更多运行和排障细节，直接看：
 
-- [realtime-gateway-runbook.md](D:/dev/cmr-mini/doc/realtime-gateway-runbook.md)
+- [实时网关运行手册.md](D:/dev/cmr-mini/doc/gateway/实时网关运行手册.md)