docs: the emit/parse mismatch, read the second time from the exit code

The first description of it in this batch was wrong in the direction that
matters. It said the emitted descriptor lacks a `sources` list which the
validator requires, and that adding the list by hand makes it validate.

Measured again, this time on the STATUS rather than the output: `mcpp xpkg
parse` reports `unknown mcpp-segment key 'manifest'` and exits 1. The missing
`sources` error follows from it -- the ignored key means nothing derives
sources from the manifest it names -- and adding the list removes the second
error, prints the summary, and still exits 1. The first reading took a printed
summary for success.

mcpp-index uses that key in 0 of 218 descriptors. A package keeping its own
mcpp.toml omits the `mcpp` field entirely. So the defect is not a missing
list: `mcpp emit xpkg` writes a descriptor shape that the resolver in the same
release does not implement and that no published descriptor uses.

Author: speak-agent

.agents/docs/2026-09-08-documentation-architecture-three-trees.md

@@ -554,12 +554,23 @@ README because a rule author will meet all three:
 - **The compiler is a declared input.** Without it, editing `toyc.sh` left every
   edge clean and the artifact kept the previous compiler's bytes.
 
-And one in the tooling: `mcpp emit xpkg` produces a descriptor that
-`mcpp xpkg parse` rejects for a package keeping 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 in `docs/21` as a limitation; not fixed in a documentation
-change.
+And one in the tooling, whose first description in this document was wrong in a
+way worth keeping. `mcpp emit xpkg` writes `manifest = "mcpp.toml"` into the
+`mcpp` segment; `mcpp xpkg parse` reports that key as **unknown** and exits 1,
+and the "missing sources" error follows from it — the ignored key means nothing
+derives sources from the manifest it names.
+
+> The first reading said "adding `sources` by hand makes it validate". It does
+> not. It removes the second error, the summary prints, and the command still
+> exits 1. The conclusion came from reading the OUTPUT rather than the STATUS,
+> which is the failure this repository already has a memory for.
+
+`mcpp-index` uses that key in **0 of 218** descriptors: a package keeping its own
+`mcpp.toml` omits the `mcpp` field entirely and mcpp looks the manifest up under
+the version directory. So the defect is not a missing list — it is that `emit`
+writes a descriptor shape the resolver in the same release does not implement
+and no published descriptor uses. Recorded in `docs/21`; not fixed in a
+documentation change.
 
 `build_examples.sh` refused all four new example roots for being in neither
 `BUILD` nor `SKIP`. That is the denominator discipline working, and it is the

docs/21-commands-by-scenario.md

@@ -371,14 +371,21 @@ it will still say so once the key has more than one accepted value.
   (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:
+`mcpp emit xpkg` writes a key `mcpp xpkg parse` does not know. For a package
+that keeps its own `mcpp.toml`, the emitted `mcpp` segment ends with
+`manifest = "mcpp.toml"`, and the descriptor parser reports it as unknown:
 
 ```
-error: d.lua: xpkg-lua://example.mathkit@0.1.0: error: synthesised manifest
-       missing sources (mcpp segment must declare `sources = { ... }`)
+error: unknown mcpp-segment key 'manifest' — silently ignored at build time
+       by this mcpp version
+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.
+The second error follows from the first: the ignored key means no sources are
+derived from the manifest it names. Adding `sources = { … }` by hand removes the
+second and not the first, and `mcpp xpkg parse` still exits 1.
+
+No descriptor in `mcpp-index` uses that key — 0 of 218. A package that keeps its
+own `mcpp.toml` omits the `mcpp` field entirely, and mcpp looks the manifest up
+under the version directory. Measured on 2026.9.8.1.

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

@@ -243,7 +243,8 @@ path.
   imply `host-module`. `mcpp:plugins` declares `default = []`; a rule package
   whose rule is on by default is refused with a message naming the module and
   the key to add.
-- `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. Adding `sources = { … }` to the emitted descriptor makes it validate.
+- `mcpp emit xpkg` writes `manifest = "mcpp.toml"` into the `mcpp` segment, and
+  `mcpp xpkg parse` reports that key as unknown and exits 1. No descriptor in
+  `mcpp-index` uses it (0 of 218); a package keeping its own `mcpp.toml` omits
+  the `mcpp` field entirely. See *Current limitations* in
+  [21 — Commands by Scenario](21-commands-by-scenario.md).

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

@@ -314,14 +314,21 @@ deps = ["xim:mcpp-hooks-audioplayer@0.0.1"]
   (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` 列表,而校验器
-要求有一个:
+`mcpp emit xpkg` 写出一个 `mcpp xpkg parse` 不认识的键。对一个自带 `mcpp.toml`
+的包,产出的 `mcpp` 段以 `manifest = "mcpp.toml"` 结尾,而描述符解析器把它报为
+未知键:
 
 ```
-error: d.lua: xpkg-lua://example.mathkit@0.1.0: error: synthesised manifest
-       missing sources (mcpp segment must declare `sources = { ... }`)
+error: unknown mcpp-segment key 'manifest' — silently ignored at build time
+       by this mcpp version
+error: synthesised manifest missing sources (mcpp segment must declare
+       `sources = { ... }`)
 ```
 
-给产出的 `mcpp` 段补上 `sources = { "src/*.cppm" }` 即可通过校验。实测于
+第二个错误由第一个导出:键被忽略,于是没有从它点名的那份 manifest 推导出任何
+源。手工补上 `sources = { … }` 只消掉第二个,消不掉第一个,`mcpp xpkg parse`
+仍然以 1 退出。
+
+`mcpp-index` 里没有任何描述符使用那个键 —— 218 个里 0 个。自带 `mcpp.toml` 的包
+**整个省略 `mcpp` 字段**,由 mcpp 在版本目录下查找那份 manifest。实测于
 2026.9.8.1。

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

@@ -222,7 +222,7 @@ mcpp::floor("cuda.driver", runtime_needs);
 - 规则包自己 `[features] default` 里的规则 feature 不隐含 `host-module`。
   `mcpp:plugins` 声明 `default = []`;规则默认开启的规则包会被拒绝,消息点名
   该模块与需要补的键。
-- 对一个自带 `mcpp.toml` 的包,`mcpp emit xpkg` 产出的描述符会被
-  `mcpp xpkg parse` 拒绝:产出的 `mcpp` 段带 `manifest = "mcpp.toml"` 而没有
-  `sources` 列表,而校验器要求有一个。给产出的描述符补上 `sources = { … }`
-  之后即可通过校验。
+- `mcpp emit xpkg` 把 `manifest = "mcpp.toml"` 写进 `mcpp` 段,而
+  `mcpp xpkg parse` 把该键报为未知并以 1 退出。`mcpp-index` 里没有任何描述符使用
+  它(218 个里 0 个);自带 `mcpp.toml` 的包整个省略 `mcpp` 字段。见
+  [21 —— 按场景选命令](21-commands-by-scenario.md)的*当前边界*。