docs: number the chapters by band, and write the design the reorganisation was missing

Two things, and the second is the one that matters.

The chapters are renumbered so the number says which part a chapter is in: 0x
uses mcpp, 1x ships what was built, 2x is toolchains and targets, 3x is bare
metal and devices, 5x is the machine-facing contracts, 9x is mcpp itself. Within
a part the order is a reading order. The index read `00, 01, 05, 06, 07, 21, 22`
under Part I, which is a list a reader cannot sort. Renumbering was refused in
the previous batch on a measurement that counted 103 citing files; 73 of those
are `.agents/docs` design records, where citing the number a chapter had at the
time is correct. The live cost is 29 files and 56 occurrences, plus 287
intra-docs links, all scripted -- and the earlier refusal conflated an immutable
record with live code.

The second thing is `.agents/docs/2026-09-08-the-documentation-as-a-book.md`. A
reorganisation groups the chapters that exist; it does not decide what each one
is FOR. Measured: testing is a section in seven chapters, dependency resolution
in seven, C++ modules in seven, and the model -- what mcpp's moving parts are --
is a section in none. Five of 24 chapters state their reader and their question;
six have a limits section.

So the design specifies, per chapter, the reader, the one question it answers,
what it contains, what it must NOT contain, where it sits and why. It creates
three chapters for the three unowned topics, moves build programs beside rule
authoring because they are one subject at two scales, moves bare metal in front
of devices because that is the arc, and states the rule that keeps a topic from
being explained a second time.

That implies a second renumbering, which is the cost of having reorganised
before designing. It is stated in the design rather than hidden.

Author: speak-agent

.agents/docs/2026-09-08-the-documentation-as-a-book.md

@@ -18,21 +18,23 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-269 records.
+270 records.
 
 ## By subject
 
 Records that declare one. Everything else is listed by date below.
 
 ### docs
 
+- [The documentation as a book: a chapter-by-chapter design](2026-09-08-the-documentation-as-a-book.md) — active
 - [A curriculum for the examples, a reference for the documentation, and a check with a denominator](2026-09-08-examples-curriculum-and-documentation-plan.md) — superseded by [2026-09-08-documentation-architecture-three-trees.md](2026-09-08-documentation-architecture-three-trees.md)
 - [Three documentation trees, three audiences, and the rule for citing between them](2026-09-08-documentation-architecture-three-trees.md) — active
 
 ## By date
 
 ### 2026-09
 
+- [The documentation as a book: a chapter-by-chapter design](2026-09-08-the-documentation-as-a-book.md) — active
 - [A curriculum for the examples, a reference for the documentation, and a check with a denominator](2026-09-08-examples-curriculum-and-documentation-plan.md) — superseded by [2026-09-08-documentation-architecture-three-trees.md](2026-09-08-documentation-architecture-three-trees.md)
 - [Three documentation trees, three audiences, and the rule for citing between them](2026-09-08-documentation-architecture-three-trees.md) — active
 - [第六轮生态复核:工具平面的目标轴](2026-09-07-round6-ecosystem-review.md)

.agents/docs/README.md

@@ -20,7 +20,7 @@ fail=0
 bad() { echo "FAIL: $*"; fail=1; }
 
 # Tutorials address the reader on purpose: the reader is following along.
-TUTORIALS="00-getting-started.md 01-examples.md 04-build-from-source.md"
+TUTORIALS="00-getting-started.md 01-examples.md 90-build-from-source.md"
 
 # Headings outside fenced code blocks. `# …` inside a ```sh block is a shell
 # comment, and counting it made the first version of this script report a

.github/tools/check_docs_style.sh

@@ -136,7 +136,7 @@ fi
 # (b) The version BOOTSTRAPPED FROM (.xlings.json) names a mcpp that is already
 #     published, and is NOT required to equal the version being built. It
 #     deliberately lags, and is bumped in a separate commit AFTER the release
-#     exists in xim-pkgindex (see docs/09-release.md). Requiring equality here is
+#     exists in xim-pkgindex (see docs/92-release.md). Requiring equality here is
 #     what an earlier revision of this script got wrong: it sent CI to install a
 #     version that did not exist yet, and every job died with
 #     `package 'mcpp@<unreleased>' not found`.

.github/tools/check_version_pins.sh

@@ -55,7 +55,7 @@ concurrency:
 # NOT to be confused with the .xlings.json workspace pin, which this used to be
 # kept equal to. That one is the BOOTSTRAP compiler for the self-host builds and
 # has a different requirement — it must be a released mcpp that can build the
-# CURRENT source tree — so it stays hand-maintained. See docs/09-release.md.
+# CURRENT source tree — so it stays hand-maintained. See docs/92-release.md.
 
 jobs:
   # ──────────────────────────────────────────────────────────────────

.github/workflows/ci-fresh-install.yml

@@ -677,7 +677,7 @@ C++20 modules 的第二个编译器(icpx,或带 SYCL 前端的 clang)。
 配套的规则包在 `mcpp:plugins` 0.2.0:`mcpp.rules.sycl` 驱动 `xim:dpcpp` 载荷,
 `mcpp.rules.hip` 在 NVIDIA 平台上把 HIP 当作 CUDA 运行时之上的一层头文件,
 `mcpp.rules.spirv` 增加 `glslc` 路线(`xim:shaderc` 使它从一句声明变成一条路线)。
-文档见 `docs/20-heterogeneous-builds.md` 的「lanes」一节。
+文档见 `docs/32-heterogeneous-builds.md` 的「lanes」一节。
 
 ### `mcpp clean --stale`:只清 target/ 里已无构建使用的指纹目录 (#565)
 
@@ -779,7 +779,7 @@ e2e 610 分别断言这五条(含 `mcpp` 命名空间零告警、其他命名空
 文件的相反的话。
 
 表因此扩到「由另一个编译器消费的语言」:CUDA 与 HIP,GLSL 的各个 stage 与无 stage 的
-`.glsl`,HLSL,OpenCL C,Metal。共 18 个扩展名,完整清单见 `docs/20-heterogeneous-builds.md`。
+`.glsl`,HLSL,OpenCL C,Metal。共 18 个扩展名,完整清单见 `docs/32-heterogeneous-builds.md`。
 
 这次扩表不能改变任何今天可用的构建,理由有两条且互相独立:设备扩展名**本来就不在**
 默认 source glob 里,所以没有 glob 变宽;而这些扩展名今天在 `sources` 里是**硬错误**,
@@ -814,7 +814,7 @@ e2e 610 分别断言这五条(含 `mcpp` 命名空间零告警、其他命名空
 
 ### 文档
 
-- 第 20 章由「加速器」更名为「异构硬件构建」(`docs/20-heterogeneous-builds.md`),副题指明
+- 第 20 章由「加速器」更名为「异构硬件构建」(`docs/32-heterogeneous-builds.md`),副题指明
   GPU 与 AI 加速器目标以及宿主/设备混合编译;`accel` 键不变。
 - 第 5 章与第 7 章(中英)补入 feature 选择的规则集合与 `mcpp.rules.*` / `mcpp.tools.*`
   命名;第 7 章中文版此前缺少命名一节,本次补齐。
@@ -957,7 +957,7 @@ generic target 取得同样的覆盖,所以空的下界不放宽任何东西。
 
 设计与调研:`.agents/docs/2026-09-05-accelerator-support-design.md`、
 `.agents/docs/2026-09-04-ai-accelerator-toolchain-ecosystem-survey.md`。
-新增手册章节 `docs/20-heterogeneous-builds.md`(中英双份)。
+新增手册章节 `docs/32-heterogeneous-builds.md`(中英双份)。
 
 ## [2026.9.4.3] — 2026-09-04
 
@@ -1159,7 +1159,7 @@ M-profile:MPU 按基址与上限描述区域,没有页表项。A-profile 有真
 `mcpp why runners` 列出本工程提供的 runner,与其余解析结果并列;
 `mcpp run --list-runners` 是同一份读取,单独报告。
 
-新增 `docs/18-devices.md`、`docs/19-supported-versions.md`(中英双份)。
+新增 `docs/31-devices.md`、`docs/51-supported-versions.md`(中英双份)。
 指令协议版本 6。
 
 ## [2026.9.4.1] — 2026-09-04
@@ -2543,7 +2543,7 @@ windows-x86_64),而不是手头有哪几台 runner —— 一台拿到发布二
   本次发布修的三条缺陷全部来自「一个事实在多处各自推导」。各包的载荷路径由
   `MCPP_XPKG_*_DIR` 另行回答,与 `PATH` 是两个问题。
 
-  新增 `examples/07-project-subos/` 与 [第 17 章](docs/17-the-project-environment.md)。
+  新增 `examples/07-project-subos/` 与 [第 17 章](docs/23-the-project-environment.md)。
 
 ### 测试
 
@@ -2792,7 +2792,7 @@ windows-x86_64),而不是手头有哪几台 runner —— 一台拿到发布二
 
 ### 文档
 
-- 新增[第 16 章 —— 目标三元组](docs/16-the-target-triple.md)(中英双份):
+- 新增[第 16 章 —— 目标三元组](docs/21-the-target-triple.md)(中英双份):
   三段各是什么、第三段在每个平台上命名的是不同的轴、两种体系的分界、
   以及该用哪种拼法。
 
@@ -2909,7 +2909,7 @@ windows-x86_64),而不是手头有哪几台 runner —— 一台拿到发布二
   判据是失败模态:选错不会让链接失败,会得到一个能跑、偶尔崩的程序。
   `[build] runner` 早已按同一条规则处理。
 
-- **`docs/14-target-side.md`(中英)与 `docs/specs/target-side.md`(SPEC-002)。**
+- **`docs/22-target-side.md`(中英)与 `docs/specs/target-side.md`(SPEC-002)。**
 
 ### 变更
 
@@ -3890,7 +3890,7 @@ windows-x86_64),而不是手头有哪几台 runner —— 一台拿到发布二
   (它不改任何一条边 —— 进了会让「抬高超时」重建全世界)。
 - 旧版 mcpp 遇到 `module_extensions` 会警告+忽略,然后把那些文件当普通翻译单元
   编译 —— **错误的构建**而不是干净的失败。发布用了这个键的包必须声明 mcpp 版本下限
-  (见 `docs/10-publishing-a-library.md`)。
+  (见 `docs/11-publishing-a-library.md`)。
 
 ## [2026.8.10.3] — 2026-08-10
 
@@ -4069,7 +4069,7 @@ windows-x86_64),而不是手头有哪几台 runner —— 一台拿到发布二
 
 机器可读输出有契约了。设计与实测见
 `.agents/docs/2026-08-08-machine-readable-output-protocol-design.md`,用户文档见
-`docs/11-machine-output.md`。
+`docs/50-machine-output.md`。
 
 ### 新增
 
@@ -4317,7 +4317,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 ### 文档
 
-- `docs/05-mcpp-toml.md` 的示例此前写的是 `import mcpp.rules.protobuf;`,**做不到**:mcpp 用依赖的裸 `package.name` 注册 host 模块,而 SPEC-001 要求 `name` 是单一原子段。随之澄清一条会咬人的约束:规则包的名字必须是**合法 C++ 模块名**(`grpcgen` 可以,`grpc-rules` 不行),否则报的是 `module 'grpc_rules' not found`,不会提示你名字有问题。
+- `docs/02-mcpp-toml.md` 的示例此前写的是 `import mcpp.rules.protobuf;`,**做不到**:mcpp 用依赖的裸 `package.name` 注册 host 模块,而 SPEC-001 要求 `name` 是单一原子段。随之澄清一条会咬人的约束:规则包的名字必须是**合法 C++ 模块名**(`grpcgen` 可以,`grpc-rules` 不行),否则报的是 `module 'grpc_rules' not found`,不会提示你名字有问题。
 
 ## [2026.8.5.1] — 2026-08-05
 
@@ -4516,7 +4516,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 ### 修复
 
-- **`[build] static_stdlib = false` 对测试二进制静默失效(#336)。** #124 在 0.0.52 明确写下这个 opt-out,`docs/05-mcpp-toml.md` 至今也还这么写;但 #202(0.0.86)把测试二进制改成与分发目标相同的静态 `-load_hidden` libc++ 时,新增的那条推导**没有带上 `staticStdlib` 门**。结果是约一年时间里 macOS 上的 `mcpp test` 没有任何办法回到动态 libc++,而文档一直在承诺它可以。
+- **`[build] static_stdlib = false` 对测试二进制静默失效(#336)。** #124 在 0.0.52 明确写下这个 opt-out,`docs/02-mcpp-toml.md` 至今也还这么写;但 #202(0.0.86)把测试二进制改成与分发目标相同的静态 `-load_hidden` libc++ 时,新增的那条推导**没有带上 `staticStdlib` 门**。结果是约一年时间里 macOS 上的 `mcpp test` 没有任何办法回到动态 libc++,而文档一直在承诺它可以。
 
 - **macOS 上全局对象在静态初始化期访问 `std::cout` 必崩(#336)。** Mach-O 没有按优先级排序的初始化段(`init_priority` 只在单个 TU 内有效),归档成员的初始化器按链接顺序排在最后;而 libc++ 的 `<iostream>` 不像 libstdc++ / MSVC STL 那样自带 `ios_base::Init` 守卫,流的构造只存在于库内对象里。两件事叠起来的后果是:默认配置下,任何在构造函数里碰 `std::cout` 的全局对象都会读到 vptr 为零的流,进程启动即 SIGSEGV —— 而且**包侧无法修复**,因为 `std::ios_base::Init` 在 libc++ 的头文件里只有前向声明(`ios:70`),标准为静态初始化次序提供的官方解药在 libc++ 上用户根本写不出来。
 
@@ -4550,7 +4550,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 ### 修复
 
-- **`--offline` 不再拒绝本地 git 远端。** `docs/05-mcpp-toml.md` 写明 `--offline` 的语义是「完全不碰网络……已安装的东西照常构建」,`prepare.cppm` 里依赖下载闸的注释也把线画在同一处:「这条线以上全是本地操作,一个依赖齐备的离线构建必须成功」。但 `git = "../sibling-repo"` 这种指向本地目录的远端,`ls-remote`/`clone` 都只是文件系统读取,拒绝它买不到任何隔离性。现在按远端形态判定——`file://`、以及不带 scheme 也不是 `git@host:path` 的存在路径,算本地(Windows 盘符 `C:\repo` 含冒号但不含 `@`,因此仍归本地)。
+- **`--offline` 不再拒绝本地 git 远端。** `docs/02-mcpp-toml.md` 写明 `--offline` 的语义是「完全不碰网络……已安装的东西照常构建」,`prepare.cppm` 里依赖下载闸的注释也把线画在同一处:「这条线以上全是本地操作,一个依赖齐备的离线构建必须成功」。但 `git = "../sibling-repo"` 这种指向本地目录的远端,`ls-remote`/`clone` 都只是文件系统读取,拒绝它买不到任何隔离性。现在按远端形态判定——`file://`、以及不带 scheme 也不是 `git@host:path` 的存在路径,算本地(Windows 盘符 `C:\repo` 含冒号但不含 `@`,因此仍归本地)。
 
 - **克隆被中途杀掉后不再永久提供错误的 commit。** 缓存目录以 commit 命名,但内容是 `git clone` 之后再 `git checkout` 两步做出来的;进程死在两步之间,目录名和 HEAD 就对不上了,而后续构建只检查目录存不存在。现在分支依赖会比对 `git rev-parse HEAD`,不符即删除重克隆(tag/rev 以 ref 名为身份,无可比之物)。
 
@@ -4633,7 +4633,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
   **最危险的一条判据**(`SuppressedInconclusive`):「本地查不到」单独不能推出「需要刷新」。xim 描述符不写 `namespace`,`(xim, x)` 永远匹配不上身份门 —— 把这种 miss 当真,任何带 xim 依赖的工程会**每次构建都刷**,比被删掉的 TTL 更糟。判据复用 `IndexRoute::authoritative_for`(#307),单测 + e2e 双闸锁住。
 
-  语义变化:`^1.2` 对**本地索引已知的版本**求解。上游新发的 1.3.0 需要 `mcpp index update` 或 `mcpp update` 才可见 —— 这正是那两个命令存在的意义,已写进 `docs/05-mcpp-toml.md`。
+  语义变化:`^1.2` 对**本地索引已知的版本**求解。上游新发的 1.3.0 需要 `mcpp index update` 或 `mcpp update` 才可见 —— 这正是那两个命令存在的意义,已写进 `docs/02-mcpp-toml.md`。
 
 - **`mcpp update` 不再是空操作。** 它此前只删 mcpp.lock 条目、然后叫用户去跑 `mcpp build` —— 而构建路径**从不读 mcpp.lock**(`prepare` 只写不读),所以删了等于没删,行为影响为零。它现在先强制刷新索引(显式意图 ⇒ 不看 TTL、不看去抖),并报告索引 rev 的变化;工程里没有任何走共享 registry 的依赖时跳过(刷了也没用)。
 
@@ -5629,7 +5629,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 - `[targets.<name>]` 下的不支持键不再被静默丢弃,而是产生 warning(`--strict` 下为 error),
   并指引到正确的机制(workspace / features / profile)。
-- 文档 `docs/05-mcpp-toml.md`(及 `docs/zh`)新增"构建配置该放哪"的决策指引。
+- 文档 `docs/02-mcpp-toml.md`(及 `docs/zh`)新增"构建配置该放哪"的决策指引。
   设计记录见 `.agents/docs/2026-06-18-per-target-build-config-design.md`。
 
 ## [0.0.54] — 2026-06-10

CHANGELOG.md

@@ -9,7 +9,7 @@
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
 
-| [Documentation](docs/) · [Getting Started](docs/00-getting-started.md) · [mcpp.toml Guide](docs/05-mcpp-toml.md) · [Examples](docs/01-examples.md) · [Toolchains](docs/03-toolchains.md) |
+| [Documentation](docs/) · [Getting Started](docs/00-getting-started.md) · [mcpp.toml Guide](docs/02-mcpp-toml.md) · [Examples](docs/01-examples.md) · [Toolchains](docs/20-toolchains.md) |
 |:---:|
 | [Package index mcpp-index](https://mcpplibs.github.io/mcpp-index/) · [Module libraries mcpplibs](https://github.com/mcpplibs) · [Community Forum](https://forum.d2learn.org/category/20) · [Issues](https://github.com/mcpp-community/mcpp/issues) · [Releases](https://github.com/mcpp-community/mcpp/releases) |
 | [![ci-linux](https://github.com/mcpp-community/mcpp/actions/workflows/ci-linux.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp/actions/workflows/ci-linux.yml) [![ci-macos](https://github.com/mcpp-community/mcpp/actions/workflows/ci-macos.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp/actions/workflows/ci-macos.yml) [![ci-windows](https://github.com/mcpp-community/mcpp/actions/workflows/ci-windows.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp/actions/workflows/ci-windows.yml) |
@@ -224,7 +224,7 @@ Then `import` it directly in your code:
 import mcpplibs.cmdline;
 ```
 
-> For more dependency options (version constraints, namespaces, Git references, local paths, etc.), see the [mcpp.toml guide — dependency management](docs/05-mcpp-toml.md).
+> For more dependency options (version constraints, namespaces, Git references, local paths, etc.), see the [mcpp.toml guide — dependency management](docs/02-mcpp-toml.md).
 
 ## Feature Overview
 
@@ -413,17 +413,17 @@ verified — CI builds **and executes** the artifact end-to-end (qemu/wine inclu
 > cross-compilers by construction, so any host that can install the LLVM
 > payload produces these targets. The C library, startup code, memory layout
 > and emulator travel with a board-support package rather than with mcpp — see
-> [docs/13 — Bare-Metal and Freestanding Targets](docs/13-baremetal.md).
+> [docs/13 — Bare-Metal and Freestanding Targets](docs/30-baremetal.md).
 
 ## Documentation
 
 - [Getting Started](docs/00-getting-started.md) — install → new → build → run in 5 minutes
 - [Examples](docs/01-examples.md)
-- [Packaging & Release](docs/02-pack-and-release.md)
-- [Toolchain Management](docs/03-toolchains.md)
-- [Building from Source](docs/04-build-from-source.md)
-- [mcpp.toml Guide](docs/05-mcpp-toml.md)
-- [Workspaces](docs/06-workspace.md)
+- [Packaging & Release](docs/10-pack-and-release.md)
+- [Toolchain Management](docs/20-toolchains.md)
+- [Building from Source](docs/90-build-from-source.md)
+- [mcpp.toml Guide](docs/02-mcpp-toml.md)
+- [Workspaces](docs/03-workspace.md)
 
 Full options for any command are available via `mcpp <cmd> --help`.