diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 782d44f..3ee5b89 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -15,9 +15,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
     - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
         node-version: '22'
         cache: npm
@@ -41,7 +41,7 @@ jobs:
   link-checker:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Link Checker
         uses: lycheeverse/lychee-action@v2.8.0
         with:
diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml
index 1382a4e..91f9501 100644
--- a/.github/workflows/labeler.yml
+++ b/.github/workflows/labeler.yml
@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Run Labeler
-        uses: actions/labeler@v4
+        uses: actions/labeler@v6
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"
           configuration-path: .github/labeler.yml
diff --git a/.github/workflows/welcome.yml b/.github/workflows/welcome.yml
index 1ba3ae1..2e5d42b 100644
--- a/.github/workflows/welcome.yml
+++ b/.github/workflows/welcome.yml
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Welcome new contributor
-        uses: actions/first-interaction@v1
+        uses: actions/first-interaction@v3
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           issue-message: |
@@ -27,4 +27,4 @@ jobs:
 
           pr-message: |
             👋 你好，@${{ github.actor }}！感谢你第一次向 vibe-coding-cn 提交 Pull Request！
-            我们将仔细评审你的贡献。感谢你让这个项目变得更好！
\ No newline at end of file
+            我们将仔细评审你的贡献。感谢你让这个项目变得更好！
diff --git a/AGENTS.md b/AGENTS.md
index 85fa868..3476209 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,7 +9,7 @@
 ### 允许的操作
 - 读取、修改顶层文档：`README.md`、`AGENTS.md`、`CONTRIBUTING.md` 等
 - 读取、修改 `docs/`、`prompts/`、`skills/`、`tools/config/`、`tools/external/` 下的文档与代码
-- 执行 `make lint`、`make check-links`、`make check-details`、`make check-doc-structure`、`make check-directory-docs`、`make check-metadata`、`make check-ai-citation`、prompts-library 转换工具
+- 执行 `make lint`、`make check-links`、`make check-details`、`make check-doc-structure`、`make check-directory-docs`、`make check-metadata`、`make check-ai-citation`、`make sync-doc-toc`、prompts-library 转换工具
 - 新增/修改提示词、技能、文档
 - 提交符合规范的 commit
 
@@ -70,6 +70,7 @@ git push origin develop
 | `make check-directory-docs` | 校验仓库自有目录 README/AGENTS 覆盖 | Python 3 |
 | `make check-metadata` | 校验 metadata 路径与锚点 | Python 3 |
 | `make check-ai-citation` | 校验 llms 与 AI 引用语料路径和锚点 | Python 3 |
+| `make sync-doc-toc` | 根据 taxonomy 和文档锚点重建 docs 细粒度目录 | Python 3 |
 | `make test` | 执行本地质量门禁 | Node.js 22+、Python 3 |
 | `git submodule update --init --recursive` | 初始化外部 Git 仓库指针 | Git |
 | `cd tools/prompts-library && python3 main.py` | 提示词格式转换 | `pip install -r tools/prompts-library/requirements.txt` |
@@ -227,6 +228,7 @@ git push origin develop
 - `scripts/check-directory-docs.py` - 仓库自有目录 README/AGENTS 覆盖检查脚本，供 `make check-directory-docs` 与 CI 使用
 - `scripts/check-metadata.py` - metadata 路径与锚点检查脚本，供 `make check-metadata` 与 CI 使用
 - `scripts/check-ai-citation.py` - llms 与 AI 引用语料路径和锚点检查脚本，供 `make check-ai-citation` 与 CI 使用
+- `scripts/sync-doc-toc.py` - docs 线性 README 细粒度目录重建脚本，供 `make sync-doc-toc` 使用
 - `tools/prompts-library/main.py` - 提示词转换工具入口
 - `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
 - `docs/concepts/README.md#concept-problem-solving` - 问题定义与求解路径底层模型
diff --git a/Makefile b/Makefile
index d5c2196..594de8d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 # Makefile for Vibe Coding Guide
 
-.PHONY: help lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation build test clean
+.PHONY: help lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation sync-doc-toc build test clean clean-deps
 
 help:
 	@echo "Makefile for Vibe Coding Guide"
@@ -14,9 +14,11 @@ help:
 	@echo "  check-directory-docs - Check required README/AGENTS pairs"
 	@echo "  check-metadata - Check metadata paths and anchors"
 	@echo "  check-ai-citation - Check llms and AI citation paths and anchors"
+	@echo "  sync-doc-toc - Regenerate docs fine-grained TOC blocks"
 	@echo "  build    - Verify knowledge base has no build step"
 	@echo "  test     - Run repository quality gates"
 	@echo "  clean    - Remove ignored generated caches"
+	@echo "  clean-deps - Remove local dependency caches"
 	@echo ""
 
 node_modules/.bin/markdownlint: package.json package-lock.json
@@ -50,14 +52,23 @@ check-ai-citation:
 	@echo "Checking llms and AI citation paths and anchors..."
 	@python3 scripts/check-ai-citation.py
 
+sync-doc-toc:
+	@echo "Regenerating docs fine-grained TOC blocks..."
+	@python3 scripts/sync-doc-toc.py
+
 build:
 	@echo "No build step: this repository is a documentation and knowledge-base project."
 
 test: lint check-links check-details check-doc-structure check-directory-docs check-metadata check-ai-citation
 	@echo "Quality gates complete."
 
-clean:
+clean: clean-deps
 	@echo "Cleaning ignored generated caches..."
 	@find . -type d -name '__pycache__' -prune -exec rm -rf {} +
 	@rm -rf tools/prompts-library/prompt_jsonl
 	@echo "Cleanup complete."
+
+clean-deps:
+	@echo "Cleaning local dependency caches..."
+	@rm -rf node_modules
+	@echo "Dependency cleanup complete."
diff --git a/README.md b/README.md
index fb66988..cfad0d5 100644
--- a/README.md
+++ b/README.md
@@ -224,6 +224,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 | 目录 README/AGENTS 覆盖检查 | `make check-directory-docs` | `scripts/check-directory-docs.py` |
 | Metadata 路径检查 | `make check-metadata` | `scripts/check-metadata.py` |
 | AI 引用路径检查 | `make check-ai-citation` | `scripts/check-ai-citation.py` |
+| 重建 docs 细粒度目录 | `make sync-doc-toc` | `scripts/sync-doc-toc.py` |
 | 全部本地质量门禁 | `make test` | `Makefile` |
 | 提示词格式转换 | `cd tools/prompts-library && python3 main.py` | `tools/prompts-library/main.py` |
 | Skill 严格校验示例 | `skills/auto-skill/scripts/validate-skill.sh skills/auto-skill --strict` | `skills/auto-skill/scripts/validate-skill.sh` |
diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt
index 5d403e5..cc1d344 100644
--- a/assets/ai-citation/llms-full.txt
+++ b/assets/ai-citation/llms-full.txt
@@ -51,6 +51,10 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
 - docs/concepts/README.md：核心概念索引，汇总问题求解、拼好码、系统构建方法、开发范式演进、语言层要素和递归自优化系统。
 - docs/concepts/README.md#concept-problem-solving：问题定义、目标、约束、对象、路径。
 - docs/concepts/README.md#concept-glue-coding：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。
+- docs/concepts/README.md#concept-system-building：自顶向下、自底向上与分而治之的系统构建方法。
+- docs/concepts/README.md#concept-development-paradigms：软件开发组织方式和 AI 编程范式的演进。
+- docs/concepts/README.md#concept-language-layers：理解代码所需的语言层级、执行模型、类型系统和工程语义。
+- docs/concepts/README.md#concept-recursive-self-optimizing-system：递归自优化生成系统的形式化模型。
 - docs/philosophy/README.md：哲学方法论、思维模型、编程哲学与底层认知模型入口。
 - docs/philosophy/README.md#philosophy-thinking-models：第一性原理、奥卡姆剃刀、多阶思维、状态空间等认知工具。
 - docs/philosophy/README.md#philosophy-compositional-description-model：对象、状态、快照、序列、过程、变换、同一/差异与关系。
diff --git a/docs/concepts/README.md b/docs/concepts/README.md
index efaa2d1..2506e43 100644
--- a/docs/concepts/README.md
+++ b/docs/concepts/README.md
@@ -27,8 +27,12 @@
 - [1. 问题求解](#concept-problem-solving)
   - [不会操作？先让网页 AI 生成逐步执行版](#concept-problem-solving-不会操作先让网页-ai-生成逐步执行版)
   - [描述](#concept-problem-solving-描述)
-  - [一、定义问题](#concept-problem-solving-一定义问题)
-  - [二、求解过程](#concept-problem-solving-二求解过程)
+    - [一、定义问题](#concept-problem-solving-一定义问题)
+    - [二、求解过程](#concept-problem-solving-二求解过程)
+      - [1）目标](#concept-problem-solving-1目标)
+      - [2）约束](#concept-problem-solving-2约束)
+      - [3）对象](#concept-problem-solving-3对象)
+      - [4）路径](#concept-problem-solving-4路径)
   - [一句话总结](#concept-problem-solving-一句话总结)
   - [这个框架为什么很底层](#concept-problem-solving-这个框架为什么很底层)
   - [继续压缩](#concept-problem-solving-继续压缩)
@@ -38,59 +42,64 @@
   - [3. 记忆](#concept-problem-solving-3-记忆)
   - [4. 理解](#concept-problem-solving-4-理解)
   - [5. 搭建体系](#concept-problem-solving-5-搭建体系)
-  - [一、问题从哪里来？](#concept-problem-solving-一问题从哪里来)
-  - [二、问题如何被定义？](#concept-problem-solving-二问题如何被定义)
-  - [三、问题如何被求解？](#concept-problem-solving-三问题如何被求解)
-  - [四、求解如何收敛？](#concept-problem-solving-四求解如何收敛)
+    - [一、问题从哪里来？](#concept-problem-solving-一问题从哪里来)
+    - [二、问题如何被定义？](#concept-problem-solving-二问题如何被定义)
+    - [三、问题如何被求解？](#concept-problem-solving-三问题如何被求解)
+      - [1. 目标决定方向](#concept-problem-solving-1-目标决定方向)
+      - [2. 约束决定边界](#concept-problem-solving-2-约束决定边界)
+      - [3. 对象决定方法](#concept-problem-solving-3-对象决定方法)
+    - [四、求解如何收敛？](#concept-problem-solving-四求解如何收敛)
   - [6. 应用](#concept-problem-solving-6-应用)
-  - [场景一：学习能力](#concept-problem-solving-场景一学习能力)
-  - [场景二：工作项目推进](#concept-problem-solving-场景二工作项目推进)
-  - [场景三：个人决策](#concept-problem-solving-场景三个人决策)
+    - [场景一：学习能力](#concept-problem-solving-场景一学习能力)
+    - [场景二：工作项目推进](#concept-problem-solving-场景二工作项目推进)
+    - [场景三：个人决策](#concept-problem-solving-场景三个人决策)
   - [7. 思辨](#concept-problem-solving-7-思辨)
-  - [常见误区一：把“现象”当成“问题”](#concept-problem-solving-常见误区一把现象当成问题)
-  - [常见误区二：一上来就找方法](#concept-problem-solving-常见误区二一上来就找方法)
-  - [常见误区三：只执行，不校正](#concept-problem-solving-常见误区三只执行不校正)
-  - [易混点：问题求解能力 vs 执行力](#concept-problem-solving-易混点问题求解能力-vs-执行力)
-  - [值得思考的问题](#concept-problem-solving-值得思考的问题)
+    - [常见误区一：把“现象”当成“问题”](#concept-problem-solving-常见误区一把现象当成问题)
+    - [常见误区二：一上来就找方法](#concept-problem-solving-常见误区二一上来就找方法)
+    - [常见误区三：只执行，不校正](#concept-problem-solving-常见误区三只执行不校正)
+    - [易混点：问题求解能力 vs 执行力](#concept-problem-solving-易混点问题求解能力-vs-执行力)
+    - [值得思考的问题](#concept-problem-solving-值得思考的问题)
   - [8. 创新](#concept-problem-solving-8-创新)
-  - [一、迁移到学习系统](#concept-problem-solving-一迁移到学习系统)
-  - [二、迁移到个人成长](#concept-problem-solving-二迁移到个人成长)
-  - [三、迁移到创新能力](#concept-problem-solving-三迁移到创新能力)
-  - [四、迁移到 AI 时代](#concept-problem-solving-四迁移到-ai-时代)
+    - [一、迁移到学习系统](#concept-problem-solving-一迁移到学习系统)
+    - [二、迁移到个人成长](#concept-problem-solving-二迁移到个人成长)
+    - [三、迁移到创新能力](#concept-problem-solving-三迁移到创新能力)
+    - [四、迁移到 AI 时代](#concept-problem-solving-四迁移到-ai-时代)
   - [9. 内化](#concept-problem-solving-9-内化)
-  - [立即可执行的行动建议](#concept-problem-solving-立即可执行的行动建议)
+    - [立即可执行的行动建议](#concept-problem-solving-立即可执行的行动建议)
+      - [行动一：用一句话重写你现在的问题](#concept-problem-solving-行动一用一句话重写你现在的问题)
+      - [行动二：建立一个“问题求解清单”](#concept-problem-solving-行动二建立一个问题求解清单)
 - [2. 拼好码](#concept-glue-coding)
   - [关系定位](#concept-glue-coding-关系定位)
   - [一句话定义](#concept-glue-coding-一句话定义)
   - [颠覆性宣言](#concept-glue-coding-颠覆性宣言)
   - [核心理念](#concept-glue-coding-核心理念)
-  - [范式转移](#concept-glue-coding-范式转移)
+    - [范式转移](#concept-glue-coding-范式转移)
   - [架构哲学](#concept-glue-coding-架构哲学)
   - [核心链路](#concept-glue-coding-核心链路)
   - [为什么有效](#concept-glue-coding-为什么有效)
-  - [1. 幻觉问题：从“发明”转向“核验”](#concept-glue-coding-1-幻觉问题从发明转向核验)
-  - [2. 复杂性问题：转交给成熟生态](#concept-glue-coding-2-复杂性问题转交给成熟生态)
-  - [3. 门槛问题：从底层实现转向业务编排](#concept-glue-coding-3-门槛问题从底层实现转向业务编排)
+    - [1. 幻觉问题：从“发明”转向“核验”](#concept-glue-coding-1-幻觉问题从发明转向核验)
+    - [2. 复杂性问题：转交给成熟生态](#concept-glue-coding-2-复杂性问题转交给成熟生态)
+    - [3. 门槛问题：从底层实现转向业务编排](#concept-glue-coding-3-门槛问题从底层实现转向业务编排)
   - [胶水原则](#concept-glue-coding-胶水原则)
   - [决策顺序](#concept-glue-coding-决策顺序)
   - [成熟方案判断标准](#concept-glue-coding-成熟方案判断标准)
   - [胶水代码应该做什么](#concept-glue-coding-胶水代码应该做什么)
   - [胶水代码不应该做什么](#concept-glue-coding-胶水代码不应该做什么)
   - [实践流程](#concept-glue-coding-实践流程)
-  - [使用 GitHub Topics 找成熟能力](#concept-glue-coding-使用-github-topics-找成熟能力)
+    - [使用 GitHub Topics 找成熟能力](#concept-glue-coding-使用-github-topics-找成熟能力)
   - [经典案例](#concept-glue-coding-经典案例)
-  - [Polymarket 数据分析 Bot](#concept-glue-coding-polymarket-数据分析-bot)
+    - [Polymarket 数据分析 Bot](#concept-glue-coding-polymarket-数据分析-bot)
   - [常见场景](#concept-glue-coding-常见场景)
-  - [登录认证](#concept-glue-coding-登录认证)
-  - [AI 客服](#concept-glue-coding-ai-客服)
-  - [订单流程](#concept-glue-coding-订单流程)
+    - [登录认证](#concept-glue-coding-登录认证)
+    - [AI 客服](#concept-glue-coding-ai-客服)
+    - [订单流程](#concept-glue-coding-订单流程)
   - [偏离协议](#concept-glue-coding-偏离协议)
   - [胶水原则之禅](#concept-glue-coding-胶水原则之禅)
   - [与相近概念的区别](#concept-glue-coding-与相近概念的区别)
-  - [拼好码 vs 胶水编程](#concept-glue-coding-拼好码-vs-胶水编程)
-  - [拼好码 vs 低代码](#concept-glue-coding-拼好码-vs-低代码)
-  - [拼好码 vs 微服务](#concept-glue-coding-拼好码-vs-微服务)
-  - [拼好码 vs 自研平台化](#concept-glue-coding-拼好码-vs-自研平台化)
+    - [拼好码 vs 胶水编程](#concept-glue-coding-拼好码-vs-胶水编程)
+    - [拼好码 vs 低代码](#concept-glue-coding-拼好码-vs-低代码)
+    - [拼好码 vs 微服务](#concept-glue-coding-拼好码-vs-微服务)
+    - [拼好码 vs 自研平台化](#concept-glue-coding-拼好码-vs-自研平台化)
   - [AI 时代的拼好码](#concept-glue-coding-ai-时代的拼好码)
   - [内化](#concept-glue-coding-内化)
   - [延伸阅读](#concept-glue-coding-延伸阅读)
@@ -119,14 +128,14 @@
   - [五、给你一个真正工程级的目标](#concept-language-layers-五给你一个真正工程级的目标)
   - [六、工程级追加：L9–L12（从"看懂"到"架构"）](#concept-language-layers-六工程级追加l9l12从看懂到架构)
   - [🧠 L9：时间维度模型（90% 人完全没意识到）](#concept-language-layers-l9时间维度模型90-人完全没意识到)
-  - [你必须能一眼判断：](#concept-language-layers-你必须能一眼判断)
+    - [你必须能一眼判断：](#concept-language-layers-你必须能一眼判断)
   - [🧠 L10：资源模型（CPU / IO / 内存 / 网络）](#concept-language-layers-l10资源模型cpu-io-内存-网络)
-  - [示例](#concept-language-layers-示例)
+    - [示例](#concept-language-layers-示例)
   - [🧠 L11：隐含契约 & 非语法规则（工程真相）](#concept-language-layers-l11隐含契约-非语法规则工程真相)
-  - [你必须识别这些"非代码规则"：](#concept-language-layers-你必须识别这些非代码规则)
-  - [示例](#concept-language-layers-示例-2)
+    - [你必须识别这些"非代码规则"：](#concept-language-layers-你必须识别这些非代码规则)
+    - [示例](#concept-language-layers-示例-2)
   - [🧠 L12：代码意图层（顶级能力）](#concept-language-layers-l12代码意图层顶级能力)
-  - [示例](#concept-language-layers-示例-3)
+    - [示例](#concept-language-layers-示例-3)
   - [七、终极完整版：12 层"语言层要素"总表](#concept-language-layers-七终极完整版12-层语言层要素总表)
   - [八、反直觉但真实的结论](#concept-language-layers-八反直觉但真实的结论)
   - [九、工程级自测题（非常准）](#concept-language-layers-九工程级自测题非常准)
@@ -149,9 +158,9 @@
   - [6. 讨论](#concept-recursive-self-optimizing-system-6-讨论)
   - [7. 结论](#concept-recursive-self-optimizing-system-7-结论)
   - [附录：高层次概念释义](#concept-recursive-self-optimizing-system-附录高层次概念释义)
-  - [1. 定义核心角色](#concept-recursive-self-optimizing-system-1-定义核心角色)
-  - [2. 描述递归生命周期](#concept-recursive-self-optimizing-system-2-描述递归生命周期)
-  - [3. 终极目标](#concept-recursive-self-optimizing-system-3-终极目标)
+    - [1. 定义核心角色](#concept-recursive-self-optimizing-system-1-定义核心角色)
+    - [2. 描述递归生命周期](#concept-recursive-self-optimizing-system-2-描述递归生命周期)
+    - [3. 终极目标](#concept-recursive-self-optimizing-system-3-终极目标)
 
 </details>
 
diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
index 480e62b..da69033 100644
--- a/docs/getting-started/README.md
+++ b/docs/getting-started/README.md
@@ -38,8 +38,8 @@
 
 ### 细粒度目录
 
-- [1. Vibe Coding 经验](#vibe-coding-experience)
-- [2. 学习地图](#learning-map)
+  - [vibe-coding-experience](#vibe-coding-experience)
+  - [learning-map](#learning-map)
 - [3. 网络环境配置](#network-environment)
 - [4. CLI 配置](#cli-setup)
 - [5. 开发环境搭建](#development-environment)
diff --git a/docs/philosophy/README.md b/docs/philosophy/README.md
index 5ae3cb2..093ac0b 100644
--- a/docs/philosophy/README.md
+++ b/docs/philosophy/README.md
@@ -26,14 +26,14 @@
 - [1. 思维模型](#philosophy-thinking-models)
   - [使用原则](#philosophy-thinking-models-使用原则)
   - [模型记录区](#philosophy-thinking-models-模型记录区)
-  - [第一性原理](#philosophy-thinking-models-第一性原理)
-  - [奥卡姆剃刀](#philosophy-thinking-models-奥卡姆剃刀)
-  - [网络效应](#philosophy-thinking-models-网络效应)
-  - [思想实验](#philosophy-thinking-models-思想实验)
-  - [逆向思维](#philosophy-thinking-models-逆向思维)
-  - [多阶思维](#philosophy-thinking-models-多阶思维)
-  - [组合描述模型](#philosophy-thinking-models-组合描述模型)
-  - [状态空间思维模型](#philosophy-thinking-models-状态空间思维模型)
+    - [第一性原理](#philosophy-thinking-models-第一性原理)
+    - [奥卡姆剃刀](#philosophy-thinking-models-奥卡姆剃刀)
+    - [网络效应](#philosophy-thinking-models-网络效应)
+    - [思想实验](#philosophy-thinking-models-思想实验)
+    - [逆向思维](#philosophy-thinking-models-逆向思维)
+    - [多阶思维](#philosophy-thinking-models-多阶思维)
+    - [组合描述模型](#philosophy-thinking-models-组合描述模型)
+    - [状态空间思维模型](#philosophy-thinking-models-状态空间思维模型)
 - [2. 组合描述模型](#philosophy-compositional-description-model)
   - [一、对象](#philosophy-compositional-description-model-一对象)
   - [二、状态](#philosophy-compositional-description-model-二状态)
@@ -46,23 +46,23 @@
   - [九、关系](#philosophy-compositional-description-model-九关系)
   - [十、概念之间的结构关系](#philosophy-compositional-description-model-十概念之间的结构关系)
   - [十一、不同学科中的展开](#philosophy-compositional-description-model-十一不同学科中的展开)
-  - [1. 哲学](#philosophy-compositional-description-model-1-哲学)
-  - [2. 数学](#philosophy-compositional-description-model-2-数学)
-  - [3. 物理学](#philosophy-compositional-description-model-3-物理学)
-  - [4. 计算机科学](#philosophy-compositional-description-model-4-计算机科学)
-  - [5. 系统科学](#philosophy-compositional-description-model-5-系统科学)
-  - [6. 语言学和认知科学](#philosophy-compositional-description-model-6-语言学和认知科学)
+    - [1. 哲学](#philosophy-compositional-description-model-1-哲学)
+    - [2. 数学](#philosophy-compositional-description-model-2-数学)
+    - [3. 物理学](#philosophy-compositional-description-model-3-物理学)
+    - [4. 计算机科学](#philosophy-compositional-description-model-4-计算机科学)
+    - [5. 系统科学](#philosophy-compositional-description-model-5-系统科学)
+    - [6. 语言学和认知科学](#philosophy-compositional-description-model-6-语言学和认知科学)
   - [十二、理论上的核心问题](#philosophy-compositional-description-model-十二理论上的核心问题)
-  - [1. 实体优先，还是过程优先](#philosophy-compositional-description-model-1-实体优先还是过程优先)
-  - [2. 同一怎么在变化里成立](#philosophy-compositional-description-model-2-同一怎么在变化里成立)
-  - [3. 差异到底是派生的，还是基础的](#philosophy-compositional-description-model-3-差异到底是派生的还是基础的)
-  - [4. 关系会不会比对象更基础](#philosophy-compositional-description-model-4-关系会不会比对象更基础)
+    - [1. 实体优先，还是过程优先](#philosophy-compositional-description-model-1-实体优先还是过程优先)
+    - [2. 同一怎么在变化里成立](#philosophy-compositional-description-model-2-同一怎么在变化里成立)
+    - [3. 差异到底是派生的，还是基础的](#philosophy-compositional-description-model-3-差异到底是派生的还是基础的)
+    - [4. 关系会不会比对象更基础](#philosophy-compositional-description-model-4-关系会不会比对象更基础)
   - [十三、五层统一模型](#philosophy-compositional-description-model-十三五层统一模型)
-  - [第一层：存在层](#philosophy-compositional-description-model-第一层存在层)
-  - [第二层：表征层](#philosophy-compositional-description-model-第二层表征层)
-  - [第三层：生成层](#philosophy-compositional-description-model-第三层生成层)
-  - [第四层：判定层](#philosophy-compositional-description-model-第四层判定层)
-  - [第五层：结构层](#philosophy-compositional-description-model-第五层结构层)
+    - [第一层：存在层](#philosophy-compositional-description-model-第一层存在层)
+    - [第二层：表征层](#philosophy-compositional-description-model-第二层表征层)
+    - [第三层：生成层](#philosophy-compositional-description-model-第三层生成层)
+    - [第四层：判定层](#philosophy-compositional-description-model-第四层判定层)
+    - [第五层：结构层](#philosophy-compositional-description-model-第五层结构层)
   - [十四、作为一种分析方法](#philosophy-compositional-description-model-十四作为一种分析方法)
   - [十五、结语](#philosophy-compositional-description-model-十五结语)
 - [3. 编程之道](#philosophy-programming-dao)
@@ -122,36 +122,36 @@
   - [总体作业流](#philosophy-methodology-toolbox-总体作业流)
   - [推荐底座（Python）](#philosophy-methodology-toolbox-推荐底座python)
   - [方法论](#philosophy-methodology-toolbox-方法论)
-  - [1. 现象学还原（悬置假设）](#philosophy-methodology-toolbox-1-现象学还原悬置假设)
-  - [2. 正反合（三段迭代）](#philosophy-methodology-toolbox-2-正反合三段迭代)
-  - [3. 可证伪主义（波普尔）](#philosophy-methodology-toolbox-3-可证伪主义波普尔)
-  - [4. 形式化方法（轻量形式化）](#philosophy-methodology-toolbox-4-形式化方法轻量形式化)
-  - [5. 奥卡姆剃刀（最小复杂度）](#philosophy-methodology-toolbox-5-奥卡姆剃刀最小复杂度)
-  - [6. 实用主义（以指标为准）](#philosophy-methodology-toolbox-6-实用主义以指标为准)
-  - [7. 系统论/整体论（边界与反馈回路）](#philosophy-methodology-toolbox-7-系统论整体论边界与反馈回路)
-  - [8. 诠释学（语境澄清）](#philosophy-methodology-toolbox-8-诠释学语境澄清)
-  - [9. "钢人化"原则（最强版本理解）](#philosophy-methodology-toolbox-9-钢人化原则最强版本理解)
-  - [10. 决策论/机会成本（可逆优先）](#philosophy-methodology-toolbox-10-决策论机会成本可逆优先)
-  - [11. 反事实推理（Counterfactuals）](#philosophy-methodology-toolbox-11-反事实推理counterfactuals)
-  - [12. 溯因推理（Abduction，最佳解释）](#philosophy-methodology-toolbox-12-溯因推理abduction最佳解释)
-  - [13. 贝叶斯式信念更新（与溯因配合）](#philosophy-methodology-toolbox-13-贝叶斯式信念更新与溯因配合)
-  - [14. 反思平衡（Reflective equilibrium）](#philosophy-methodology-toolbox-14-反思平衡reflective-equilibrium)
-  - [15. 概念分析 / 概念工程](#philosophy-methodology-toolbox-15-概念分析-概念工程)
-  - [16. 方法论怀疑（笛卡尔式）](#philosophy-methodology-toolbox-16-方法论怀疑笛卡尔式)
-  - [17. 视角三角测量（Triangulation）](#philosophy-methodology-toolbox-17-视角三角测量triangulation)
-  - [18. 机制解释（Mechanistic explanation）](#philosophy-methodology-toolbox-18-机制解释mechanistic-explanation)
-  - [19. 错误认识论（Error epistemology）](#philosophy-methodology-toolbox-19-错误认识论error-epistemology)
-  - [20. 实验哲学（x-phi）](#philosophy-methodology-toolbox-20-实验哲学x-phi)
-  - [21. 计算哲学（Computational philosophy）](#philosophy-methodology-toolbox-21-计算哲学computational-philosophy)
-  - [22. 自然化认识论（Naturalized epistemology）](#philosophy-methodology-toolbox-22-自然化认识论naturalized-epistemology)
-  - [23. 贝叶斯认识论（Bayesian epistemology）](#philosophy-methodology-toolbox-23-贝叶斯认识论bayesian-epistemology)
+    - [1. 现象学还原（悬置假设）](#philosophy-methodology-toolbox-1-现象学还原悬置假设)
+    - [2. 正反合（三段迭代）](#philosophy-methodology-toolbox-2-正反合三段迭代)
+    - [3. 可证伪主义（波普尔）](#philosophy-methodology-toolbox-3-可证伪主义波普尔)
+    - [4. 形式化方法（轻量形式化）](#philosophy-methodology-toolbox-4-形式化方法轻量形式化)
+    - [5. 奥卡姆剃刀（最小复杂度）](#philosophy-methodology-toolbox-5-奥卡姆剃刀最小复杂度)
+    - [6. 实用主义（以指标为准）](#philosophy-methodology-toolbox-6-实用主义以指标为准)
+    - [7. 系统论/整体论（边界与反馈回路）](#philosophy-methodology-toolbox-7-系统论整体论边界与反馈回路)
+    - [8. 诠释学（语境澄清）](#philosophy-methodology-toolbox-8-诠释学语境澄清)
+    - [9. "钢人化"原则（最强版本理解）](#philosophy-methodology-toolbox-9-钢人化原则最强版本理解)
+    - [10. 决策论/机会成本（可逆优先）](#philosophy-methodology-toolbox-10-决策论机会成本可逆优先)
+    - [11. 反事实推理（Counterfactuals）](#philosophy-methodology-toolbox-11-反事实推理counterfactuals)
+    - [12. 溯因推理（Abduction，最佳解释）](#philosophy-methodology-toolbox-12-溯因推理abduction最佳解释)
+    - [13. 贝叶斯式信念更新（与溯因配合）](#philosophy-methodology-toolbox-13-贝叶斯式信念更新与溯因配合)
+    - [14. 反思平衡（Reflective equilibrium）](#philosophy-methodology-toolbox-14-反思平衡reflective-equilibrium)
+    - [15. 概念分析 / 概念工程](#philosophy-methodology-toolbox-15-概念分析-概念工程)
+    - [16. 方法论怀疑（笛卡尔式）](#philosophy-methodology-toolbox-16-方法论怀疑笛卡尔式)
+    - [17. 视角三角测量（Triangulation）](#philosophy-methodology-toolbox-17-视角三角测量triangulation)
+    - [18. 机制解释（Mechanistic explanation）](#philosophy-methodology-toolbox-18-机制解释mechanistic-explanation)
+    - [19. 错误认识论（Error epistemology）](#philosophy-methodology-toolbox-19-错误认识论error-epistemology)
+    - [20. 实验哲学（x-phi）](#philosophy-methodology-toolbox-20-实验哲学x-phi)
+    - [21. 计算哲学（Computational philosophy）](#philosophy-methodology-toolbox-21-计算哲学computational-philosophy)
+    - [22. 自然化认识论（Naturalized epistemology）](#philosophy-methodology-toolbox-22-自然化认识论naturalized-epistemology)
+    - [23. 贝叶斯认识论（Bayesian epistemology）](#philosophy-methodology-toolbox-23-贝叶斯认识论bayesian-epistemology)
   - [附录](#philosophy-methodology-toolbox-附录)
-  - [通用"性质测试"提示（可复用）](#philosophy-methodology-toolbox-通用性质测试提示可复用)
-  - [建议的项目框架（最小）](#philosophy-methodology-toolbox-建议的项目框架最小)
+    - [通用"性质测试"提示（可复用）](#philosophy-methodology-toolbox-通用性质测试提示可复用)
+    - [建议的项目框架（最小）](#philosophy-methodology-toolbox-建议的项目框架最小)
   - [使用指南](#philosophy-methodology-toolbox-使用指南)
-  - [现象学还原用于 Vibe Coding](#philosophy-methodology-toolbox-现象学还原用于-vibe-coding)
-  - [辩证法用于 Vibe Coding：正反合](#philosophy-methodology-toolbox-辩证法用于-vibe-coding正反合)
-  - [控制论与科学方法论](#philosophy-methodology-toolbox-控制论与科学方法论)
+    - [现象学还原用于 Vibe Coding](#philosophy-methodology-toolbox-现象学还原用于-vibe-coding)
+    - [辩证法用于 Vibe Coding：正反合](#philosophy-methodology-toolbox-辩证法用于-vibe-coding正反合)
+    - [控制论与科学方法论](#philosophy-methodology-toolbox-控制论与科学方法论)
 
 </details>
 
diff --git a/docs/references/README.md b/docs/references/README.md
index 8998d30..dd8bd7c 100644
--- a/docs/references/README.md
+++ b/docs/references/README.md
@@ -40,7 +40,6 @@
 ### 细粒度目录
 
 - [章节](#stable-anchor)
-  - [子章节](#stable-child-anchor)
 
 </details>
 ```
@@ -56,64 +55,174 @@
   - [使用方式](#reference-engineering-practice-使用方式)
   - [目录](#reference-engineering-practice-目录)
   - [1. 项目架构模板](#reference-engineering-practice-1-项目架构模板)
-  - [1. 使用原则](#reference-engineering-practice-1-使用原则)
-  - [2. 快速选型](#reference-engineering-practice-2-快速选型)
-  - [3. Python Web/API 项目结构](#reference-engineering-practice-3-python-webapi-项目结构)
-  - [4. 数据科学 / 量化项目结构](#reference-engineering-practice-4-数据科学-量化项目结构)
-  - [5. Monorepo 项目结构](#reference-engineering-practice-5-monorepo-项目结构)
-  - [6. Full-Stack Web 应用结构](#reference-engineering-practice-6-full-stack-web-应用结构)
-  - [7. Dataset First 数据服务结构](#reference-engineering-practice-7-dataset-first-数据服务结构)
-  - [8. 架构设计原则](#reference-engineering-practice-8-架构设计原则)
-  - [9. 最低门禁](#reference-engineering-practice-9-最低门禁)
-  - [10. `.gitignore` 推荐模板](#reference-engineering-practice-10-gitignore-推荐模板)
-  - [11. 技术选型参考](#reference-engineering-practice-11-技术选型参考)
-  - [12. 新项目检查清单](#reference-engineering-practice-12-新项目检查清单)
-  - [13. 常见反模式](#reference-engineering-practice-13-常见反模式)
-  - [14. 一句话结论](#reference-engineering-practice-14-一句话结论)
+    - [1. 使用原则](#reference-engineering-practice-1-使用原则)
+    - [2. 快速选型](#reference-engineering-practice-2-快速选型)
+    - [3. Python Web/API 项目结构](#reference-engineering-practice-3-python-webapi-项目结构)
+    - [4. 数据科学 / 量化项目结构](#reference-engineering-practice-4-数据科学-量化项目结构)
+    - [5. Monorepo 项目结构](#reference-engineering-practice-5-monorepo-项目结构)
+    - [6. Full-Stack Web 应用结构](#reference-engineering-practice-6-full-stack-web-应用结构)
+    - [7. Dataset First 数据服务结构](#reference-engineering-practice-7-dataset-first-数据服务结构)
+      - [一句话](#reference-engineering-practice-一句话)
+      - [适合](#reference-engineering-practice-适合)
+      - [不适合直接照抄](#reference-engineering-practice-不适合直接照抄)
+      - [核心原则](#reference-engineering-practice-核心原则)
+      - [标准目录](#reference-engineering-practice-标准目录)
+      - [Dataset 最小结构](#reference-engineering-practice-dataset-最小结构)
+      - [Registry 真相矩阵](#reference-engineering-practice-registry-真相矩阵)
+      - [Dataset 命名](#reference-engineering-practice-dataset-命名)
+      - [Service Entry 与 Runtime](#reference-engineering-practice-service-entry-与-runtime)
+      - [数据模型分层](#reference-engineering-practice-数据模型分层)
+      - [新建数据服务流程](#reference-engineering-practice-新建数据服务流程)
+      - [外部源码接入流程](#reference-engineering-practice-外部源码接入流程)
+    - [8. 架构设计原则](#reference-engineering-practice-8-架构设计原则)
+      - [关注点分离](#reference-engineering-practice-关注点分离)
+      - [可测试性](#reference-engineering-practice-可测试性)
+      - [可配置性](#reference-engineering-practice-可配置性)
+      - [可维护性](#reference-engineering-practice-可维护性)
+      - [版本控制友好](#reference-engineering-practice-版本控制友好)
+    - [9. 最低门禁](#reference-engineering-practice-9-最低门禁)
+      - [代码门禁](#reference-engineering-practice-代码门禁)
+      - [结构门禁](#reference-engineering-practice-结构门禁)
+      - [运行门禁](#reference-engineering-practice-运行门禁)
+      - [数据门禁](#reference-engineering-practice-数据门禁)
+      - [文档门禁](#reference-engineering-practice-文档门禁)
+    - [10. `.gitignore` 推荐模板](#reference-engineering-practice-10-gitignore-推荐模板)
+    - [11. 技术选型参考](#reference-engineering-practice-11-技术选型参考)
+    - [12. 新项目检查清单](#reference-engineering-practice-12-新项目检查清单)
+    - [13. 常见反模式](#reference-engineering-practice-13-常见反模式)
+    - [14. 一句话结论](#reference-engineering-practice-14-一句话结论)
   - [2. 代码组织](#reference-engineering-practice-2-代码组织)
-  - [模块化编程](#reference-engineering-practice-模块化编程)
-  - [命名规范](#reference-engineering-practice-命名规范)
-  - [代码注释](#reference-engineering-practice-代码注释)
-  - [代码格式化](#reference-engineering-practice-代码格式化)
+    - [模块化编程](#reference-engineering-practice-模块化编程)
+    - [命名规范](#reference-engineering-practice-命名规范)
+    - [代码注释](#reference-engineering-practice-代码注释)
+    - [代码格式化](#reference-engineering-practice-代码格式化)
   - [文档](#reference-engineering-practice-文档)
-  - [文档字符串](#reference-engineering-practice-文档字符串)
-  - [自动化文档生成](#reference-engineering-practice-自动化文档生成)
-  - [README 文件](#reference-engineering-practice-readme-文件)
+    - [文档字符串](#reference-engineering-practice-文档字符串)
+    - [自动化文档生成](#reference-engineering-practice-自动化文档生成)
+    - [README 文件](#reference-engineering-practice-readme-文件)
   - [工具](#reference-engineering-practice-工具)
-  - [IDE](#reference-engineering-practice-ide)
+    - [IDE](#reference-engineering-practice-ide)
   - [3. 开发经验](#reference-engineering-practice-3-开发经验)
-  - [目录](#reference-engineering-practice-目录-2)
+    - [目录](#reference-engineering-practice-目录-2)
   - [**1. 变量名维护方案**](#reference-engineering-practice-1-变量名维护方案)
-  - [1.1 新建“变量名大全文件”](#reference-engineering-practice-11-新建变量名大全文件)
+    - [1.1 新建“变量名大全文件”](#reference-engineering-practice-11-新建变量名大全文件)
+      - [文件内容包括（格式示例）：](#reference-engineering-practice-文件内容包括格式示例)
+      - [目的](#reference-engineering-practice-目的)
   - [**2. 文件结构与命名规范**](#reference-engineering-practice-2-文件结构与命名规范)
-  - [2.1 子文件夹内容](#reference-engineering-practice-21-子文件夹内容)
-  - [2.2 文件命名规则](#reference-engineering-practice-22-文件命名规则)
-  - [2.3 变量与定义规则及解释](#reference-engineering-practice-23-变量与定义规则及解释)
+    - [2.1 子文件夹内容](#reference-engineering-practice-21-子文件夹内容)
+    - [2.2 文件命名规则](#reference-engineering-practice-22-文件命名规则)
+    - [2.3 变量与定义规则及解释](#reference-engineering-practice-23-变量与定义规则及解释)
   - [**3. 编码规范**](#reference-engineering-practice-3-编码规范)
+      - [3.1 单一职责（Single Responsibility）](#reference-engineering-practice-31-单一职责single-responsibility)
+      - [3.2 可复用函数 / 构建（Reusable Components）](#reference-engineering-practice-32-可复用函数-构建reusable-components)
+      - [3.3 消费端 / 生产端 / 状态（变量）/ 变换（函数）](#reference-engineering-practice-33-消费端-生产端-状态变量-变换函数)
+      - [3.4 并发（Concurrency）](#reference-engineering-practice-34-并发concurrency)
   - [**4. 系统架构原则**](#reference-engineering-practice-4-系统架构原则)
+      - [4.1 先梳理清楚架构](#reference-engineering-practice-41-先梳理清楚架构)
+      - [4.2 理解需求 → 保持简单 → 自动化测试 → 小步迭代](#reference-engineering-practice-42-理解需求-保持简单-自动化测试-小步迭代)
   - [**5. 程序设计核心思想**](#reference-engineering-practice-5-程序设计核心思想)
-  - [5.1 从问题开始，而不是从代码开始](#reference-engineering-practice-51-从问题开始而不是从代码开始)
-  - [5.2 大问题拆小问题（Divide & Conquer）](#reference-engineering-practice-52-大问题拆小问题divide-conquer)
-  - [5.3 KISS 原则（保持简单）](#reference-engineering-practice-53-kiss-原则保持简单)
-  - [5.4 DRY 原则（不要重复）](#reference-engineering-practice-54-dry-原则不要重复)
-  - [5.5 清晰的命名](#reference-engineering-practice-55-清晰的命名)
-  - [5.6 单一职责](#reference-engineering-practice-56-单一职责)
-  - [5.7 代码可读性优先](#reference-engineering-practice-57-代码可读性优先)
-  - [5.8 合理注释](#reference-engineering-practice-58-合理注释)
-  - [5.9 Make it work → Make it right → Make it fast](#reference-engineering-practice-59-make-it-work-make-it-right-make-it-fast)
-  - [5.10 错误是朋友，调试是必修课](#reference-engineering-practice-510-错误是朋友调试是必修课)
-  - [5.11 Git 版本控制是必备技能](#reference-engineering-practice-511-git-版本控制是必备技能)
-  - [5.12 测试你的代码](#reference-engineering-practice-512-测试你的代码)
-  - [5.13 编程是长期练习](#reference-engineering-practice-513-编程是长期练习)
+    - [5.1 从问题开始，而不是从代码开始](#reference-engineering-practice-51-从问题开始而不是从代码开始)
+    - [5.2 大问题拆小问题（Divide & Conquer）](#reference-engineering-practice-52-大问题拆小问题divide-conquer)
+    - [5.3 KISS 原则（保持简单）](#reference-engineering-practice-53-kiss-原则保持简单)
+    - [5.4 DRY 原则（不要重复）](#reference-engineering-practice-54-dry-原则不要重复)
+    - [5.5 清晰的命名](#reference-engineering-practice-55-清晰的命名)
+    - [5.6 单一职责](#reference-engineering-practice-56-单一职责)
+    - [5.7 代码可读性优先](#reference-engineering-practice-57-代码可读性优先)
+    - [5.8 合理注释](#reference-engineering-practice-58-合理注释)
+    - [5.9 Make it work → Make it right → Make it fast](#reference-engineering-practice-59-make-it-work-make-it-right-make-it-fast)
+    - [5.10 错误是朋友，调试是必修课](#reference-engineering-practice-510-错误是朋友调试是必修课)
+    - [5.11 Git 版本控制是必备技能](#reference-engineering-practice-511-git-版本控制是必备技能)
+    - [5.12 测试你的代码](#reference-engineering-practice-512-测试你的代码)
+    - [5.13 编程是长期练习](#reference-engineering-practice-513-编程是长期练习)
   - [**6. 微服务**](#reference-engineering-practice-6-微服务)
   - [**7. Redis（缓存 / 内存数据库）**](#reference-engineering-practice-7-redis缓存-内存数据库)
   - [**8. 消息队列（Message Queue）**](#reference-engineering-practice-8-消息队列message-queue)
   - [4. AI 编程质量门禁与常见坑](#reference-engineering-practice-4-ai-编程质量门禁与常见坑)
-  - [使用方式](#reference-engineering-practice-使用方式-2)
-  - [目录](#reference-engineering-practice-目录-3)
-  - [1. 系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则)
-  - [2. 强前置条件约束](#reference-engineering-practice-2-强前置条件约束)
-  - [3. 常见坑汇总](#reference-engineering-practice-3-常见坑汇总)
+    - [使用方式](#reference-engineering-practice-使用方式-2)
+    - [目录](#reference-engineering-practice-目录-3)
+    - [1. 系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则)
+        - [核心身份与行为准则](#reference-engineering-practice-核心身份与行为准则)
+        - [沟通与互动](#reference-engineering-practice-沟通与互动)
+        - [任务执行与工作流](#reference-engineering-practice-任务执行与工作流)
+        - [技术与编码规范](#reference-engineering-practice-技术与编码规范)
+        - [安全与防护](#reference-engineering-practice-安全与防护)
+        - [工具使用](#reference-engineering-practice-工具使用)
+    - [2. 强前置条件约束](#reference-engineering-practice-2-强前置条件约束)
+        - [通用开发约束](#reference-engineering-practice-通用开发约束)
+        - [胶水开发约束](#reference-engineering-practice-胶水开发约束)
+        - [系统性代码与功能完整性检查约束](#reference-engineering-practice-系统性代码与功能完整性检查约束)
+      - [一、AI 编码常见伪高性能错误](#reference-engineering-practice-一ai-编码常见伪高性能错误)
+      - [二、AI 容易生成的隐藏低效逻辑](#reference-engineering-practice-二ai-容易生成的隐藏低效逻辑)
+      - [三、新手常见复杂度误区](#reference-engineering-practice-三新手常见复杂度误区)
+      - [四、Python 语法糖误用](#reference-engineering-practice-四python-语法糖误用)
+      - [五、错误的数据结构直觉](#reference-engineering-practice-五错误的数据结构直觉)
+      - [六、缓存误用](#reference-engineering-practice-六缓存误用)
+      - [七、异步误用](#reference-engineering-practice-七异步误用)
+      - [八、多线程 / 多进程误用](#reference-engineering-practice-八多线程-多进程误用)
+      - [九、NumPy 新手错误](#reference-engineering-practice-九numpy-新手错误)
+      - [十、pandas 新手错误](#reference-engineering-practice-十pandas-新手错误)
+      - [十一、PyTorch / 深度学习新手错误](#reference-engineering-practice-十一pytorch-深度学习新手错误)
+      - [十二、GPU 使用新手错误](#reference-engineering-practice-十二gpu-使用新手错误)
+      - [十三、JIT / 编译工具误用](#reference-engineering-practice-十三jit-编译工具误用)
+      - [十四、数据库与 ORM 新手错误](#reference-engineering-practice-十四数据库与-orm-新手错误)
+      - [十五、网络请求新手错误](#reference-engineering-practice-十五网络请求新手错误)
+      - [十六、文件与序列化新手错误](#reference-engineering-practice-十六文件与序列化新手错误)
+      - [十七、日志与观测误用](#reference-engineering-practice-十七日志与观测误用)
+      - [十八、Benchmark 新手错误](#reference-engineering-practice-十八benchmark-新手错误)
+      - [十九、资源配置新手错误](#reference-engineering-practice-十九资源配置新手错误)
+      - [二十、AI 最容易“自信瞎优化”的错误](#reference-engineering-practice-二十ai-最容易自信瞎优化的错误)
+      - [二十一、适合直接放进全局规则的总禁止池](#reference-engineering-practice-二十一适合直接放进全局规则的总禁止池)
+      - [一、数值计算反例](#reference-engineering-practice-一数值计算反例)
+      - [二、内存布局与缓存局部性反例](#reference-engineering-practice-二内存布局与缓存局部性反例)
+      - [三、BLAS / LAPACK / 矩阵计算反例](#reference-engineering-practice-三blas-lapack-矩阵计算反例)
+      - [四、JIT / 编译加速反例](#reference-engineering-practice-四jit-编译加速反例)
+      - [五、并行计算反例](#reference-engineering-practice-五并行计算反例)
+      - [六、共享内存与进程间通信反例](#reference-engineering-practice-六共享内存与进程间通信反例)
+      - [七、GPU / CUDA / 深度学习反例](#reference-engineering-practice-七gpu-cuda-深度学习反例)
+      - [八、PyTorch / TensorFlow 反例](#reference-engineering-practice-八pytorch-tensorflow-反例)
+      - [九、大数据与分布式计算反例](#reference-engineering-practice-九大数据与分布式计算反例)
+      - [十、文件格式与数据读取反例](#reference-engineering-practice-十文件格式与数据读取反例)
+      - [十一、性能测量反例](#reference-engineering-practice-十一性能测量反例)
+      - [十二、资源控制反例](#reference-engineering-practice-十二资源控制反例)
+      - [十三、Python 高性能计算精简总版](#reference-engineering-practice-十三python-高性能计算精简总版)
+      - [一、最高优先级禁止](#reference-engineering-practice-一最高优先级禁止)
+      - [二、推理与决策禁止](#reference-engineering-practice-二推理与决策禁止)
+      - [三、工程质量禁止](#reference-engineering-practice-三工程质量禁止)
+      - [四、代码实现禁止](#reference-engineering-practice-四代码实现禁止)
+      - [五、验证与测试禁止](#reference-engineering-practice-五验证与测试禁止)
+      - [六、工具调用禁止](#reference-engineering-practice-六工具调用禁止)
+      - [七、不可逆与高风险操作禁止](#reference-engineering-practice-七不可逆与高风险操作禁止)
+      - [八、架构与文档禁止](#reference-engineering-practice-八架构与文档禁止)
+      - [九、任务管理禁止](#reference-engineering-practice-九任务管理禁止)
+      - [十、沟通与输出禁止](#reference-engineering-practice-十沟通与输出禁止)
+      - [十一、协作与版本控制禁止](#reference-engineering-practice-十一协作与版本控制禁止)
+      - [十二、性能与设计哲学禁止](#reference-engineering-practice-十二性能与设计哲学禁止)
+      - [十三、可直接合并进你的「全局禁止池」精简版](#reference-engineering-practice-十三可直接合并进你的全局禁止池精简版)
+      - [建议删除或不要加入禁止池的内容](#reference-engineering-practice-建议删除或不要加入禁止池的内容)
+      - [一、输出完整性类](#reference-engineering-practice-一输出完整性类)
+      - [二、逻辑正确性类](#reference-engineering-practice-二逻辑正确性类)
+      - [三、性能类](#reference-engineering-practice-三性能类)
+      - [四、安全类](#reference-engineering-practice-四安全类)
+      - [五、代码质量类](#reference-engineering-practice-五代码质量类)
+      - [六、依赖与环境类](#reference-engineering-practice-六依赖与环境类)
+      - [七、测试与验证类](#reference-engineering-practice-七测试与验证类)
+      - [八、数据与状态类](#reference-engineering-practice-八数据与状态类)
+      - [九、用户体验类](#reference-engineering-practice-九用户体验类)
+      - [十、工程交付类](#reference-engineering-practice-十工程交付类)
+      - [十一、AI 编码行为类](#reference-engineering-practice-十一ai-编码行为类)
+      - [十二、推荐你整理成最终版“全局禁止池”](#reference-engineering-practice-十二推荐你整理成最终版全局禁止池)
+    - [3. 常见坑汇总](#reference-engineering-practice-3-常见坑汇总)
+        - [先查资料，再写代码](#reference-engineering-practice-先查资料再写代码)
+        - [为什么要用虚拟环境？](#reference-engineering-practice-为什么要用虚拟环境)
+        - [创建和使用 .venv](#reference-engineering-practice-创建和使用-venv)
+        - [常见问题](#reference-engineering-practice-常见问题)
+        - [一键重置环境](#reference-engineering-practice-一键重置环境)
+        - [常见问题](#reference-engineering-practice-常见问题-2)
+        - [常用命令](#reference-engineering-practice-常用命令)
+        - [终端代理配置](#reference-engineering-practice-终端代理配置)
+        - [常用 Git 命令](#reference-engineering-practice-常用-git-命令)
+      - [🔥 终极解决方案](#reference-engineering-practice-终极解决方案)
+      - [📝 贡献](#reference-engineering-practice-贡献)
   - [5. 底层程序逻辑设计与工程优化项](#reference-engineering-practice-5-底层程序逻辑设计与工程优化项)
 - [2. 技术栈](#reference-technology-stack)
   - [核心摘要](#reference-technology-stack-核心摘要)
@@ -122,31 +231,31 @@
   - [一、什么是技术栈](#reference-technology-stack-一什么是技术栈)
   - [二、技术栈通常包含哪些部分](#reference-technology-stack-二技术栈通常包含哪些部分)
   - [1. 前端技术栈](#reference-technology-stack-1-前端技术栈)
-  - [基础语言](#reference-technology-stack-基础语言)
-  - [前端框架](#reference-technology-stack-前端框架)
-  - [UI 框架和组件库](#reference-technology-stack-ui-框架和组件库)
-  - [构建工具](#reference-technology-stack-构建工具)
-  - [状态管理](#reference-technology-stack-状态管理)
-  - [前端路由](#reference-technology-stack-前端路由)
-  - [前端请求工具](#reference-technology-stack-前端请求工具)
-  - [前端测试](#reference-technology-stack-前端测试)
-  - [前端常见组合](#reference-technology-stack-前端常见组合)
+    - [基础语言](#reference-technology-stack-基础语言)
+    - [前端框架](#reference-technology-stack-前端框架)
+    - [UI 框架和组件库](#reference-technology-stack-ui-框架和组件库)
+    - [构建工具](#reference-technology-stack-构建工具)
+    - [状态管理](#reference-technology-stack-状态管理)
+    - [前端路由](#reference-technology-stack-前端路由)
+    - [前端请求工具](#reference-technology-stack-前端请求工具)
+    - [前端测试](#reference-technology-stack-前端测试)
+    - [前端常见组合](#reference-technology-stack-前端常见组合)
   - [2. 后端技术栈](#reference-technology-stack-2-后端技术栈)
-  - [常见后端语言](#reference-technology-stack-常见后端语言)
-  - [Java 后端](#reference-technology-stack-java-后端)
-  - [Python 后端](#reference-technology-stack-python-后端)
-  - [Node.js 后端](#reference-technology-stack-nodejs-后端)
-  - [Go 后端](#reference-technology-stack-go-后端)
-  - [PHP 后端](#reference-technology-stack-php-后端)
-  - [C# 后端](#reference-technology-stack-c-后端)
+    - [常见后端语言](#reference-technology-stack-常见后端语言)
+    - [Java 后端](#reference-technology-stack-java-后端)
+    - [Python 后端](#reference-technology-stack-python-后端)
+    - [Node.js 后端](#reference-technology-stack-nodejs-后端)
+    - [Go 后端](#reference-technology-stack-go-后端)
+    - [PHP 后端](#reference-technology-stack-php-后端)
+    - [C# 后端](#reference-technology-stack-c-后端)
   - [3. 数据库技术栈](#reference-technology-stack-3-数据库技术栈)
   - [关系型数据库](#reference-technology-stack-关系型数据库)
   - [非关系型数据库](#reference-technology-stack-非关系型数据库)
-  - [文档数据库](#reference-technology-stack-文档数据库)
-  - [键值数据库](#reference-technology-stack-键值数据库)
-  - [搜索引擎](#reference-technology-stack-搜索引擎)
-  - [图数据库](#reference-technology-stack-图数据库)
-  - [时序数据库](#reference-technology-stack-时序数据库)
+    - [文档数据库](#reference-technology-stack-文档数据库)
+    - [键值数据库](#reference-technology-stack-键值数据库)
+    - [搜索引擎](#reference-technology-stack-搜索引擎)
+    - [图数据库](#reference-technology-stack-图数据库)
+    - [时序数据库](#reference-technology-stack-时序数据库)
   - [三、移动端技术栈](#reference-technology-stack-三移动端技术栈)
   - [iOS 原生开发](#reference-technology-stack-ios-原生开发)
   - [Android 原生开发](#reference-technology-stack-android-原生开发)
@@ -226,8 +335,8 @@
   - [如果你想做网页前端](#reference-technology-stack-如果你想做网页前端)
   - [如果你想做后端](#reference-technology-stack-如果你想做后端)
   - [如果你想做全栈](#reference-technology-stack-如果你想做全栈)
-  - [路线一：JavaScript / TypeScript 全栈](#reference-technology-stack-路线一javascript-typescript-全栈)
-  - [路线二：Java 企业全栈](#reference-technology-stack-路线二java-企业全栈)
+    - [路线一：JavaScript / TypeScript 全栈](#reference-technology-stack-路线一javascript-typescript-全栈)
+    - [路线二：Java 企业全栈](#reference-technology-stack-路线二java-企业全栈)
   - [如果你想做 AI](#reference-technology-stack-如果你想做-ai)
   - [十六、技术栈的层级结构](#reference-technology-stack-十六技术栈的层级结构)
   - [十七、技术栈示例总表](#reference-technology-stack-十七技术栈示例总表)
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
index 0588efb..a4686e7 100644
--- a/scripts/AGENTS.md
+++ b/scripts/AGENTS.md
@@ -6,6 +6,7 @@
 
 - 脚本默认从仓库根目录运行，路径解析必须稳定。
 - 新增检查脚本时，同步更新 `scripts/README.md`、`Makefile`、CI 和根目录 `AGENTS.md` 的命令清单。
+- 修改 docs 线性 README 的主章节或锚点后，优先运行 `python3 scripts/sync-doc-toc.py`，再运行 `make test`。
 - 检查失败输出应包含文件路径、行号或可定位的错误信息。
 - 跳过目录必须明确，至少跳过 `.git`、`.history`、`node_modules` 和外部源码快照。
 
diff --git a/scripts/README.md b/scripts/README.md
index e8542c4..8adb545 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -10,3 +10,4 @@
 - `check-directory-docs.py`：仓库自有目录 `README.md` / `AGENTS.md` 覆盖检查脚本。
 - `check-metadata.py`：`metadata/taxonomy.yml` 与 `metadata/redirects.yml` 路径和锚点检查脚本。
 - `check-ai-citation.py`：`llms.txt`、`assets/ai-citation/llms-full.txt` 与 AI 引用语料路径和锚点检查脚本。
+- `sync-doc-toc.py`：根据 `metadata/taxonomy.yml` 和文档锚点重建 docs 线性 README 的完整细粒度目录。
diff --git a/scripts/check-ai-citation.py b/scripts/check-ai-citation.py
index 0f72024..e3d9bfb 100644
--- a/scripts/check-ai-citation.py
+++ b/scripts/check-ai-citation.py
@@ -10,6 +10,7 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[1]
+TAXONOMY = ROOT / "metadata/taxonomy.yml"
 AI_ENTRY_FILES = [
     Path("llms.txt"),
     Path("assets/ai-citation/llms-full.txt"),
@@ -27,6 +28,31 @@ MARKDOWN_LINK_PATTERN = re.compile(r"!??\[[^\]]*\]\(([^)]+)\)")
 EXTERNAL_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:")
 
 
+def strip_quotes(value: str) -> str:
+    return value.strip().strip("\"'")
+
+
+def taxonomy_document_paths() -> list[str]:
+    paths: list[str] = []
+    in_documents = False
+
+    for line in TAXONOMY.read_text(encoding="utf-8").splitlines():
+        if line == "documents:":
+            in_documents = True
+            continue
+        if in_documents and line and not line.startswith(" "):
+            break
+        if not in_documents:
+            continue
+
+        stripped = line.strip()
+        if stripped.startswith("- path:"):
+            _, value = stripped.split(":", 1)
+            paths.append(strip_quotes(value))
+
+    return paths
+
+
 def github_slug(title: str) -> str:
     title = re.sub(r"<[^>]+>", "", title.strip().lower())
     title = re.sub(r"[`*_~]", "", title)
@@ -157,6 +183,15 @@ def main() -> int:
             if error:
                 errors.append(error)
 
+    llms_full = ROOT / "assets/ai-citation/llms-full.txt"
+    if not llms_full.exists():
+        errors.append("assets/ai-citation/llms-full.txt: missing full AI citation context")
+    else:
+        llms_full_text = llms_full.read_text(encoding="utf-8", errors="ignore")
+        for target in taxonomy_document_paths():
+            if target not in llms_full_text:
+                errors.append(f"assets/ai-citation/llms-full.txt: missing taxonomy document coverage: {target}")
+
     if errors:
         print("AI_CITATION_ERRORS")
         for error in errors:
diff --git a/scripts/check-doc-structure.py b/scripts/check-doc-structure.py
index 2f5e976..1d1f60b 100644
--- a/scripts/check-doc-structure.py
+++ b/scripts/check-doc-structure.py
@@ -9,42 +9,77 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[1]
-DOC_READMES: dict[Path, list[str]] = {
-    Path("docs/getting-started/README.md"): [
-        "vibe-coding-experience",
-        "learning-map",
-        "network-environment",
-        "cli-setup",
-        "development-environment",
-    ],
-    Path("docs/concepts/README.md"): [
-        "concept-problem-solving",
-        "concept-glue-coding",
-        "concept-system-building",
-        "concept-development-paradigms",
-        "concept-language-layers",
-        "concept-recursive-self-optimizing-system",
-    ],
-    Path("docs/philosophy/README.md"): [
-        "philosophy-thinking-models",
-        "philosophy-compositional-description-model",
-        "philosophy-programming-dao",
-        "philosophy-methodology-toolbox",
-    ],
-    Path("docs/references/README.md"): [
-        "reference-engineering-practice",
-        "reference-technology-stack",
-    ],
-    Path("docs/research/README.md"): [
-        "research-harness-engineering",
-    ],
-}
+TAXONOMY = ROOT / "metadata/taxonomy.yml"
 SKIP_PARTS = {".git", ".history", "node_modules"}
 SKIP_PREFIXES = [
     Path(".github/wiki"),
     Path("tools/external"),
 ]
 ANCHOR_PATTERN = re.compile(r"<a\s+id=[\"']([^\"']+)[\"']")
+SUMMARY_LINE = "<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>"
+
+
+def strip_quotes(value: str) -> str:
+    return value.strip().strip("\"'")
+
+
+def taxonomy_sections() -> dict[str, dict[str, str]]:
+    sections: dict[str, dict[str, str]] = {}
+    current: str | None = None
+    in_sections = False
+
+    for line in TAXONOMY.read_text(encoding="utf-8").splitlines():
+        if line == "sections:":
+            in_sections = True
+            continue
+        if in_sections and line and not line.startswith(" "):
+            break
+        if not in_sections:
+            continue
+
+        section_match = re.match(r"^  ([A-Za-z0-9_-]+):\s*$", line)
+        if section_match:
+            current = section_match.group(1)
+            sections[current] = {}
+            continue
+        field_match = re.match(r"^    (path|entry|agent_guide):\s*(.+?)\s*$", line)
+        if current and field_match:
+            sections[current][field_match.group(1)] = strip_quotes(field_match.group(2))
+
+    return sections
+
+
+def taxonomy_document_paths() -> list[str]:
+    paths: list[str] = []
+    in_documents = False
+
+    for line in TAXONOMY.read_text(encoding="utf-8").splitlines():
+        if line == "documents:":
+            in_documents = True
+            continue
+        if in_documents and line and not line.startswith(" "):
+            break
+        if not in_documents:
+            continue
+
+        stripped = line.strip()
+        if stripped.startswith("- path:"):
+            _, value = stripped.split(":", 1)
+            paths.append(strip_quotes(value))
+
+    return paths
+
+
+def doc_readmes_from_taxonomy() -> dict[Path, list[str]]:
+    readmes: dict[Path, list[str]] = {}
+
+    for target in taxonomy_document_paths():
+        path_part, _, anchor = target.partition("#")
+        if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"):
+            continue
+        readmes.setdefault(Path(path_part), []).append(anchor)
+
+    return readmes
 
 
 def strip_fenced_code(text: str) -> str:
@@ -118,12 +153,72 @@ def check_linear_readme(path: Path, expected_anchors: list[str]) -> list[str]:
             errors.append(f"{rel}:{line}: main anchor '{anchor}' is out of expected section order")
         previous_line = line
 
-    toc_boundary = min((anchor_lines.get(anchor, len(text.splitlines()) + 1) for anchor in expected_anchors), default=0)
-    toc_text = "\n".join(text.splitlines()[:toc_boundary])
+    toc_text = active_toc_text(text)
+    if not toc_text:
+        errors.append(f"{rel}: missing active collapsible fine-grained TOC block")
+
     for anchor in expected_anchors:
         if f"#{anchor}" not in toc_text:
             errors.append(f"{rel}: top navigation or fine-grained TOC does not link to '#{anchor}'")
 
+    required_prefixes = tuple(f"{anchor}-" for anchor in expected_anchors)
+    for anchor in anchor_lines:
+        if anchor in expected_anchors or anchor.startswith(required_prefixes):
+            if f"#{anchor}" not in toc_text:
+                errors.append(f"{rel}: fine-grained TOC does not link to manual anchor '#{anchor}'")
+
+    return errors
+
+
+def active_toc_text(text: str) -> str:
+    in_fence = False
+    fence_marker = ""
+    collecting = False
+    collected: list[str] = []
+
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith(("```", "~~~")):
+            marker = stripped[:3]
+            if not in_fence:
+                in_fence = True
+                fence_marker = marker
+            elif marker == fence_marker:
+                in_fence = False
+                fence_marker = ""
+
+        if in_fence:
+            continue
+        if SUMMARY_LINE in line:
+            collecting = True
+        if collecting:
+            collected.append(line)
+        if collecting and line.strip() == "</details>":
+            break
+
+    return "\n".join(collected)
+
+
+def check_docs_index() -> list[str]:
+    errors: list[str] = []
+    docs_index = ROOT / "docs/README.md"
+    rel = docs_index.relative_to(ROOT)
+
+    if not docs_index.exists():
+        return [f"{rel}: missing docs index"]
+
+    text = docs_index.read_text(encoding="utf-8", errors="ignore")
+    for name, fields in taxonomy_sections().items():
+        for field in ("path", "entry", "agent_guide"):
+            value = fields.get(field)
+            if not value:
+                errors.append(f"metadata/taxonomy.yml: section '{name}' missing '{field}'")
+                continue
+            docs_relative = value.removeprefix("docs/")
+            candidates = {value, f"./{docs_relative}", docs_relative}
+            if not any(candidate in text for candidate in candidates):
+                errors.append(f"{rel}: missing taxonomy {field} reference for '{name}': {value}")
+
     return errors
 
 
@@ -137,13 +232,19 @@ def main() -> int:
         checked_files += 1
         errors.extend(duplicate_manual_anchors(markdown_file))
 
-    for rel_path, expected_anchors in DOC_READMES.items():
+    doc_readmes = doc_readmes_from_taxonomy()
+    if not doc_readmes:
+        errors.append("metadata/taxonomy.yml: no docs README anchors found under documents")
+
+    for rel_path, expected_anchors in doc_readmes.items():
         path = ROOT / rel_path
         if not path.exists():
             errors.append(f"{rel_path}: missing docs README")
             continue
         errors.extend(check_linear_readme(path, expected_anchors))
 
+    errors.extend(check_docs_index())
+
     if errors:
         print("DOC_STRUCTURE_ERRORS")
         for error in errors:
diff --git a/scripts/sync-doc-toc.py b/scripts/sync-doc-toc.py
new file mode 100644
index 0000000..2d45b68
--- /dev/null
+++ b/scripts/sync-doc-toc.py
@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Regenerate collapsible fine-grained TOC blocks in docs linear README files."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+TAXONOMY = ROOT / "metadata/taxonomy.yml"
+SUMMARY_LINE = "<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>"
+ANCHOR_PATTERN = re.compile(r"<a\s+id=[\"']([^\"']+)[\"']")
+HEADING_PATTERN = re.compile(r"^(#{2,6})\s+(.+?)\s*#*\s*$")
+
+
+def strip_quotes(value: str) -> str:
+    return value.strip().strip("\"'")
+
+
+def taxonomy_document_paths() -> list[str]:
+    paths: list[str] = []
+    in_documents = False
+
+    for line in TAXONOMY.read_text(encoding="utf-8").splitlines():
+        if line == "documents:":
+            in_documents = True
+            continue
+        if in_documents and line and not line.startswith(" "):
+            break
+        if not in_documents:
+            continue
+
+        stripped = line.strip()
+        if stripped.startswith("- path:"):
+            _, value = stripped.split(":", 1)
+            paths.append(strip_quotes(value))
+
+    return paths
+
+
+def doc_readmes_from_taxonomy() -> dict[Path, list[str]]:
+    readmes: dict[Path, list[str]] = {}
+
+    for target in taxonomy_document_paths():
+        path_part, _, anchor = target.partition("#")
+        if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"):
+            continue
+        readmes.setdefault(Path(path_part), []).append(anchor)
+
+    return readmes
+
+
+def heading_after(lines: list[str], start: int) -> tuple[int, str] | None:
+    for line in lines[start + 1 : start + 8]:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        match = HEADING_PATTERN.match(stripped)
+        if not match:
+            return None
+        return len(match.group(1)), match.group(2).strip()
+    return None
+
+
+def title_from_anchor(anchor: str, main_anchors: list[str]) -> str:
+    for main_anchor in sorted(main_anchors, key=len, reverse=True):
+        if anchor == main_anchor:
+            return main_anchor
+        prefix = f"{main_anchor}-"
+        if anchor.startswith(prefix):
+            return anchor.removeprefix(prefix).replace("-", " ")
+    return anchor.replace("-", " ")
+
+
+def collect_toc_entries(text: str, main_anchors: list[str]) -> list[tuple[int, str, str]]:
+    lines = text.splitlines()
+    required_prefixes = tuple(f"{anchor}-" for anchor in main_anchors)
+    entries: list[tuple[int, str, str]] = []
+    seen: set[str] = set()
+
+    for idx, line in enumerate(lines):
+        for anchor in ANCHOR_PATTERN.findall(line):
+            if anchor in seen:
+                continue
+            if anchor not in main_anchors and not anchor.startswith(required_prefixes):
+                continue
+            seen.add(anchor)
+
+            heading = heading_after(lines, idx)
+            if heading:
+                level, title = heading
+            else:
+                level, title = 3, title_from_anchor(anchor, main_anchors)
+            entries.append((level, title, anchor))
+
+    return entries
+
+
+def render_toc(entries: list[tuple[int, str, str]]) -> str:
+    rendered = [
+        "<details>",
+        SUMMARY_LINE,
+        "",
+        "### 细粒度目录",
+        "",
+    ]
+
+    for level, title, anchor in entries:
+        indent = "  " * max(level - 2, 0)
+        rendered.append(f"{indent}- [{title}](#{anchor})")
+
+    rendered.extend(["", "</details>"])
+    return "\n".join(rendered)
+
+
+def active_toc_bounds(text: str) -> tuple[int, int] | None:
+    in_fence = False
+    fence_marker = ""
+    offset = 0
+    details_start: int | None = None
+
+    for line in text.splitlines(keepends=True):
+        stripped = line.lstrip()
+        if stripped.startswith(("```", "~~~")):
+            marker = stripped[:3]
+            if not in_fence:
+                in_fence = True
+                fence_marker = marker
+            elif marker == fence_marker:
+                in_fence = False
+                fence_marker = ""
+
+        if not in_fence:
+            if "<details>" in line:
+                details_start = offset + line.index("<details>")
+            if SUMMARY_LINE in line and details_start is not None:
+                end = text.find("</details>", offset)
+                if end == -1:
+                    return None
+                return details_start, end + len("</details>")
+
+        offset += len(line)
+
+    return None
+
+
+def replace_toc_block(text: str, toc: str) -> tuple[str, bool]:
+    bounds = active_toc_bounds(text)
+    if bounds is None:
+        return text, False
+
+    details_start, details_end = bounds
+    return f"{text[:details_start]}{toc}{text[details_end:]}", True
+
+
+def main() -> int:
+    changed: list[str] = []
+    errors: list[str] = []
+
+    for rel_path, main_anchors in doc_readmes_from_taxonomy().items():
+        path = ROOT / rel_path
+        if not path.exists():
+            errors.append(f"{rel_path}: missing docs README")
+            continue
+
+        text = path.read_text(encoding="utf-8")
+        entries = collect_toc_entries(text, main_anchors)
+        if not entries:
+            errors.append(f"{rel_path}: no TOC entries generated")
+            continue
+
+        new_text, replaced = replace_toc_block(text, render_toc(entries))
+        if not replaced:
+            errors.append(f"{rel_path}: missing standard collapsible TOC block")
+            continue
+
+        if new_text != text:
+            path.write_text(new_text, encoding="utf-8")
+            changed.append(str(rel_path))
+
+    if errors:
+        print("SYNC_DOC_TOC_ERRORS")
+        for error in errors:
+            print(error)
+        return 1
+
+    for rel_path in changed:
+        print(f"updated {rel_path}")
+    print(f"OK synced docs TOC blocks: {len(changed)} changed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())