docs: limits go last, the emit/parse mismatch is recorded, and links are checked

Appending [hooks] to 21 had put it after that chapter's 'Current limitations',
which is the one section that has to be last. Both languages reordered.

`mcpp emit xpkg` produces a descriptor that `mcpp xpkg parse` rejects for a
package that keeps its own mcpp.toml: the emitted mcpp segment carries
`manifest = "mcpp.toml"` and no `sources` list, and the validator requires
one. Isolated by adding the list by hand, which makes it validate. Recorded as a
current limitation in 21 rather than fixed here.

Rule 9: every relative Markdown link in docs/ and examples/ resolves. Rule 3
catches a chapter path named from anywhere including source comments; this
catches a link whose target is not there. A chapter moved in this batch would
satisfy one and break the other.

Author: speak-agent

.github/tools/check_docs_structure.sh

@@ -12,6 +12,7 @@
 #   6. no emoji under docs/ or in a top-level README
 #   7. the generated design-record index is current
 #   8. a new design record declares its subject and status
+#   9. every relative link in docs/ and examples/ resolves
 #
 # What it deliberately does NOT check: whether a chapter documents what is
 # implemented, whether an assertion's strength matches its evidence, or whether
@@ -139,6 +140,26 @@ for f in .agents/docs/[0-9]*.md; do
     || bad "$f: front matter declares no valid \`status\` (active | landed | superseded | abandoned)"
 done
 
+# ── 9. every relative link in docs/ and examples/ resolves ───────────────
+#
+# Rule 3 catches `docs/NN-*.md` named anywhere, including from source comments.
+# This is the other half: a Markdown link in a document that points at a file
+# which is not there. Both halves are needed -- a chapter moved in this batch
+# would satisfy one and break the other.
+python3 - <<'PYCHECK' || fail=1
+import re, pathlib, sys
+bad = 0
+for f in list(pathlib.Path("docs").rglob("*.md")) + list(pathlib.Path("examples").rglob("*.md")):
+    for m in re.finditer(r"\]\(([^)#]+?)(?:#[^)]*)?\)", f.read_text(errors="ignore")):
+        t = m.group(1)
+        if t.startswith(("http", "mailto:")):
+            continue
+        if not (f.parent / t).exists():
+            print(f"FAIL: {f}: link to `{t}` does not resolve")
+            bad += 1
+sys.exit(1 if bad else 0)
+PYCHECK
+
 if [[ "$fail" -eq 0 ]]; then
   echo "OK: docs structure checks pass"
 fi

docs/21-commands-by-scenario.md

@@ -195,21 +195,6 @@ included. `mcpp self config --mirror CN|GLOBAL` selects the download mirror;
 mcpp and xlings hold this setting separately, so selecting it for one does not
 select it for the other.
 
-## Current limitations
-
-- `mcpp why --format json` is defined for the `toolchain` topic only. The other
-  topics report `'<topic>' has no machine-readable shape yet` and exit non-zero.
-- `mcpp search` matches a substring; there is no field selector, and no way to
-  restrict a search to one namespace.
-- `mcpp clean --stale` reads `target/.build_cache`, which holds a bounded number
-  of recent entries. A project built across more (target, profile) pairs than it
-  holds loses its oldest entries, and a directory whose entry has been evicted
-  is then treated as unrecorded — kept while it is newer than `--older-than`,
-  removed after that.
-- `mcpp cache gc --older-than 0` is rejected with `bad --older-than value '0'
-  (expected <N>{s,m,h,d})`, while `mcpp clean --stale --older-than 0` accepts it.
-  The two options share a parser but not this case.
-
 ## `[hooks]` — Project Build Lifecycle Commands (experimental)
 
 > **Experimental.** A hook cannot currently decide whether a build succeeded.
@@ -370,3 +355,30 @@ A different sound for a successful or failed build. `side_effect = false` is
 written out rather than left to the default: it is the value this manifest
 wants on its own terms — a missing audio device should never fail a build — so
 it will still say so once the key has more than one accepted value.
+
+## Current limitations
+
+- `mcpp why --format json` is defined for the `toolchain` topic only. The other
+  topics report `'<topic>' has no machine-readable shape yet` and exit non-zero.
+- `mcpp search` matches a substring; there is no field selector, and no way to
+  restrict a search to one namespace.
+- `mcpp clean --stale` reads `target/.build_cache`, which holds a bounded number
+  of recent entries. A project built across more (target, profile) pairs than it
+  holds loses its oldest entries, and a directory whose entry has been evicted
+  is then treated as unrecorded — kept while it is newer than `--older-than`,
+  removed after that.
+- `mcpp cache gc --older-than 0` is rejected with `bad --older-than value '0'
+  (expected <N>{s,m,h,d})`, while `mcpp clean --stale --older-than 0` accepts it.
+  The two options share a parser but not this case.
+
+`mcpp emit xpkg` produces a descriptor that `mcpp xpkg parse` rejects for a
+package that keeps its own `mcpp.toml`. The emitted `mcpp` segment carries
+`manifest = "mcpp.toml"` and no `sources` list, and the validator requires one:
+
+```
+error: d.lua: xpkg-lua://example.mathkit@0.1.0: error: synthesised manifest
+       missing sources (mcpp segment must declare `sources = { ... }`)
+```
+
+Adding `sources = { "src/*.cppm" }` to the emitted `mcpp` segment makes it
+validate. Measured on 2026.9.8.1.

docs/zh/21-commands-by-scenario.md

@@ -170,18 +170,6 @@ warning: pre-v1 cache at '/home/speak/.mcpp/bmi' occupies 167.5 MiB and is no lo
 `mcpp self config --mirror CN|GLOBAL` 选择下载镜像;mcpp 与 xlings 各自持有这个设置,
 为其中一个选定不会为另一个选定。
 
-## 当前边界
-
-- `mcpp why --format json` 只对 `toolchain` 话题有定义。其余话题报
-  `'<topic>' has no machine-readable shape yet` 并以非零退出。
-- `mcpp search` 按子串匹配;没有字段选择器,也没有把搜索限定到单个命名空间的方式。
-- `mcpp clean --stale` 读 `target/.build_cache`,它保存的近期条目数量有上限。一个工程
-  如果构建过的 (目标, profile) 组合多于这个上限,最旧的条目会被挤掉;条目被挤掉的目录
-  随后按未记录处理 —— 在 `--older-than` 之内保留,超出则删除。
-- `mcpp cache gc --older-than 0` 以 `bad --older-than value '0'
-  (expected <N>{s,m,h,d})` 被拒绝,而 `mcpp clean --stale --older-than 0` 接受。
-  两个选项共用一个 parser,但这一种取值上不一致。
-
 ## `[hooks]` —— 项目构建生命周期命令(实验性)
 
 > **实验性。** Hook 目前**不能**决定一次构建成功与否。所有 Hook 失败都以
@@ -313,3 +301,27 @@ deps = ["xim:mcpp-hooks-audioplayer@0.0.1"]
 根据构建成功或失败播放不同提示音。`side_effect = false` 写出来而不是靠默认值:它是
 这份 manifest 自己就想要的值——缺个音频设备不该让构建失败——所以等这个键有了不止
 一个可接受的值之后,它仍然会这么写。
+
+## 当前边界
+
+- `mcpp why --format json` 只对 `toolchain` 话题有定义。其余话题报
+  `'<topic>' has no machine-readable shape yet` 并以非零退出。
+- `mcpp search` 按子串匹配;没有字段选择器,也没有把搜索限定到单个命名空间的方式。
+- `mcpp clean --stale` 读 `target/.build_cache`,它保存的近期条目数量有上限。一个工程
+  如果构建过的 (目标, profile) 组合多于这个上限,最旧的条目会被挤掉;条目被挤掉的目录
+  随后按未记录处理 —— 在 `--older-than` 之内保留,超出则删除。
+- `mcpp cache gc --older-than 0` 以 `bad --older-than value '0'
+  (expected <N>{s,m,h,d})` 被拒绝,而 `mcpp clean --stale --older-than 0` 接受。
+  两个选项共用一个 parser,但这一种取值上不一致。
+
+对一个自带 `mcpp.toml` 的包,`mcpp emit xpkg` 产出的描述符会被 `mcpp xpkg parse`
+拒绝。产出的 `mcpp` 段带 `manifest = "mcpp.toml"` 而没有 `sources` 列表,而校验器
+要求有一个:
+
+```
+error: d.lua: xpkg-lua://example.mathkit@0.1.0: error: synthesised manifest
+       missing sources (mcpp segment must declare `sources = { ... }`)
+```
+
+给产出的 `mcpp` 段补上 `sources = { "src/*.cppm" }` 即可通过校验。实测于
+2026.9.8.1。