diff --git a/docs/git-branching.md b/docs/git-branching.md
index 563511c..3d6f198 100644
--- a/docs/git-branching.md
+++ b/docs/git-branching.md
@@ -130,6 +130,45 @@ main ──────────────── E ────────
 
 ---
 
+### 7. 开发者文档的发布归属（以 rel 分支的形态为准）
+
+**规则：面向使用者的开发者文档，先在对应的 `release/vX.Y.x` 上修正成「这一版的实际行为」，
+再 cherry-pick 合入 `main`。**（文档属 §二.3 所列的发布分支允许事项之一）
+
+为什么不能直接改 main：
+
+- `main` 的语义是**下一个未发布版本**（§二.1）。在那儿写的文档要么描述尚未发布的行为，
+  要么与当前 rel 的实际行为**相反**，而文档的读者（包括模型自身）会把它当事实。
+- `assets/docs/**` 会**随发行包分发并在 WebUI 里被阅读**——它服务的是“这一版”，不是“下一版”。
+- 版本号、工具名、机制的有无都是**随版变动的**：同一个文件在两个分支上就应该是两种口径。
+
+做法：
+
+```bash
+git switch release/v1.2.x
+# 按这一版口径修改：版本号、当前工具名（hmapdev）、已移除机制不再写成现行
+# ... 编辑 assets/docs/**、README{,_EN}.md、docs/zh/** ...
+git commit -m "docs: 按 v1.2.x 口径修正 …"
+git switch main && git cherry-pick <sha>   # 遵守 §三：只 pick，不 merge
+```
+
+`main` 上若需要描述“下一版才有的行为”，必须显式标注（如「（下一版）」或附版本号），
+不得让读者以为它已发布。
+
+**反例（本仓真实踩过，均为“文档当成事实后反向误导”）**：
+
+| 现象 | 后果 |
+|---|---|
+| 人格卡写死 `v0.9.0（C ABI v2）` | 内核接口/日志报 1.2.0，agent 却向用户自述旧版本（且该机制 v1.0.0 已删除） |
+| 架构文档在 1.2.0 后仍把“描述式索引 + 引用计数 GC”写成现行机制 | 读者按已删除的设计理解现行行为 |
+| README 停在 v1.1.1 并描述已被删除的机制 | 同上 |
+
+配套硬约束：**任何“模型或用户会当作事实”的文本，都不得写死版本号**——
+要么用 `meta.Version` 插值，要么要求读运行时快照，并用测试钉住
+（如 `TestDefaultPersonaPromptHasNoVersionLiterals`）。
+
+---
+
 ## 三、当前分支对齐（2026-09-12 更新）
 
 ### 主仓（TrueAgent）