docs: a citation that names a section must land in the chapter that has it

The self-review found five citations, in two languages, reading
`See *One package, one version* in [04 — mcpp.toml](04-mcpp-toml.md)`. The
section moved to chapter 23 with the `[xlings]` split. Rule 3 could not see it:
the path resolves, and the chapter is simply the wrong one. The earlier §-number
sweep could not see it either, because this citation names its target by TITLE.

All five are repointed, and rule 12 checks the shape: a citation of the form
`See *X* in [NN](NN-….md)` -- and its 简体中文 form -- must land in a chapter
whose text contains X. Falsified before committing.

Two more from the same review pass: chapter 20 appeared in no scenario path,
though "which compiler builds this" is a question every reader eventually has,
and it joins scenario 1; and the limits section of chapter 30 was left
mid-chapter by the split that appended a section after it.

The duplicate-sentence scan across 27 chapters found two hits and neither is a
duplicated explanation -- one is a shared cross-reference, which is R1 working,
and the other is one sentence two chapters reached independently.

Author: speak-agent

.github/tools/check_docs_structure.sh

@@ -15,6 +15,7 @@
 #   9. every relative link in docs/ and examples/ resolves
 #  10. a translation carries the same tables and code blocks
 #  11. every chapter states its reader, its question and its exclusions
+#  12. a citation naming a section lands in the chapter that contains it
 #
 # What it deliberately does NOT check: whether a chapter documents what is
 # implemented, whether an assertion's strength matches its evidence, or whether
@@ -219,6 +220,32 @@ for f in docs/[0-9]*.md docs/zh/[0-9]*.md; do
     || bad "$f: the opening states no exclusions"
 done
 
+# ── 12. a citation that names a section lands in the chapter that has it ─
+#
+# `See *One package, one version* in [04](04-mcpp-toml.md)` survived a split
+# that moved the section to chapter 23, in five places and two languages. Rule 3
+# could not see it -- the path resolved; it was the wrong chapter. A citation
+# that names a section by TITLE is checkable against that chapter's headings.
+python3 - <<'PYCITE' || fail=1
+import re, pathlib, sys
+EN = re.compile(r"See \*([^*]{3,60})\* in \[\d{2}[^\]]*\]\((\d{2}-[a-z0-9-]+)\.md\)")
+ZH = re.compile(r"见\s*\[\d{2}[^\]]*\]\((\d{2}-[a-z0-9-]+)\.md\)\s*的\*([^*]{2,40})\*")
+bad = 0
+for f in list(pathlib.Path("docs").glob("[0-9]*.md")) + list(pathlib.Path("docs/zh").glob("[0-9]*.md")):
+    text = f.read_text(errors="ignore")
+    for m in EN.finditer(text):
+        title, chap = m.group(1), m.group(2)
+        t = (f.parent / f"{chap}.md")
+        if not t.exists() or title.lower() not in t.read_text(errors="ignore").lower():
+            print(f"FAIL: {f}: cites *{title}* in {chap}, which does not contain it"); bad += 1
+    for m in ZH.finditer(text):
+        chap, title = m.group(1), m.group(2)
+        t = (f.parent / f"{chap}.md")
+        if not t.exists() or title not in t.read_text(errors="ignore"):
+            print(f"FAIL: {f}: cites *{title}* in {chap}, which does not contain it"); bad += 1
+sys.exit(1 if bad else 0)
+PYCITE
+
 if [[ "$fail" -eq 0 ]]; then
   echo "OK: docs structure checks pass"
 fi

docs/02-scenarios.md

@@ -45,7 +45,9 @@ command produces a binary that carries what it needs.
 3. [05 — Dependencies and Resolution](05-dependencies.md) — `[dependencies]`,
    the lock file.
 4. [08 — Testing](08-testing.md) — `tests/**/*.cpp`.
-5. [10 — Packaging an Application](10-pack-and-release.md) — `mcpp pack`.
+5. [20 — Toolchain Management](20-toolchains.md) — when the compiler's version
+   matters, or the project must pin one.
+6. [10 — Packaging an Application](10-pack-and-release.md) — `mcpp pack`.
 
 **Run.** [`examples/01-hello`](../examples/01-hello/), then
 [`02-with-deps`](../examples/02-with-deps/), then

docs/23-the-project-environment.md

@@ -119,7 +119,7 @@ Where a project and a dependency name **one package**, one version of it is
 installed: identity is `(namespace, name)` and the version is a constraint on
 it. The declaration nearer the artifact wins and the override is reported;
 a pin that fails a requirement the other side stated is refused naming both.
-See *One package, one version* in [04 — mcpp.toml](04-mcpp-toml.md).
+See *One package, one version* in [23 — The Project Environment](23-the-project-environment.md).
 
 ## 4. Reading an environment, never creating one
 

docs/30-build-mcpp.md

@@ -355,7 +355,7 @@ could not state a floor and every project repeated its rule's package list.
 version this build actually installed rather than the one the local manifest
 wrote. One package means one version: where a project and a rule both name it,
 the declaration nearer the artifact wins and both sides are told the same
-answer. See *One package, one version* in [04 — mcpp.toml](04-mcpp-toml.md).
+answer. See *One package, one version* in [23 — The Project Environment](23-the-project-environment.md).
 
 **`[feature-xlings.<f>]` is answered too, while `<f>` is active**
 *(2026.9.6.2+)*. That table has provisioned its packages since it existed --

docs/31-authoring-a-rule-package.md

@@ -169,7 +169,7 @@ neither.
 
 A bare version is a **choice** a project may override; `>=` is a
 **requirement** a project may not go below. See *One package, one version* in
-[04 — mcpp.toml](04-mcpp-toml.md).
+[23 — The Project Environment](23-the-project-environment.md).
 
 ## Generating an island's boundary
 

docs/42-heterogeneous-builds.md

@@ -303,7 +303,7 @@ the machines it will run on:
 The nearer declaration wins, one version is installed, and mcpp says which. A
 pin that does not satisfy the rule's floor is refused naming both sides rather
 than installed alongside it. See *One package, one version* in
-[04 — mcpp.toml](04-mcpp-toml.md) for the full rule;
+[23 — The Project Environment](23-the-project-environment.md) for the full rule;
 `examples/09-heterogeneous/multi-backend` is the one example in this repository
 that takes the override path, and every other one writes only the edge.
 

docs/zh/02-scenarios.md

@@ -41,7 +41,9 @@
 2. [01 —— 快速开始](01-getting-started.md) —— 把程序跑起来。
 3. [05 —— 依赖与解析](05-dependencies.md) —— `[dependencies]`、锁文件。
 4. [08 —— 测试](08-testing.md) —— `tests/**/*.cpp`。
-5. [10 —— 发布打包](10-pack-and-release.md) —— `mcpp pack`。
+5. [20 —— 工具链管理](20-toolchains.md) —— 当编译器版本要紧,或者工程必须钉住
+   一个的时候。
+6. [10 —— 发布打包](10-pack-and-release.md) —— `mcpp pack`。
 
 **跑。** [`examples/01-hello`](../../examples/01-hello/),然后
 [`02-with-deps`](../../examples/02-with-deps/),再

docs/zh/23-the-project-environment.md

@@ -96,7 +96,7 @@ SubOS 里。前置让被声明的环境成为默认答案;其余的仍在它后
 
 工程与依赖命名**同一个包**时,只装它的一个版本:身份是 `(namespace, name)`,版本是这个
 包上的约束。离产物更近的声明赢,并且覆盖会被报出来;不满足对方所陈述之要求的钉会被拒绝
-并点出两侧。见 [04 — mcpp.toml](04-mcpp-toml.md) 的「一个包一个版本」。
+并点出两侧。见 [23 — The Project Environment](23-the-project-environment.md) 的「一个包一个版本」。
 
 ## 4. 只读取环境,从不创建环境
 

docs/zh/30-build-mcpp.md

@@ -305,7 +305,7 @@ store 内部结构 —— 与 `dep_dir` 存在的理由相同。
 
 **依赖声明的包同样被作答**(2026.9.6.6+),而且答的是这次构建**真正装上**的版本,不是
 本地 manifest 写下的那个。一个包只有一个版本:工程与规则都命名它时,离产物更近的声明赢,
-而两侧被告知同一个答案。见 [04 — mcpp.toml](04-mcpp-toml.md) 的「一个包一个版本」。
+而两侧被告知同一个答案。见 [23 — The Project Environment](23-the-project-environment.md) 的「一个包一个版本」。
 
 **`[feature-xlings.<f>]` 在 `<f>` 生效时同样被作答**(2026.9.6.2+)。这张表从诞生
 起就参与供给 —— 在那里写下一个包,它就会被下载并安装 —— 但构建程序的环境只由

docs/zh/31-authoring-a-rule-package.md

@@ -154,7 +154,7 @@ device link 在引擎侧的全部内容:N 个 `artifact` action,其输出不进
 都不开。
 
 裸版本是项目可以覆盖的**选择**;`>=` 是项目不得低于的**要求**。见
-[04 —— mcpp.toml](04-mcpp-toml.md) 的*一个包,一个版本*。
+[23 —— 项目环境](23-the-project-environment.md) 的*一个包一个版本*。
 
 ## 生成岛的边界