docs: repoint the cross-references the split invalidated, and put chapter 17 back in order

Moving six sections out of 05 left references behind that pointed at section
numbers which had moved with them. Fourteen in the two languages: `§2.8.1`
from inside the chapter that now contains it, `§2.13` from the chapter that
now IS it, `§2.14` from the chapter it moved to, `§2.7.1` from the chapter it
left. Each is repointed at the chapter that holds the content now, or at the
section of the same chapter when the reference became local.

Chapter 17's 'Related chapters' had ended up in the middle, and its own bullet
for 05 said 'every manifest key, including [xlings]' -- the one claim the move
made false. It is last again, renumbered, and 05 is described as the rest of the
manifest.

This is what the review pass is for: a mechanical move keeps every heading
structure valid and leaves the prose pointing at the old shape.

Author: speak-agent

docs/07-build-mcpp.md

@@ -376,7 +376,7 @@ mcpp builds that `kind = "bin"` target **for the build machine** (even under
 `--target`), caches it globally, and returns the path. The request lives in
 `mcpp.toml` rather than here for the same reason a dependency does: asking the
 graph for an extra artifact is a graph-level request, and the graph stays
-statically analysable. See [05 §2.14](05-mcpp-toml.md) for the full contract,
+statically analysable. See *Host tools from a dependency* in this chapter for the full contract,
 including `[tools.overrides]` and `reexport = true` (which is how a library
 provides the whole toolchain, so a project declares **one** dependency instead of
 four).
@@ -1079,7 +1079,7 @@ plugins = { version = "0.3.0", features = ["rules-spirv"], host-module = true }
 ```
 
 **`[build-dependencies]`, not `[dependencies]`** — a rule package is the case
-§2.6.1 describes exactly: its library must never reach the target while its
+[05 §2.6.1](05-mcpp-toml.md) describes exactly: its library must never reach the target while its
 rule is still wanted. The two axes are separate, so `host-module = true` says
 *which build-time product* is wanted and the section says *whether the package
 reaches the target*; a rule package answers "no" on the second axis, and the
@@ -1213,6 +1213,6 @@ unsupported platform into an error its user cannot edit away. Scope it:
 ```
 
 `[target.<sel>.feature-deps.<feature>]` (2026.8.6.2+) follows the same rules as
-the other conditional dependency tables (§2.7.1). The **feature itself is
+the other conditional dependency tables ([14 — The Target Side](14-target-side.md)). The **feature itself is
 registered on every platform** — only what it pulls in is conditional — so
 requesting it where no predicate matches is not an unknown-feature error.

docs/14-target-side.md

@@ -342,7 +342,7 @@ The selector `<sel>` has three forms:
 |---|---|---|
 | **bare OS alias** | a single OS / family — the concise, common form | `[target.windows]`, `[target.unix]` |
 | **`cfg(...)` predicate** | a compound condition (arch / env / combinators) | `[target.'cfg(all(linux, not(arch = "aarch64")))']` |
-| **exact triple** | one specific target (also carries `toolchain` / `linkage` / `sysroot` / `runner`; see §2.7.3) | `[target.x86_64-linux-musl]` |
+| **exact triple** | one specific target (also carries `toolchain` / `linkage` / `sysroot` / `runner`; see [05 §2.7.3](05-mcpp-toml.md)) | `[target.x86_64-linux-musl]` |
 
 A selector may carry platform-conditional **dependencies** and **build flags**:
 
@@ -365,7 +365,7 @@ there is no ambiguity. Use the bare form for a single OS/family; use `cfg(...)`
 for arch/env conditions and combinators.
 
 - **Keys**: `dependencies` / `dev-dependencies` / `build-dependencies` /
-  `feature-deps.<feature>` (mcpp 2026.8.6.2+ — see §2.14; the feature is
+  `feature-deps.<feature>` (mcpp 2026.8.6.2+ — see [07 — build.mcpp](07-build-mcpp.md); the feature is
   registered unconditionally, only its dependency set is scoped), and
   `build` with `cflags` / `cxxflags` / `ldflags` / `sources` (mcpp 0.0.95+ —
   conditional source globs, e.g. gating `src/x86/**/*.asm` behind

docs/17-the-project-environment.md

@@ -166,16 +166,16 @@ package the host cannot install is an error, not a skipped entry. A tool that
 exists for one host platform only is therefore declared for that platform
 (2026.9.2.1): `deps = [{ linux = "qemu-user-aarch64" }]` declares the emulator
 on Linux and nothing elsewhere. The keys and the resolution rule are in
-chapter 5, §2.13.
+this chapter.
 
 **Which verbs install it.** An entry may name a tier —
 `{ version = "0.24.0", when = "run" }` — and a `[feature-xlings.<feature>]`
 table gates one on a feature. A tool the project will not use is then not
-downloaded: chapter 5, §2.13. Omitting the tier is the historical behaviour.
+downloaded: this chapter. Omitting the tier is the historical behaviour.
 
 **The runner.** A program under `[xlings.workspace]` is also where
 `[target.<triple>].runner` looks first for its first element, before `PATH`
-(chapter 5, §2.7.3). The two keys together provision a user-mode emulator on a
+([05 §2.7.3](05-mcpp-toml.md)). The two keys together provision a user-mode emulator on a
 CI host and execute a cross-built artifact through it, without the manifest
 naming the payload's path.
 
@@ -190,15 +190,7 @@ naming the payload's path.
 | a tool only one verb or one feature needs | `when = "run"`, `[feature-xlings.<f>]` |
 | which environment | `[xlings] subos` |
 
-## 7. Related chapters
-
-- [7 - build.mcpp](07-build-mcpp.md) — the contract a build program receives,
-  including the `PATH` it runs with.
-- [8 - Toolchain Internals](08-toolchain-internals.md) — runtime selection,
-  the `RuntimeBinding` snapshot, and the degradation rules.
-- [5 - mcpp.toml](05-mcpp-toml.md) — every manifest key, including `[xlings]`.
-
-## `[xlings]` — the project's environment
+## 7. `[xlings]` — the manifest keys
 
 ```toml
 [xlings.workspace]                 # what this project's environment contains
@@ -514,3 +506,11 @@ exact version of that package cannot edit.
 program's environment is declared by its own package, and an environment's by
 that environment. The key is now an error naming both. Nothing in the index
 used it.
+
+## 8. Related chapters
+
+- [7 - build.mcpp](07-build-mcpp.md) — the contract a build program receives,
+  including the `PATH` it runs with.
+- [8 - Toolchain Internals](08-toolchain-internals.md) — runtime selection,
+  the `RuntimeBinding` snapshot, and the degradation rules.
+- [5 - mcpp.toml](05-mcpp-toml.md) — the rest of the manifest.

docs/22-features-and-capabilities.md

@@ -38,7 +38,7 @@ feature carry package-owned preprocessor `defines`, feature-gated source globs
 the feature is active, exactly like an index descriptor's `features.<f>.sources`;
 the highest-frequency shape for vendored libraries: *feature = a source set + a
 define*), feature-gated per-glob compile flags (`flags`, mcpp 0.0.101+), and/or
-capability `requires` / `provides` (see §2.8.1) alongside its implied features:
+capability `requires` / `provides` (see *`provides` / `requires`* below) alongside its implied features:
 
 ```toml
 [features]
@@ -67,11 +67,11 @@ simd       = { sources = ["src/simd/**"], flags = [
   defines`. They are restricted by convention to the package's **own** namespaced
   macros: a feature does **not** inject free-form package-wide `cflags`/`ldflags`,
   which would break the additive feature-union model. Link flags come from a
-  provider dependency (§2.8.1), not from a feature.
+  provider dependency (see *`provides` / `requires`* below), not from a feature.
 - The automatic `-DMCPP_FEATURE_<NAME>` is still defined for every active feature,
   so `defines` are additive to it.
 - `flags` (mcpp 0.0.101+) is the same ordered array-of-inline-tables grammar as
-  `[build].flags` (§2.3: `glob` required, plus `cflags`/`cxxflags`/`asmflags`/
+  `[build].flags` ([05 §2.3](05-mcpp-toml.md): `glob` required, plus `cflags`/`cxxflags`/`asmflags`/
   `defines`; the `[[features.<name>.flags]]` array-of-tables spelling is accepted
   too, like `[[build.flags]]`). When the feature is active the entries
   are appended **after** the base `[build].flags`, features in name order, so a
@@ -348,7 +348,7 @@ implementation cannot be fetched is a feature that does not exist, and a project
 using a **path** dependency during development never consults the index — so the
 failure appears only after publication, to somebody else.
 
-This composes with capabilities (§2.8.1): a single `backend-openblas` feature
+This composes with capabilities (*`provides` / `requires`* above): a single `backend-openblas` feature
 both **pulls** the provider (`compat.openblas`, which `provides = ["blas"]`) and
 **turns on** the consumer switch (`implies = ["use_blas"]`, which
 `requires = ["blas"]`). With one provider in the graph the capability binds
@@ -398,7 +398,7 @@ Two properties make this preferable to shipping the implementation
 unconditionally. A library that ships one takes a decision belonging to the
 program, and it cannot be undone: features are **additive**, so there is no way
 for a consumer to switch a default *off*. And because a dependency package's
-objects link unconditionally (§2.8.1), a shipped default plus a program-supplied
+objects link unconditionally (*`provides` / `requires`* above), a shipped default plus a program-supplied
 one is a duplicate definition rather than a replacement — the archive semantics
 that let a C++ standard library offer a replaceable `operator new` do not apply
 to a package dependency. Keeping the implementation behind a switch means the

docs/zh/07-build-mcpp.md

@@ -324,7 +324,7 @@ mcpp 会**为构建机器**构建那个 `kind = "bin"` target(即使在 `--targe
 全局缓存,并把路径交回。这个请求写在 `mcpp.toml` 而不是这里,理由和依赖本身
 一样:向依赖图索取一个额外产物是**图级别**的请求,而图必须保持可静态分析。
 完整契约(含 `[tools.overrides]` 与 `reexport = true` —— 库据此把整条工具链交给
-调用方,因此只需写**一条**依赖而不是四条)见 [05 §2.14](05-mcpp-toml.md)。
+调用方,因此只需写**一条**依赖而不是四条)见本章*依赖产出的 host 工具*。
 
 ### 用通配符声明输入:`rerun_if_changed_glob`(2026.8.6.2+)
 
@@ -907,7 +907,7 @@ rules-spirv = { sources = ["rules/spirv.cppm"] } # export module mcpp.rules.spir
 plugins = { version = "0.3.0", features = ["rules-spirv"], host-module = true }
 ```
 
-**用 `[build-dependencies]` 而不是 `[dependencies]`** —— 规则包正是 §2.6.1 描述的那种
+**用 `[build-dependencies]` 而不是 `[dependencies]`** —— 规则包正是 [05 §2.6.1](05-mcpp-toml.md) 描述的那种
 情形:它的库绝不该到达目标,而它的规则仍然被需要。两条轴是分开的:
 `host-module = true` 说的是**要哪一种构建期产物**,而 section 说的是**这个包是否到达
 目标**;规则包在第二条轴上的答案是"否",而 section 就是说这件事的地方。写在

docs/zh/14-target-side.md

@@ -290,7 +290,7 @@ mcpp 不认识的键 —— 打错的字,或来自更新版本 mcpp 的谓词 
 |---|---|---|
 | **裸 OS 别名** | 单个 OS / 族 —— 简洁且常用的形式 | `[target.windows]`、`[target.unix]` |
 | **`cfg(...)` 谓词** | 复合条件(arch / env / 组合子) | `[target.'cfg(all(linux, not(arch = "aarch64")))']` |
-| **精确三元组** | 某个具体目标(同时承载 `toolchain` / `linkage` / `sysroot` / `runner`,见 §2.7.3) | `[target.x86_64-linux-musl]` |
+| **精确三元组** | 某个具体目标(同时承载 `toolchain` / `linkage` / `sysroot` / `runner`,见 [05 §2.7.3](05-mcpp-toml.md)) | `[target.x86_64-linux-musl]` |
 
 一个选择器可以承载平台条件的**依赖**与**构建 flag**:
 
@@ -312,7 +312,7 @@ cxxflags = ["-march=x86-64-v2"]
 单个 OS/族用裸形式,arch/env 条件与组合子用 `cfg(...)`。
 
 - **可用键**:`dependencies` / `dev-dependencies` / `build-dependencies` /
-  `feature-deps.<feature>`(mcpp 2026.8.6.2+ —— 见 §2.14;feature 本身无条件注册,
+  `feature-deps.<feature>`(mcpp 2026.8.6.2+ —— 见 [07 —— build.mcpp](07-build-mcpp.md);feature 本身无条件注册,
   只有它的依赖集合受限定),以及带 `cflags` / `cxxflags` / `ldflags` / `sources`
   的 `build`(mcpp 0.0.95+ —— 条件源码 glob,例如把 `src/x86/**/*.asm` 收在
   `cfg(arch = "x86_64")` 之后;`!` 排除 glob 在此同样有效),再加 `flags` 与

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

@@ -131,14 +131,14 @@ create/bootstrap that environment instead of falling back to active/default
 这份声明在每台构建本工程的宿主上都会供给,宿主装不了的包是错误,不是被跳过的条目。
 只存在于某一个宿主平台的工具因此按平台声明(2026.9.2.1):
 `deps = [{ linux = "qemu-user-aarch64" }]` 在 Linux 上声明这个模拟器,在别处什么都不声明。
-键与解析规则见第 5 章 §2.13。
+键与解析规则见本章。
 
 **哪些命令会安装它。** 一条条目可以带档位 —— `{ version = "0.24.0", when = "run" }` ——
 `[feature-xlings.<feature>]` 则把工具挂在某个 feature 上。用不到的工具因此不会被下载:
-见第 5 章 §2.13。不写档位就是从前的行为。
+见本章。不写档位就是从前的行为。
 
 **runner。** `[xlings.workspace]` 下的程序也是 `[target.<triple>].runner` 查找其第一个元素
-的首选位置,在 `PATH` 之前(第 5 章 §2.7.3)。两个键合起来,在 CI 宿主上供给用户态模拟器,
+的首选位置,在 `PATH` 之前([05 §2.7.3](05-mcpp-toml.md))。两个键合起来,在 CI 宿主上供给用户态模拟器,
 并通过它执行交叉构建的产物,而清单不必写出载荷的路径。
 
 ## 6. 什么该写在别处
@@ -152,15 +152,7 @@ create/bootstrap that environment instead of falling back to active/default
 | 只有某个命令或某个 feature 需要的工具 | `when = "run"`、`[feature-xlings.<f>]` |
 | 用哪个环境 | `[xlings] subos` |
 
-## 7. 相关章节
-
-- [7 - build.mcpp](07-build-mcpp.md) —— 构建程序收到的契约,含它运行时的
-  `PATH`。
-- [8 - 工具链内部](08-toolchain-internals.md) —— 运行时选择、`RuntimeBinding`
-  快照与降级规则。
-- [5 - mcpp.toml](05-mcpp-toml.md) —— 全部清单键,含 `[xlings]`。
-
-## `[xlings]` — 工程的环境
+## 7. `[xlings]` —— manifest 键
 
 ```toml
 [xlings.workspace]                 # 这个工程的环境里有什么
@@ -428,3 +420,11 @@ error: `xim:cuda-nvcc` is pinned to 12.0.0 by this project, and mcpp:plugins
 `[xlings.envs]` 曾被物化进 `.xlings.json`,而没有任何东西读它:程序的环境由它自己
 的包声明,环境的环境由那个环境声明。现在这个键是错误,并同时点名这两者。索引里没有
 任何包用过它。
+
+## 8. 相关章节
+
+- [7 - build.mcpp](07-build-mcpp.md) —— 构建程序收到的契约,含它运行时的
+  `PATH`。
+- [8 - 工具链内部](08-toolchain-internals.md) —— 运行时选择、`RuntimeBinding`
+  快照与降级规则。
+- [5 - mcpp.toml](05-mcpp-toml.md) —— manifest 的其余部分。

docs/zh/22-features-and-capabilities.md

@@ -17,7 +17,7 @@ Feature 是一个包提供可选内容的方式:一个编译宏、一份额外
 0.0.95+——列出的 glob 离开默认构建,仅当 feature 激活时才编译,与 index 描述符的
 `features.<f>.sources` 完全对等;这正是 vendored 大库最高频的形态:*feature =
 一组源文件 + 一个 define*)、feature 门控的 per-glob 编译旗标(`flags`,mcpp
-0.0.101+),以及 capability 的 `requires` / `provides`(见 §2.8.1):
+0.0.101+),以及 capability 的 `requires` / `provides`(见下文*`provides` / `requires`*):
 
 ```toml
 [features]
@@ -42,9 +42,9 @@ simd       = { sources = ["src/simd/**"], flags = [
 - `defines` 为**裸**宏名(不带 `-D`);feature 激活时每个脱糖为 `-D<x>`,加到该包
   自己的编译上——与 `[targets.*] defines` 完全一致。按约定仅限包**自有**的带命名
   空间宏:feature **不**注入自由的包级 `cflags`/`ldflags`,否则会破坏加性的 feature
-  并集模型。链接旗标来自 provider 依赖(§2.8.1),而非 feature。
+  并集模型。链接旗标来自 provider 依赖(见下文*`provides` / `requires`*),而非 feature。
 - 每个激活的 feature 仍会得到自动的 `-DMCPP_FEATURE_<NAME>`,`defines` 与之叠加。
-- `flags`(mcpp 0.0.101+)与 `[build].flags`(§2.3)共用同一有序 inline-table 数组
+- `flags`(mcpp 0.0.101+)与 `[build].flags`([05 §2.3](05-mcpp-toml.md))共用同一有序 inline-table 数组
   文法(`glob` 必填,加 `cflags`/`cxxflags`/`asmflags`/`defines`;与
   `[[build.flags]]` 一样也接受 `[[features.<name>.flags]]` 拼写)。feature 激活时
   条目追加在 base `[build].flags` **之后**(feature 按名
@@ -284,7 +284,7 @@ compat.openblas = "0.3"
 feature**,而开发期使用 **path** 依赖的工程根本不查索引 —— 该失败只在发布之后才出现,
 而且是出现在别人身上。
 
-该机制与能力(§2.8.1)组合:单个 `backend-openblas` feature 既**拉取** provider
+该机制与能力(上文*`provides` / `requires`*)组合:单个 `backend-openblas` feature 既**拉取** provider
 (`compat.openblas`,其 `provides = ["blas"]`),又**开启**消费方开关
 (`implies = ["use_blas"]`,其 `requires = ["blas"]`)。当图中只有一个 provider 时,
 能力自动绑定——消费方只需写 `features = ["backend-openblas"]`。
@@ -329,6 +329,6 @@ std-freestanding-alloc-kal = "0.1.x"
 
 有两条性质使该形状优于无条件随包提供实现。随包提供实现的库替程序做了本属程序的决定,
 而且**撤销不掉**:feature 是**加性**的,消费方没有把某个默认**关掉**的手段。以及,由于
-依赖包的目标文件无条件参与链接(§2.8.1),随包的默认加上程序自备的那份是**重复定义**
+依赖包的目标文件无条件参与链接(上文*`provides` / `requires`*),随包的默认加上程序自备的那份是**重复定义**
 而非替换 —— 让 C++ 标准库能提供可替换 `operator new` 的那套归档语义,对包依赖并不适用。
 把实现放在开关之后,意味着两者**从不共存**。