diff --git a/.github/workflows/pypi-publish.yml b/.github/workflows/pypi-publish.yml
new file mode 100644
index 000000000..af00b7d61
--- /dev/null
+++ b/.github/workflows/pypi-publish.yml
@@ -0,0 +1,200 @@
+name: pypi-publish
+
+# Publish the `mcpp-bin` wheels to PyPI (`pip install mcpp-bin`).
+#
+# Downstream of `release`, like aur-publish.yml and homebrew-publish.yml: the
+# wheels are built from the release's own mcpp-release.json and payloads, so
+# this runs only once the release workflow has completed.
+#
+# CREDENTIALS: none stored. Publishing uses PyPI Trusted Publishing (OIDC):
+# PyPI trusts this repository + workflow file + the `pypi` environment, and
+# the job exchanges its GitHub OIDC token for a short-lived upload token.
+# One-time setup is in scripts/pypi/README.md.
+#
+# ARMING: the automatic trigger builds, verifies and reports, and publishes
+# only when the repository variable PYPI_AUTOPUBLISH is `true`, for the reason
+# aur-publish.yml gives: an unattended push to a third-party service must be
+# armed by a human who has watched one publish succeed, not inherited from a
+# merge. `workflow_dispatch` carries its own explicit `publish` switch.
+
+on:
+  workflow_run:
+    workflows: [release]
+    types: [completed]
+  # Changes to the packaging itself build and pip-install the wheels of the
+  # latest release on every platform. A pull request never publishes.
+  pull_request:
+    paths:
+      - scripts/pypi/**
+      - tests/scripts/test_pypi_wheels.py
+      - .github/workflows/pypi-publish.yml
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: 'Upload to PyPI (false builds and verifies only)'
+        type: boolean
+        required: true
+        default: false
+      tag:
+        description: 'Release tag, e.g. v2026.9.21.3 (default: the latest release)'
+        type: string
+        required: false
+
+concurrency:
+  group: pypi-mcpp-bin
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build wheels
+    if: >-
+      github.event_name != 'workflow_run' ||
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    outputs:
+      version: ${{ steps.resolve.outputs.version }}
+      publish: ${{ steps.resolve.outputs.publish }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Builder contract tests
+        run: python3 tests/scripts/test_pypi_wheels.py
+
+      - name: Resolve the release and whether to publish
+        id: resolve
+        env:
+          TRIGGER: ${{ github.event_name }}
+          INPUT_TAG: ${{ inputs.tag }}
+          MANUAL_PUBLISH: ${{ inputs.publish }}
+          AUTOPUBLISH: ${{ vars.PYPI_AUTOPUBLISH }}
+        run: |
+          set -euo pipefail
+          if [[ -n "${INPUT_TAG:-}" ]]; then
+            tag="$INPUT_TAG"
+          elif [[ "$TRIGGER" == "workflow_run" ]]; then
+            # The released commit's mcpp.toml carries the released version.
+            tag="v$(grep -m1 -E '^\s*version\s*=' mcpp.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+          else
+            tag="$(gh release view -R "$GITHUB_REPOSITORY" --json tagName --jq .tagName)"
+          fi
+          version="${tag#v}"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+          # PyPI never accepts the same file twice, so an existing version is
+          # a finished job rather than something to retry.
+          code=$(curl -s -o /dev/null -w '%{http_code}' --retry 3 --retry-all-errors \
+                   "https://pypi.org/pypi/mcpp-bin/$version/json")
+          if [[ "$code" == "200" ]]; then
+            echo "::notice::mcpp-bin $version is already on PyPI; nothing to publish."
+            publish=false
+          elif [[ "$TRIGGER" == "workflow_run" ]]; then
+            if [[ "${AUTOPUBLISH:-}" == "true" ]]; then
+              publish=true
+            else
+              publish=false
+              echo "::notice::PYPI_AUTOPUBLISH is not set — building and verifying $tag without publishing."
+            fi
+          elif [[ "$TRIGGER" == "workflow_dispatch" ]]; then
+            publish="${MANUAL_PUBLISH:-false}"
+          else
+            publish=false
+          fi
+          echo "publish=$publish" >> "$GITHUB_OUTPUT"
+          echo "mcpp-bin $version from $tag; publish=$publish" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Build wheels from the release manifest
+        run: python3 scripts/pypi/build_wheels.py --tag "${{ steps.resolve.outputs.tag }}" --out dist
+
+      - name: Check metadata
+        run: |
+          python3 -m pip install --quiet twine
+          python3 -m twine check --strict dist/*.whl
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: mcpp-bin-wheels
+          path: dist/*.whl
+          if-no-files-found: error
+
+  # pip, not this workflow, picks the wheel: each runner installs from the
+  # directory of all four, so a wrong platform tag fails here rather than on a
+  # user's machine. The run then checks the two properties the launcher exists
+  # for: the per-user home is outside the Python environment, and the bundled
+  # xlings is the one seeded into it.
+  smoke:
+    name: pip install (${{ matrix.os }})
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@v4
+        with:
+          name: mcpp-bin-wheels
+          path: dist
+      - name: Install and run
+        shell: bash
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          set -euo pipefail
+          python -m venv venv
+          if [[ -x venv/Scripts/python.exe ]]; then py=venv/Scripts/python.exe; bin=venv/Scripts; else py=venv/bin/python; bin=venv/bin; fi
+          "$py" -m pip install --quiet --no-index --find-links dist mcpp-bin
+          home="$RUNNER_TEMP/home"; mkdir -p "$home"
+          export HOME="$home" USERPROFILE="$home"
+          unset MCPP_HOME MCPP_VENDORED_XLINGS
+          out="$("$bin/mcpp" --version)"
+          echo "$out"
+          [[ "$out" == *"$VERSION"* ]] || { echo "::error::expected $VERSION, got: $out"; exit 1; }
+          "$bin/mcpp" self env | tee env.txt
+          grep -F "MCPP_HOME" env.txt | grep -F ".mcpp" \
+            || { echo "::error::MCPP_HOME is not the per-user home"; exit 1; }
+          if grep -F "MCPP_HOME" env.txt | grep -qF "site-packages"; then
+            echo "::error::MCPP_HOME resolved into the Python environment"; exit 1
+          fi
+          # On Windows mcpp runs the vendored xlings in place (src/config.cppm,
+          # make_xlings_env), so the seeded copy is checked on POSIX only.
+          if [[ "$RUNNER_OS" != "Windows" ]]; then
+            ls "$home/.mcpp/registry/bin/" | grep -q '^xlings' \
+              || { echo "::error::the bundled xlings was not seeded into the home"; exit 1; }
+          fi
+
+  publish:
+    name: publish to PyPI
+    needs: [build, smoke]
+    if: needs.build.outputs.publish == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mcpp-bin/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: mcpp-bin-wheels
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
diff --git a/README.md b/README.md
index f169b4915..7c517cad2 100644
--- a/README.md
+++ b/README.md
@@ -13,20 +13,12 @@
 |:---:|
 | [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) |
+| Plugins · [mcpp-language-server (mcppls)](https://github.com/Sunrisepeak/mcpp-language-server) — a C++20/23 modules language server for VS Code, Zed, CLion, Neovim, AI agents (MCP) and CI |
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/6c85896e-9a37-4f62-acfb-d37a4eae2363" alt="mcpp demo" width="720">
 </p>
 
-> **Note (2026.9.20.1):** the `[c-abi]` verification probe now selects the
-> target it is verifying. On a freestanding target it selected none and
-> answered for the build host, which on a Linux host passed for the wrong
-> reason and on a Windows host failed for one. The `hostStripMacros`
-> compensation 2026.9.18.3 added is removed with it. This release also adds
-> `[kernel-abi] provides-interfaces` / `requires-interfaces`, answered at
-> dependency resolution, and `[c-abi-absent]`, which states what a C library
-> does not supply and in what shape. See CHANGELOG and docs/22.
-
 ## Highlights
 
 - **Modular build system** — C++ modules first: `import std` handled automatically, file-level incremental builds, automatic dependency analysis, nothing to configure
@@ -174,7 +166,23 @@ remain manually maintained and may intentionally lag.
 </details>
 
 <details>
-<summary><b>Option 4</b> — let an AI assistant install it for you</summary>
+<summary><b>Option 4</b> — pip (PyPI)</summary>
+
+```bash
+pip install mcpp-bin
+```
+
+Installs the `mcpp` command into the active Python environment; `pipx install
+mcpp-bin` gives it an environment of its own. The wheels carry the same
+prebuilt release binary for Linux x86_64 / aarch64, macOS 14+ on Apple silicon
+and Windows x86_64. Per-user data still lives in `~/.mcpp/`, outside the Python
+environment. On PyPI the name `mcpp` belongs to an unrelated project, hence
+`mcpp-bin` (see [`scripts/pypi/`](scripts/pypi/)).
+
+</details>
+
+<details>
+<summary><b>Option 5</b> — let an AI assistant install it for you</summary>
 
 Copy the following prompt to your AI coding assistant (Claude Code / Cursor / Copilot, etc.):
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 036185f0d..6f96a5303 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,6 +1,6 @@
 # mcpp
 
-> 一个 现代C++ 模块化构建工具 — 纯 C++23 模块编写，已实现自举
+> 以模块为先的现代 C++ 构建工具。mcpp 完全由 C++23 模块写成，并已实现自举。
 
 [English](README.md) | **简体中文**
 
@@ -13,6 +13,7 @@
 |:---:|
 | [包索引 mcpp-index](https://mcpplibs.github.io/mcpp-index/) · [模块化库 mcpplibs](https://github.com/mcpplibs) · [社区论坛](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) |
+| 支持的插件 · [mcpp-language-server（mcppls）](https://github.com/Sunrisepeak/mcpp-language-server) —— C++20/23 模块语言服务器，面向 VS Code、Zed、CLion、Neovim、AI Agent（MCP）与 CI |
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/6c85896e-9a37-4f62-acfb-d37a4eae2363" alt="mcpp demo" width="720">
@@ -20,28 +21,27 @@
 
 ## 核心特性
 
-- **模块化构建系统** — 专注 C++ 模块：`import std` 自动处理，文件级增量构建，模块依赖自动分析，零手动配置
-- **构建插件与异构硬件编程** — `build.mcpp` 与规则包扩展构建；CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C 各是一个规则包
-- **包管理与模块化库生态** — SemVer 约束、锁文件、跨项目 BMI 缓存、自定义索引；[mcpplibs](https://github.com/mcpplibs) 的库两行引入即可 `import`
-- **工具链管理与通用交叉构建** — `family@version` 按需安装；`--target` 让同一次构建换到 Windows、macOS、Cortex-M 或 RISC-V 裸机，一份源码经 openkal 触及多个有操作系统的目标
-- **环境与运行时** — xlings 提供的用户态环境：工具链与依赖都留在隔离沙盒里，runner 把产物送上板子或模拟器
-- **纯模块化自举** — mcpp 完全由 C++23 模块接口单元写成，并用它自己构建自己
+- **模块化构建系统**：以 C++ 模块为先。`import std` 自动处理，文件级增量构建，模块依赖自动分析，无需配置
+- **构建插件与异构硬件**：`build.mcpp` 与规则包扩展构建；CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C 各对应一个规则包
+- **包管理与模块化库生态**：SemVer 约束、锁文件、跨项目 BMI 缓存、自定义索引；[mcpplibs](https://github.com/mcpplibs) 中的库在 `mcpp.toml` 中加两行即可 `import`
+- **工具链管理与交叉编译**：`family@version` 按需安装；`--target` 把同一次构建切换到 Windows、macOS、Cortex-M 或 RISC-V 裸机，一份源码经 openkal 可构建到多个带操作系统的目标
+- **环境与运行时**：由 xlings 提供用户态环境。工具链与依赖留在隔离的沙盒中，runner 把产物送到开发板或模拟器上运行
+- **纯模块化自举**：mcpp 完全由 C++23 模块接口单元写成，并由它自己构建
 
-## 为什么选择 mcpp
+## mcpp 的定位
 
-mcpp 专门为 **C++23 模块化开发** 打造。如果你想在项目中使用 `import std`、模块接口单元（`.cppm`）、模块分区等现代 C++ 特性，mcpp 在 Linux、macOS ARM64 和 Windows x86_64 上能为你提供便捷且友好的开发体验。
+mcpp 专为 **C++23 模块化开发**设计。需要使用 `import std`、模块接口单元（`.cppm`）、模块分区等现代 C++ 特性的项目，在 Linux、macOS ARM64 与 Windows x86_64 上都能得到顺畅、友好的开发体验。
 
-C++ 通常把这五件事分给五个工具，而 mcpp 用一条命令承担全部五件。第二行是每一列
-在既有认知里通常对应的东西。
+C++ 通常把下面五项工作交给五个工具，mcpp 用一个命令完成全部五项。第二行列出每一列通常对应的工具。
 
-| mcpp | 通用构建系统 | 构建插件 | 包管理 | 工具链管理 | 环境与运行时 |
+| mcpp | 构建系统 | 构建插件 | 包管理 | 工具链管理 | 环境与运行时 |
 |---|---|---|---|---|---|
-| **最接近的** | CMake + Ninja | CMake modules、xmake rules | vcpkg、Conan | rustup、nvm | conda、Nix |
+| **最接近的工具** | CMake + Ninja | CMake modules、xmake rules | vcpkg、Conan | rustup、nvm | conda、Nix |
 
 > [!NOTE]
-> **早期版本** — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。
+> **早期版本**：mcpp 仍在积极开发中，接口与行为可能在后续版本中调整。
 > 欢迎对现代 C++ 模块化构建工具感兴趣的开发者[参与贡献](#参与贡献)。
-> 问题 / 反馈 / 想法欢迎在 [issues](https://github.com/mcpp-community/mcpp/issues) 留言。
+> 问题、反馈与想法可以在 [issues](https://github.com/mcpp-community/mcpp/issues) 中提出。
 
 ## 快速开始
 
@@ -54,7 +54,7 @@ xlings install mcpp -y
 ```
 
 <details>
-<summary>还没有 xlings？点击查看安装命令</summary>
+<summary>尚未安装 xlings：点击查看安装命令</summary>
 
 **Linux / macOS**
 ```bash
@@ -66,20 +66,18 @@ curl -fsSL https://d2learn.org/xlings-install.sh | bash
 irm https://d2learn.org/xlings-install.ps1.txt | iex
 ```
 
-> xlings 详情 → [xlings.d2learn.org](https://xlings.d2learn.org)
+> xlings 的更多信息见 [xlings.d2learn.org](https://xlings.d2learn.org)
 
 </details>
 
 <details>
-<summary>可选 —— 短命令（<code>mp</code>、<code>mbuild</code>、<code>mrun</code> …）</summary>
+<summary>可选：短命令（<code>mp</code>、<code>mbuild</code>、<code>mrun</code> 等）</summary>
 
 ```bash
 xlings install mcpp-short-cmd -y
 ```
 
-装 30 个短命令，`mcpp build` 就是 `mbuild`。命名规则：除最后一个词外每词取首字母，
-最后一个词写全 —— `mcpp self doctor` → `msdoctor`；`mp` 就是裸 `mcpp`。
-它们指向 `mcpp` 这个 shim 而非固定路径，所以 `xlings use mcpp <ver>` 也会一起切换。
+该包注册 30 个 shim，`mcpp build` 即可写成 `mbuild`。命名规则：除最后一个词外，每个词取首字母，最后一个词保留全拼，例如 `mcpp self doctor` → `msdoctor`。`mp` 即不带子命令的 `mcpp`。这些短命令指向 `mcpp` 这个 shim，而不是某个固定的二进制，因此 `xlings use mcpp <ver>` 会同时切换它们。
 
 | 短命令 | 展开 | 短命令 | 展开 |
 | --- | --- | --- | --- |
@@ -101,44 +99,38 @@ xlings install mcpp-short-cmd -y
 
 </details>
 
-**其他方式**
+**其他安装方式**
 
 <details>
-<summary><b>方式 1</b> — 一键安装脚本（Linux x86_64/aarch64、macOS ARM64）</summary>
+<summary><b>方式 1</b>：一键安装脚本（Linux x86_64/aarch64、macOS ARM64）</summary>
 
 ```bash
 curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
 ```
 
-该脚本不支持 Windows；请使用上方 PowerShell 的 xlings 安装方式。它会安装到
-`~/.mcpp/`，并自动加入 shell PATH。删除 `~/.mcpp` 即可干净卸载。
+该脚本不支持 Windows，Windows 请使用上文 PowerShell 的 xlings 安装方式。脚本安装到 `~/.mcpp/`，并把它加入 shell 的 PATH。删除 `~/.mcpp` 即完成卸载。
 
 </details>
 
 <details>
-<summary><b>方式 2</b> — Homebrew（macOS / Linux）</summary>
+<summary><b>方式 2</b>：Homebrew（macOS / Linux）</summary>
 
 ```bash
 brew install mcpp-community/mcpp/mcpp-m
 ```
 
-一条命令即可，会自动 tap [`mcpp-community/homebrew-mcpp`](https://github.com/mcpp-community/homebrew-mcpp)
-并安装同一份预编译 release 二进制。macOS 需要 Apple 芯片 + macOS 14；
-每个用户的数据仍在各自的 `~/.mcpp/`。
+这一条命令会 tap [`mcpp-community/homebrew-mcpp`](https://github.com/mcpp-community/homebrew-mcpp)，并安装同一份预编译的 release 二进制。macOS 要求 Apple 芯片与 macOS 14；每个用户的数据仍在各自的 `~/.mcpp/` 中。
 
-Homebrew 上 `mcpp` 属于一个无关的 C 预处理器，所以公式名是 `mcpp-m`，
-装出来的命令仍然是 `mcpp`。
+Homebrew 中的 `mcpp` 是一个无关的 C 预处理器，因此 formula 名为 `mcpp-m`，安装出的命令仍是 `mcpp`。
 
-**Homebrew 6 对第三方 tap 加了信任门。** 上面那条全限定命令会被当作显式意图、
-可以直接用；但**其它任何拼写**——短名 `brew install mcpp-m`、`mcpp` 别名、
-以及之后的升级——都会被拒：
+**Homebrew 6 对第三方 tap 设置了信任门。** 上面的全限定命令被视为显式意图，可以直接使用；其他写法，包括短名 `brew install mcpp-m`、`mcpp` 别名以及之后的升级，都会被拒绝：
 
 ```
 Refusing to load formula mcpp-community/mcpp/mcpp-m from untrusted tap
 mcpp-community/mcpp.
 ```
 
-信任这个 tap 一次，它们就都能用了：
+信任该 tap 一次之后，上述写法均可使用：
 
 ```bash
 brew trust mcpp-community/mcpp
@@ -147,35 +139,42 @@ brew trust mcpp-community/mcpp
 </details>
 
 <details>
-<summary><b>方式 3</b> — Arch Linux（AUR）</summary>
+<summary><b>方式 3</b>：Arch Linux（AUR）</summary>
 
 ```bash
 yay -S mcpp-bin      # 预编译 release 二进制
 yay -S mcpp-m        # 或源码构建（用 mcpp-bin 自举）
 ```
 
-系统级安装 `mcpp` 命令，每个用户的数据仍在各自的 `~/.mcpp/`。
-Arch 上 `mcpp` 这个名字属于一个无关的 C 预处理器，所以包名是
-`mcpp-bin` / `mcpp-m`（详见 [`scripts/aur/`](scripts/aur/)）。
-稳定 release 的自动对账只管理 `mcpp-bin`；`mcpp-m` 与 `mcpp-git` 仍由人工维护，
-可能有意滞后。
+`mcpp` 命令安装到系统级位置，每个用户的数据仍在各自的 `~/.mcpp/` 中。Arch 上 `mcpp` 这个名字属于一个无关的 C 预处理器，因此包名为 `mcpp-bin` / `mcpp-m`（见 [`scripts/aur/`](scripts/aur/)）。稳定版 release 的自动同步只管理 `mcpp-bin`；`mcpp-m` 与 `mcpp-git` 仍由人工维护，版本可能有意滞后。
 
 </details>
 
 <details>
-<summary><b>方式 4</b> — 让 AI 助手帮你安装</summary>
+<summary><b>方式 4</b>：pip（PyPI）</summary>
 
-将以下提示词复制给你的 AI 编码助手（Claude Code / Cursor / Copilot 等）：
+```bash
+pip install mcpp-bin
+```
+
+`mcpp` 命令安装到当前的 Python 环境中；使用 `pipx install mcpp-bin` 则为它单独创建一个环境。wheel 中是同一份预编译 release 二进制，支持 Linux x86_64 / aarch64、Apple 芯片上的 macOS 14+ 与 Windows x86_64。每个用户的数据仍在各自的 `~/.mcpp/` 中，不在 Python 环境内。PyPI 上 `mcpp` 这个名字属于一个无关的项目，因此包名为 `mcpp-bin`（见 [`scripts/pypi/`](scripts/pypi/)）。
+
+</details>
+
+<details>
+<summary><b>方式 5</b>：由 AI 助手安装</summary>
+
+将以下提示词发给 AI 编码助手（Claude Code、Cursor、Copilot 等）：
 
 ```
 阅读 https://github.com/mcpp-community/mcpp 的 README，
-帮我安装 mcpp 并创建一个 C++23 模块项目，构建并运行。
-项目的 .agents/skills/mcpp-usage/SKILL.md 有详细的使用指南。
+安装 mcpp，创建一个 C++23 模块项目，然后构建并运行它。
+仓库中的 .agents/skills/mcpp-usage/SKILL.md 提供了详细的使用指南。
 ```
 
 </details>
 
-### 创建项目 & 构建运行
+### 创建、构建与运行项目
 
 ```bash
 mcpp new hello
@@ -184,7 +183,7 @@ mcpp build
 mcpp run
 ```
 
-> 注：首次构建会初始化环境并获取工具链，可能需要一些时间。
+> 首次构建会初始化环境并获取工具链，耗时较长。
 
 ### 项目结构
 
@@ -206,12 +205,11 @@ description = "A modular C++23 package"
 license     = "Apache-2.0"
 ```
 
-内置脚手架采用约定优于配置，不写 `[targets.hello]`：`src/main.cpp` 会推断出
-binary target，`mcpp test` 会自动发现 `tests/test_smoke.cpp`。
+内置脚手架依赖约定，不生成 `[targets.hello]`：mcpp 由 `src/main.cpp` 推断出 binary target，`mcpp test` 自动发现 `tests/test_smoke.cpp`。
 
 ### 使用模块化库
 
-在 `mcpp.toml` 中添加两行依赖，即可引用 [mcpplibs](https://github.com/mcpplibs) 社区模块化库：
+在 `mcpp.toml` 中添加两行依赖，即可引入 [mcpplibs](https://github.com/mcpplibs) 社区的模块化库：
 
 ```toml
 [dependencies]
@@ -224,20 +222,20 @@ cmdline = "0.0.2"
 import mcpplibs.cmdline;
 ```
 
-> 更多依赖配置方式（版本约束、命名空间、Git 引用、本地路径等）参见 [mcpp.toml 指南 — 依赖管理](docs/zh/04-mcpp-toml.md)。
+> 其他依赖写法（版本约束、命名空间、Git 引用、本地路径等）见 [mcpp.toml 指南 —— 依赖管理](docs/zh/04-mcpp-toml.md)。
 
 ## 功能概览
 
 <details>
 <summary><b>构建系统</b></summary>
 
-- C++20/23/26 模块原生支持（接口单元、实现单元、模块分区），另有 `c++latest` / `c++fly` 实验模式
+- 原生支持 C++20/23/26 模块（接口单元、实现单元、模块分区），另有 `c++latest` / `c++fly` 两种实验模式
 - `import std` / `import std.compat` 全自动预编译与缓存
 - 三层增量优化：前端脏检查 + 逐文件 P1689 dyndep + BMI copy-if-different restat
-- 指纹化 BMI 缓存：按编译器/标志/标准库哈希，跨项目共享
+- 带指纹的 BMI 缓存：按编译器、编译标志与标准库计算哈希，跨项目共享
 - Ninja 后端：自动生成 build.ninja，并行编译
-- compile_commands.json 自动生成（clangd / ccls 即用）；`mcpp build --configure-only` 可在编译普通源码之前先刷新它
-- C 语言一等支持：`.c` 文件自动检测，混合 C/C++ 项目
+- 自动生成 `compile_commands.json`（可直接供 clangd / ccls 使用）；`mcpp build --configure-only` 可在编译普通源码之前刷新它
+- C 语言一等支持：自动识别 `.c` 文件，支持 C/C++ 混合项目
 - 用户自定义 cflags / cxxflags / ldflags / c_standard
 
 </details>
@@ -245,35 +243,35 @@ import mcpplibs.cmdline;
 <details>
 <summary><b>工具链管理</b></summary>
 
-- 内置 GCC 16.1.0 + LLVM/Clang 20.1.7，一键安装
-- 首次运行按宿主选择：Linux x86_64 使用原生 glibc GCC，其他 Linux 架构使用 musl GCC，macOS 与具备可用 MSVC 的 Windows 使用 LLVM，裸 Windows 使用 MinGW-w64 GCC
+- 内置 GCC 16.1.0 与 LLVM/Clang 20.1.7，一条命令安装
+- 按宿主选择默认值：Linux x86_64 使用原生 glibc GCC，其他 Linux 架构使用 musl GCC，macOS 以及有可用 MSVC 的 Windows 使用 LLVM，裸 Windows 使用 MinGW-w64 GCC
 - 多版本共存：`mcpp toolchain install gcc 16` / `mcpp toolchain install llvm 20`
-- 隔离沙盒：所有工具链在 `~/.mcpp/registry/`，不影响系统
-- 按平台指定：`linux = "gcc@16"`, `macos = "llvm@20"`
-- GCC + Clang 编译管线平权（`BmiTraits` 抽象层驱动）
+- 隔离沙盒：所有工具链位于 `~/.mcpp/registry/`，不改动系统
+- 按平台指定：`linux = "gcc@16"`、`macos = "llvm@20"`
+- GCC 与 Clang 的编译管线对等（由 `BmiTraits` 抽象层驱动）
 
 </details>
 
 <details>
-<summary><b>交叉构建、裸机与设备</b></summary>
+<summary><b>交叉编译、裸机与设备</b></summary>
 
-- `mcpp build --target <triple>` — 一个开关;该目标所需的工具链载荷会自动解析并安装
-- 从 `x86_64-linux-gnu` 到 Cortex-M、Cortex-A 与 RISC-V 裸机,完整的表见[平台支持](#平台支持)
-- freestanding 目标不带操作系统:C 库、启动代码、内存布局与模拟器随板级支持包走,而不随 mcpp 走
-- runner 用来触及构建机器上跑不了的产物 —— `mcpp run --runner flash`、`--list-runners`、`mcpp why runners`
-- `mcpp new --template riscv-virt-rt` — 由包自带的板级模板,按名字实例化
-- 基于 openkal 的交叉编译:一个可移植程序,为内核接口与 C 库都来自包的目标构建
+- `mcpp build --target <triple>`：一个选项；该目标所需的工具链 payload 自动解析并安装
+- 目标从 `x86_64-linux-gnu` 覆盖到 Cortex-M、Cortex-A 与 RISC-V 裸机，完整列表见[平台支持](#平台支持)
+- freestanding 目标不带操作系统：C 库、启动代码、内存布局与模拟器由板级支持包提供，而不由 mcpp 提供
+- runner 用于运行构建机上无法运行的产物：`mcpp run --runner flash`、`--list-runners`、`mcpp why runners`
+- `mcpp new --template riscv-virt-rt`：按名字实例化某个包自带的板级模板
+- 基于 openkal 的交叉编译：一个可移植程序，可以为内核接口与 C 库均由包提供的目标构建
 
 </details>
 
 <details>
-<summary><b>异构硬件构建与加速器</b></summary>
+<summary><b>异构构建与加速器</b></summary>
 
-- `[build] accel = "cuda12.9+{sm_89}, vulkan1.2"` — 一次构建可以点名一个或多个设备后端,该构建里 `cfg(accelerator = "cuda")` 为真
-- 目前有规则包的编程模型有五个:CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C
-- 设备翻译单元由它自己的编译器编译,产物进入普通链接;主机与设备之间的边界是生成的,不是写两遍的
-- 带约束的 glob 用来挑出设备源码:`{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`
-- 引擎里不含任何厂商名,因此第六个后端是一个包,而不是一次引擎改动
+- `[build] accel = "cuda12.9+{sm_89}, vulkan1.2"`：一次构建可以指定一个或多个设备后端，该构建中 `cfg(accelerator = "cuda")` 为真
+- 目前有规则包的编程模型共五个：CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C
+- 设备翻译单元由各自的编译器编译，产物进入普通链接；主机与设备之间的边界代码由 mcpp 生成，不需要写两遍
+- 用带约束的 glob 选择设备源码：`{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`
+- 引擎中不包含任何厂商名，因此第六个后端是一个包，而不是一次引擎改动
 
 </details>
 
@@ -283,9 +281,9 @@ import mcpplibs.cmdline;
 - SemVer 约束解析：`^`、`~`、范围、精确版本
 - 三级解析：约束合并 → 多版本 mangling 回退 → 精确匹配
 - 锁文件 mcpp.lock（v2 格式：索引快照 + 命名空间）
-- 命名空间系统：`[dependencies.myteam] foo = "1.0"`
+- 命名空间：`[dependencies.myteam] foo = "1.0"`
 - 自定义包索引：`[indices] acme = "git@..."` / `{ path = "..." }`
-- 项目级索引隔离（`.mcpp/` 目录，不污染全局）
+- 项目级索引隔离（`.mcpp/` 目录，不影响全局状态）
 - 依赖来源：索引 / Git / 本地路径
 
 </details>
@@ -294,55 +292,53 @@ import mcpplibs.cmdline;
 <summary><b>工作空间</b></summary>
 
 - `[workspace] members = ["libs/*", "apps/*"]`
-- 统一锁文件 + 统一 target 目录
+- 统一的锁文件与 target 目录
 - 版本集中管理：`[workspace.dependencies]` + `.workspace = true`
 - 选择性构建：`mcpp build -p member-name`
-- 配置继承：工具链、构建标志、索引从根级联到成员
+- 配置继承：工具链、构建标志与索引从根级联到各成员
 
 </details>
 
 <details>
 <summary><b>打包与发布</b></summary>
 
-- `mcpp pack`：四种 Linux 发布模式 — system / vendored（默认）/ self-contained / static；`bundle-project` 与 `bundle-all` 仍是兼容别名
-- musl 全静态二进制：单文件可分发，无 glibc 依赖（匹配的 Linux x86_64 或 aarch64 target）
-- `mcpp publish`：生成 xpkg.lua + 发布到包索引
-- 自动 patchelf 修正 RPATH（Linux）
+- `mcpp pack`：四种 Linux 发布模式，即 system / vendored（默认）/ self-contained / static；`bundle-project` 与 `bundle-all` 保留为兼容别名
+- musl 全静态二进制：单文件分发，不依赖 glibc（目标须为对应架构的 Linux x86_64 或 aarch64）
+- `mcpp publish`：生成 xpkg.lua 并发布到包索引
+- 通过 patchelf 自动修正 RPATH（Linux）
 
 </details>
 
 <details>
 <summary><b>扩展构建</b></summary>
 
-- `build.mcpp` — 为 mcpp 没有现成规则的那一步写的构建程序,说的是一套带版本号的指令协议,而不是靠猜
-- `mcpp::action` 用显式的输入与输出声明一份工作,于是生成物参与增量图,而不是待在图外
-- 规则包把那一步带给别的项目:包声明一个 rule 模块,消费者以 feature 的形式选中它
-- 载荷、运行时适配包与板级支持包都是普通的包 —— 一个工具、一个驱动或一块板子,由安装库的那个解析器安装
+- `build.mcpp`：为 mcpp 没有现成规则的构建步骤编写的构建程序，它与 mcpp 通过一套带版本号的指令协议通信，而不是由 mcpp 猜测其行为
+- `mcpp::action` 以显式的输入与输出声明一项工作，生成的文件因此进入增量构建图，而不是游离在图外
+- 规则包把这类步骤提供给其他项目：包声明一个 rule 模块，使用方以 feature 的形式选用它
+- payload、运行时适配包与板级支持包都是普通的包：工具、驱动或开发板，都由安装库的同一个解析器安装
 
 </details>
 
 <details>
 <summary><b>开发体验</b></summary>
 
-- `mcpp new` — 创建模块化项目；`--template [ns.]name[@version][:tname]` 与 `mcpp add` 使用同一精确身份风格并选择**包自带模板**。只有一个模板时即使未写 `default = true` 也自动成为默认；歧义时用 `--list-templates [ns.]name[@version]` 列举
-- `mcpp run [-- args]` — 构建并运行
-- `mcpp test [pattern] [-- args]` — 自动发现并运行测试(按名字过滤;`--list`、`--timeout <s>`、`--message-format json`)
-- `mcpp search` — 搜索包索引
-- `mcpp add / remove / update` — 依赖管理
-- 命令行上的 profile 与 feature:`--release` / `--profile <name>`(`build`、`run`),`--features <list>`(`build`、`run`、`test`)
-- `mcpp why [toolchain|runtime|deps|runners]` — 解释已解析的构建决策;`--format json` 供程序读取
-- `mcpp emit sbom` — 为已记录的那次解析产出一份 CycloneDX 格式的 SBOM
-- `mcpp --offline` / `MCPP_OFFLINE=1` — 仅使用已存在的本地状态
-- `mcpp explain E0001` — 错误码详细解释
-- `mcpp self doctor` — 环境自诊断
+- `mcpp new`：创建模块化项目；`--template [ns.]name[@version][:tname]` 与 `mcpp add` 使用同一种精确身份写法，选用**包自带的模板**。包中只有一个模板时，即使未写 `default = true`，它也是默认模板；存在歧义时用 `--list-templates [ns.]name[@version]` 列出可选模板
+- `mcpp run [-- args]`：构建并运行
+- `mcpp test [pattern] [-- args]`：自动发现并运行测试（按名字过滤；`--list`、`--timeout <s>`、`--message-format json`）
+- `mcpp search`：搜索包索引
+- `mcpp add / remove / update`：依赖管理
+- 命令行上的 profile 与 feature：`build` 与 `run` 接受 `--release` / `--profile <name>`，`build`、`run` 与 `test` 接受 `--features <list>`
+- `mcpp why [toolchain|runtime|deps|runners]`：解释已解析的构建决策；`--format json` 供程序读取
+- `mcpp emit sbom`：为刚记录的那次解析生成 CycloneDX 格式的物料清单（SBOM）
+- `mcpp --offline` / `MCPP_OFFLINE=1`：只使用本地已有的状态
+- `mcpp explain E0001`：错误码的详细解释
+- `mcpp self doctor`：环境自诊断
 
 </details>
 
 ## 性能对比
 
-用**四个构建引擎**编译 **mcpp 自己** —— 锁定的工作负载有 137 个模块接口单元、
-57k 行,每一个都 `import std;` —— 并且**给它们同一个编译器二进制**。每格是 **3 轮的中位数**,以及
-相对 cmake 的倍率。所有列出自**同一次跑**。
+测量对象是构建 **mcpp 自身**：锁定的工作负载有 137 个模块接口单元、57k 行代码，每个单元都 `import std;`。四个构建引擎使用**同一个编译器二进制**。每格数据是 **3 次采样的中位数**，以及相对 cmake 的倍率。所有列来自**同一次运行**。
 
 <!-- columns: mcpp=mcpp@2026.8.13.1; mcpp +优化=mcpp@2026.8.13.1+schedule=on; mcpp (旧版)=mcpp@2026.8.11.3; cmake=cmake; xmake=xmake -->
 | 场景 | `mcpp` | `mcpp +优化` | `mcpp (旧版)` | `cmake` | `xmake` |
@@ -353,168 +349,137 @@ import mcpplibs.cmdline;
 | `edit-body` | 80.87s · 1.1x | **29.83s · 2.9x** | 81.19s · 1.1x | 85.30s · 1.0x | 84.33s · 1.0x |
 | `edit-comment` | **0.40s · 207.0x** | **0.40s · 207.0x** | 79.11s · 1.1x | 83.21s · 1.0x | 82.15s · 1.0x |
 
-<sub>`cold` 还没编过 · `noop` 什么都没改 · `touch-hub` 只碰 mtime,内容不变 · `edit-body` 真的改了一个函数体 · `edit-comment` 在 hub 接口里加一行注释。<br>
+<sub>`cold` 尚未构建过 · `noop` 没有任何改动 · `touch-hub` 只更新 mtime，内容不变 · `edit-body` 在函数体内做一次真实修改 · `edit-comment` 在 hub 接口中添加一行注释。<br>
 <br>
-`mcpp` = mcpp@2026.8.13.1,被测的这一版 · `mcpp +优化` = **和 `mcpp` 同一个二进制**,开了 opt-in 的 `[build] bmi_schedule = "on"`(默认关闭) · `mcpp (旧版)` = mcpp@2026.8.11.3,上一个已发布版。<br>
+`mcpp` = mcpp@2026.8.13.1，即被测版本 · `mcpp +优化` = **与 `mcpp` 同一个二进制**，开启 opt-in 的 `[build] bmi_schedule = "on"`（默认关闭）· `mcpp (旧版)` = mcpp@2026.8.11.3，即上一个已发布版本。<br>
 Linux x86_64 · i9-13900K · gcc 16.1.0 · n=3 · 锁定的工作负载 `a749e9f` ·
-cmake 4.4.2 / xmake 3.1.0 · 所有大于 1s 的中位数 min/max 都在 ±4% 以内 ·
-数据:[`standard-20260814-linux-x86_64`](bench/results/standard-20260814-linux-x86_64/)。</sub>
-
-* **`touch-hub` 与 `edit-comment` 两行由级联抑制决定。**
-  cmake 与 xmake 按时间戳判断,重编全部下游单元;mcpp 将编译器刚产出的 BMI 与上
-  一份比较,接口未变则不触发级联。这是默认行为,无需任何配置。`mcpp (旧版)` 一列
-  测得上一个发布版为 81.72s,与 cmake 同量级,因此该效果在本版本中才生效。
-* **`edit-body` 是对照行,mcpp 在这一行有意不快。** 扰动往接口单元里插入一条语句,
-  GCC 记录的声明位置随之移动,BMI 因而改变,每一个导入者都欠一次重建 —— 在这一行
-  跑得快的引擎,漏掉的是它欠下的工作。一次改动欠不欠级联取决于函数体写在哪里:
-  原地等长的修改,或者写在独立 `.cpp` 里的函数体,都不欠级联,落在约 200x 的那一档。
-  实测见
-  [`.agents/docs/2026-08-15-module-edit-granularity.md`](.agents/docs/2026-08-15-module-edit-granularity.md)。
-* **`bmi_schedule` 为 opt-in,默认关闭**(`auto` 解析为 off)。它将代码生成移出关键
-  路径,因此只在级联确实欠着时才有收益 —— `cold` 86.69s → 35.73s、`edit-body`
-  80.87s → 29.83s,而在 mcpp 本已跳过级联的两行上没有收益。调度错误的表现是静默
-  失效而非报错,因此不以单台机器的证据变更默认值。
-
-**[方法、锁定的版本、完整数据 → `bench/README.zh-CN.md`](bench/README.zh-CN.md)** ·
+cmake 4.4.2 / xmake 3.1.0 · 所有大于 1s 的中位数，其 min/max 与中位数相差不超过 4% ·
+数据：[`standard-20260814-linux-x86_64`](bench/results/standard-20260814-linux-x86_64/)。</sub>
+
+* **`touch-hub` 与 `edit-comment` 两行的差异来自级联抑制。**
+  cmake 与 xmake 按时间戳判断，重新编译全部下游单元；mcpp 把编译器刚产出的 BMI 与上一份比较，接口未变时跳过级联。这是默认行为，不需要配置。`mcpp (旧版)` 一列测得上一个发布版为 81.72s，与 cmake 处于同一量级，因此这一效果是本版本新增的。
+* **`edit-body` 是对照行，mcpp 在这一行有意不快。**
+  扰动在接口单元中插入一条语句，GCC 记录的源码位置随之移动，BMI 因此改变，每个导入者都需要重新构建。在这一行上快的引擎，是跳过了本应完成的工作。一次修改是否引起级联，取决于函数体写在哪里：原地等长的修改，或写在独立 `.cpp` 中的函数体，都不引起级联，结果落在约 200x 的那一档。实测见 [`.agents/docs/2026-08-15-module-edit-granularity.md`](.agents/docs/2026-08-15-module-edit-granularity.md)。
+* **`bmi_schedule` 为 opt-in，默认关闭**（`auto` 解析为 off）。
+  它把代码生成移出关键路径，因此只在确实需要级联时才有收益：`cold` 86.69s → 35.73s，`edit-body` 80.87s → 29.83s；在 mcpp 本已跳过级联的两行上没有收益。调度出错时的表现是静默失效而不是报错，因此默认值不会依据单台机器的数据改变。
+
+**[方法、锁定的版本与完整数据 → `bench/README.zh-CN.md`](bench/README.zh-CN.md)** ·
 [English](bench/README.md)
 
 ## 平台支持
 
-mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family ∈ gcc | llvm | msvc),
-**目标** = 三段 triple `arch-os[-env]`。交叉编译只需 `mcpp build --target <triple>`——
-对应的工具链包会自动解析并安装。`mcpp toolchain list` 查看本机实时状态。
+mcpp 的身份模型有两条正交的轴：**工具链**是 `family@version`（family ∈ gcc | llvm | msvc），**目标**是三段式 triple `arch-os[-env]`。交叉编译只需 `mcpp build --target <triple>`，对应的工具链 payload 会自动解析并安装。`mcpp toolchain list` 显示本机的实时状态。
 
-**宿主**(mcpp 本身运行在哪):Linux x86_64 / aarch64、macOS arm64、Windows x86_64。
+**宿主**（mcpp 本身运行的平台）：Linux x86_64 / aarch64、macOS arm64、Windows x86_64。
 
-**目标**(`--target` 接受什么;表里的行与它们的档位取自
-`modules/toolchain-model/src/triple.cppm`,也就是 `mcpp toolchain list` 为本机
-报告的那一份):
+**目标**（`--target` 接受的值；表中的行及其档位取自 `modules/toolchain-model/src/triple.cppm`，`mcpp toolchain list` 为本机报告的也是这一份）：
 
 | Target | 约定工具链 | 档位 |
 |---|---|:---:|
-| `x86_64-linux-gnu`    | gcc(*Linux 默认*)或 llvm | verified |
-| `x86_64-linux-musl`   | gcc 16,全静态 | verified |
-| `aarch64-linux-musl`  | gcc 16,全静态——x86_64 交叉(qemu)或原生 | verified |
-| `x86_64-windows-gnu`  | gcc 16 MinGW-w64——Windows 原生,Linux 交叉(wine)(*无 Visual Studio 时的 Windows 默认*) | verified |
-| `x86_64-windows-msvc` | `msvc@system`(探测 VS/BuildTools)或 llvm ¹(*有 Visual Studio 时的 Windows 默认*) | verified |
-| `x86_64-windows-musl` | llvm 22——带 musl C 库的 PE,没有 gcc 能产出它;系统由依赖图供给 | preview |
-| `aarch64-macos`       | llvm(*macOS 默认*) | verified |
-| `riscv64-none-elf` · `riscv32-none-elf` | llvm 22——裸机,`xim:picolibc-riscv` ² | verified |
-| `thumbv6m-none-eabi` · `thumbv7m-none-eabi` | llvm 22——Cortex-M0/M0+/M1、Cortex-M3 ² | verified |
-| `thumbv7em-none-eabihf` · `thumbv8m.main-none-eabi` | llvm 22——Cortex-M4F/M7F 硬浮点、Cortex-M33/M55 软浮点 ² | verified |
-| `armv7a-none-eabi` · `armv7a-none-eabihf` | llvm 22——Cortex-A 32 位,第一条带 MMU 的行 ² | verified |
-| `aarch64-none-elf` · `x86_64-none-elf` | llvm 22——裸机,默认不带 C 库 ² | preview |
-| `thumbv7em-none-eabi` · `thumbv8m.base-none-eabi` · `thumbv8m.main-none-eabihf` | llvm 22——Cortex-M4/M7 软浮点、M23、M33F/M55F ² | preview |
+| `x86_64-linux-gnu`    | gcc（*Linux 默认*）或 llvm | verified |
+| `x86_64-linux-musl`   | gcc 16，全静态 | verified |
+| `aarch64-linux-musl`  | gcc 16，全静态；从 x86_64 交叉编译（qemu）或原生构建 | verified |
+| `x86_64-windows-gnu`  | gcc 16 MinGW-w64；Windows 上原生构建，Linux 上交叉编译（wine）（*无 Visual Studio 时的 Windows 默认*） | verified |
+| `x86_64-windows-msvc` | `msvc@system`（探测 VS/BuildTools）或 llvm ¹（*有 Visual Studio 时的 Windows 默认*） | verified |
+| `x86_64-windows-musl` | llvm 22；带 musl C 库的 PE，gcc 无法产出；系统部分由依赖图提供 | preview |
+| `aarch64-macos`       | llvm（*macOS 默认*） | verified |
+| `riscv64-none-elf` · `riscv32-none-elf` | llvm 22；裸机，`xim:picolibc-riscv` ² | verified |
+| `thumbv6m-none-eabi` · `thumbv7m-none-eabi` | llvm 22；Cortex-M0/M0+/M1、Cortex-M3 ² | verified |
+| `thumbv7em-none-eabihf` · `thumbv8m.main-none-eabi` | llvm 22；Cortex-M4F/M7F 硬浮点，Cortex-M33/M55 软浮点 ² | verified |
+| `armv7a-none-eabi` · `armv7a-none-eabihf` | llvm 22；Cortex-A 32 位，第一个带 MMU 的目标 ² | verified |
+| `aarch64-none-elf` · `x86_64-none-elf` | llvm 22；裸机，默认不带 C 库 ² | preview |
+| `thumbv7em-none-eabi` · `thumbv8m.base-none-eabi` · `thumbv8m.main-none-eabihf` | llvm 22；Cortex-M4/M7 软浮点、M23、M33F/M55F ² | preview |
 | `riscv64-linux-musl` · `aarch64-linux-gnu` · `x86_64-macos` | — | planned |
-| `wasm32-emscripten` | `emsdk@6.0.9` —— Emscripten 自带 sysroot 和它自己的 libc++ 模块面;`mcpp run` 用载荷声明的 `node`(`xim:node`)把模块跑起来,不取 PATH 上的 | verified |
-| `x86_64-linux-android` | `android-ndk@30.0.16248370` —— bionic 来自 NDK,一个载荷服务两个 ABI;在 API 24 的 x86_64 模拟器镜像上跑过 | verified |
-| `aarch64-linux-android` | 同一个载荷、同样的构建;在 qemu-user 上、配系统镜像自带的 bionic 跑过 —— 这是平台模拟器从 x86_64 宿主做不到的 | verified |
-| `aarch64-ios-sim` | llvm 22 加上机器自己的 iPhoneSimulator SDK,mcpp 定位而不安装它;经 `simctl-run` 在模拟器上跑过 ³ | verified |
-| `aarch64-ios` | 真机取同一种切分;产物命名 iOS 平台,而把它跑在一台设备上需要开发者自己拥有的签名 ³ | preview |
-| `x86_64-ios-sim` | 同一次构建;没有东西跑过它,因为模拟器跑宿主的架构,而被测的那台是 Apple 芯片 ³ | preview |
-
-`verified` 该行的镜像已被构建**并运行**过,qemu 与 wine 都算 · `preview` 可构建
-可链接,未记录过模拟器运行 · `planned` 已登记在词表中,尚未接线 —— 面向这类目标
-的构建会被拒绝,而不是被尝试。
-
-> Linux release 二进制为 x86_64 与 aarch64 的 musl 全静态构建
-> (`x86_64-linux-musl` 与 `aarch64-linux-musl`)。
-> 旧拼写——`x86_64-w64-mingw32`、`gcc@16.1.0-musl`、`mingw-cross@…`、`musl-gcc@…`——
-> 作为别名**永久接受**,归一到上表的 canonical 形式。
+| `wasm32-emscripten` | `emsdk@6.0.9`；Emscripten 自带 sysroot 与 libc++ 模块接口；`mcpp run` 使用 payload 声明的 `node`（`xim:node`）运行模块，不使用 PATH 上的 `node` | verified |
+| `x86_64-linux-android` | `android-ndk@30.0.16248370`；bionic 来自 NDK，一个 payload 服务两个 ABI；已在 API 24 的 x86_64 模拟器镜像上运行 | verified |
+| `aarch64-linux-android` | 同一个 payload、同样的构建；已在 qemu-user 上配合系统镜像自带的 bionic 运行，平台模拟器无法在 x86_64 宿主上做到这一点 | verified |
+| `aarch64-ios-sim` | llvm 22 加上本机的 iPhoneSimulator SDK（mcpp 定位该 SDK，不安装它）；已通过 `simctl-run` 在模拟器上运行 ³ | verified |
+| `aarch64-ios` | 真机采用同样的分工；产物标记为 iOS 平台，在设备上运行需要开发者自己的签名 ³ | preview |
+| `x86_64-ios-sim` | 同一次构建；尚未运行过，因为模拟器运行宿主的架构，而测量所用的机器是 Apple 芯片 ³ | preview |
+
+`verified`：该行的镜像已构建**并运行**过，qemu 与 wine 均计入 · `preview`：可以构建和链接，尚无模拟器运行记录 · `planned`：已在词表中登记，尚未接通。针对这类目标的构建会被拒绝，而不会被尝试。
+
+> Linux release 二进制是 x86_64 与 aarch64 的 musl 全静态构建（`x86_64-linux-musl` 与 `aarch64-linux-musl`）。
+> 旧写法（`x86_64-w64-mingw32`、`gcc@16.1.0-musl`、`mingw-cross@…`、`musl-gcc@…`）作为别名**永久接受**，并归一化为上表中的规范形式。
 >
-> ¹ Windows 上 llvm 打的是 MSVC ABI,因此依赖已安装的 **MSVC BuildTools 或
-> Visual Studio**(UCRT、Windows SDK、MSVC STL)。这件事你不需要自己安排:mcpp 首跑会
-> 探测是否有可用的 MSVC,探不到就默认走 `x86_64-windows-gnu`(winlibs MinGW-w64)——
-> 完全自包含、不需要 Visual Studio、`import std` 可用。无需安装或配置,裸 Windows 上
-> `mcpp new && mcpp build` 直接可用。而 `mcpp.toml` 里显式写的 `[toolchain]` 永远按你
-> 写的执行——mcpp 只修正自己选的默认值,不改你的。
+> ¹ Windows 上 llvm 使用 MSVC ABI，因此需要已安装的 **MSVC BuildTools 或 Visual Studio**（UCRT、Windows SDK、MSVC STL）。这一点无需手动处理：mcpp 首次运行时探测是否有可用的 MSVC，探测不到就默认使用 `x86_64-windows-gnu`（winlibs MinGW-w64）。该工具链完全自包含，不需要 Visual Studio，并支持 `import std`。在未做任何配置的 Windows 上，`mcpp new && mcpp build` 可直接使用。`mcpp.toml` 中显式写出的 `[toolchain]` 始终按原样生效：mcpp 只修正它自己选择的默认值，不改动用户的设置。
 >
-> ² 裸机的那些行不带操作系统:clang 与 lld 天生就是交叉编译器,因此任何能安装
-> LLVM 载荷的宿主都能产出这些目标。C 库、启动代码、内存布局与模拟器随板级支持包
-> 走,而不随 mcpp 走 —— 见
-> [40 — 裸机与 freestanding 目标](docs/zh/40-baremetal.md)。
+> ² 裸机各行不带操作系统。clang 与 lld 本身就是交叉编译器，因此任何能安装 LLVM payload 的宿主都能产出这些目标。C 库、启动代码、内存布局与模拟器由板级支持包提供，而不由 mcpp 提供，见 [40 —— 裸机与 freestanding 目标](docs/zh/40-baremetal.md)。
 >
-> ³ 三条 iOS 行需要一台 macOS 宿主,而编译器仍然是生态的:`xim:llvm` 能为一个 iOS
-> 部署目标产出 arm64 Mach-O。机器供给的是 SDK —— 它在 Xcode 里且不可再分发,所以
-> mcpp 通过 `xcrun` 定位它,与它一直以来定位 macOS SDK 的方式完全相同 —— 并在找不到
-> 时点名那个 SDK 拒绝。模拟器那次会话属于 `xim:apple-simulator-tools`。见
-> [20 —— 工具链管理](docs/zh/20-toolchains.md)。
+> ³ 三个 iOS 目标需要 macOS 宿主，编译器仍来自生态：`xim:llvm` 能为 iOS 部署目标产出 arm64 Mach-O。本机提供的是 SDK。SDK 位于 Xcode 中且不可再分发，因此 mcpp 通过 `xcrun` 定位它，方式与定位 macOS SDK 相同；找不到时，mcpp 报出该 SDK 的名字并拒绝构建。模拟器会话由 `xim:apple-simulator-tools` 提供。见 [20 —— 工具链管理](docs/zh/20-toolchains.md)。
 
 ## 文档
 
-[`docs/zh/`](docs/zh/README.md) 是手册。章节号的第一位说明它属于哪一部分;索引
-另有一份反向查表 —— 从读者眼前的一个 manifest 键或一条命令,查到拥有它的那一章。
+[`docs/zh/`](docs/zh/README.md) 是使用手册。章节号的第一位数字表示它所属的部分；索引另附一份反查表，可以从一个 manifest 键或一条命令查到负责它的章节。
 
-| 部分 | 从这里开始 |
+| 部分 | 入口章节 |
 |---|---|
 | `0x` 基础 | [01 快速开始](docs/zh/01-getting-started.md) · [04 mcpp.toml 工程文件指南](docs/zh/04-mcpp-toml.md) · [09 按场景选命令](docs/zh/09-commands-by-scenario.md) |
 | `1x` 发布 | [10 发布打包](docs/zh/10-pack-and-release.md) · [11 发布一个库到 mcpp-index](docs/zh/11-publishing-a-library.md) · [12 分发预编译库](docs/zh/12-binary-distribution.md) |
 | `2x` 工具链与目标 | [20 工具链管理](docs/zh/20-toolchains.md) · [21 目标三元组](docs/zh/21-the-target-triple.md) · [24 基于 openkal 的交叉构建](docs/zh/24-openkal-cross.md) |
-| `3x` 扩展 mcpp | [30 构建程序:`build.mcpp`](docs/zh/30-build-mcpp.md) · [31 编写规则包](docs/zh/31-authoring-a-rule-package.md) · [34 编写板级支持包](docs/zh/34-authoring-a-bsp.md) |
-| `4x` 设备与加速器 | [40 裸机与 freestanding 目标](docs/zh/40-baremetal.md) · [41 抵达一台设备](docs/zh/41-devices.md) · [42 异构硬件构建](docs/zh/42-heterogeneous-builds.md) |
-| `5x` 给程序的契约 | [50 机器可读输出](docs/zh/50-machine-output.md) · [51 受支持的版本与兼容性](docs/zh/51-supported-versions.md) · [规范](docs/specs/README.md) |
+| `3x` 扩展 mcpp | [30 构建程序：`build.mcpp`](docs/zh/30-build-mcpp.md) · [31 编写规则包](docs/zh/31-authoring-a-rule-package.md) · [34 编写板级支持包](docs/zh/34-authoring-a-bsp.md) |
+| `4x` 设备与加速器 | [40 裸机与 freestanding 目标](docs/zh/40-baremetal.md) · [41 在设备上运行](docs/zh/41-devices.md) · [42 异构硬件构建](docs/zh/42-heterogeneous-builds.md) |
+| `5x` 面向程序的契约 | [50 机器可读输出](docs/zh/50-machine-output.md) · [51 受支持的版本与兼容性](docs/zh/51-supported-versions.md) · [规范](docs/specs/README.md) |
 | `9x` mcpp 自身 | [90 从源码构建与参与贡献](docs/zh/90-build-from-source.md) · [92 发布 mcpp](docs/zh/92-release.md) |
 
-[`examples/`](examples/) 下的每一个目录都是一个能构建的工程,
-[03 — 示例项目](docs/zh/03-examples.md) 说明哪一个教什么。任意命令的完整选项
-可通过 `mcpp <cmd> --help` 查阅。
+[`examples/`](examples/) 下的每个目录都是一个可以构建的项目，[03 —— 示例项目](docs/zh/03-examples.md) 说明每个示例演示什么。任意命令的完整选项可通过 `mcpp <cmd> --help` 查看。
 
-**AI 辅助学习**：你可以将以下提示词发给 AI 编码助手，让它帮你快速了解 mcpp：
+**AI 辅助学习**：将以下提示词发给 AI 编码助手，可以快速了解 mcpp：
 
 ```
 阅读 https://github.com/mcpp-community/mcpp 仓库的
 .agents/skills/mcpp-usage/SKILL.md 和 docs/ 目录下的文档，
-告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。
+说明如何用 mcpp 创建一个带依赖的 C++23 模块项目。
 ```
 
-## 谁在使用 mcpp
+## 使用 mcpp 的项目
 
-用 mcpp 构建的真实项目 —— 可直接 `import` 的 C++23 模块,以及它所依赖的工具链:
+以下是用 mcpp 构建的实际项目，包括可直接 `import` 的 C++23 模块，以及 mcpp 所依赖的工具链底座：
 
 | 项目 | 说明 |
 | --- | --- |
-| [mcpp](https://github.com/mcpp-community/mcpp) | mcpp 自身 —— 由 C++23 模块写成,完全自举 |
-| [xlings](https://github.com/openxlings/xlings) | mcpp 依赖的工具链与包管理底座 |
-| [tinyhttps](https://github.com/mcpplibs/tinyhttps) | 极简 C++23 HTTP/HTTPS 客户端,支持 SSE 流式 |
-| [llmapi](https://github.com/mcpplibs/llmapi) | 现代 C++ LLM API 客户端(OpenAI 兼容) |
-| [imgui-m](https://github.com/mcpplibs/imgui-m) | Dear ImGui 的 C++23 模块封装包 |
-| [cmdline](https://github.com/mcpplibs/cmdline) | 命令行解析库/框架(mcpp 自身在用) |
+| [mcpp](https://github.com/mcpp-community/mcpp) | mcpp 自身，由 C++23 模块写成，完全自举 |
+| [xlings](https://github.com/openxlings/xlings) | mcpp 所依赖的工具链与包管理底座 |
+| [tinyhttps](https://github.com/mcpplibs/tinyhttps) | 极简的 C++23 HTTP/HTTPS 客户端，支持 SSE 流式传输 |
+| [llmapi](https://github.com/mcpplibs/llmapi) | 现代 C++ LLM API 客户端（兼容 OpenAI） |
+| [imgui-m](https://github.com/mcpplibs/imgui-m) | 以 C++23 模块包形式提供的 Dear ImGui |
+| [cmdline](https://github.com/mcpplibs/cmdline) | 命令行解析库 / 框架（mcpp 自身使用） |
 
-更多模块化库 → [mcpplibs](https://github.com/mcpplibs) · 包索引 → [mcpp-index](https://mcpplibs.github.io/mcpp-index/)
+更多模块化库见 [mcpplibs](https://github.com/mcpplibs) · 包索引见 [mcpp-index](https://mcpplibs.github.io/mcpp-index/)
 
 ## 参与贡献
 
-欢迎通过 Issue 和 PR 参与项目开发。项目接受开发者使用 AI Agent 参与开发与贡献。
+欢迎通过 Issue 与 PR 参与开发。项目接受借助 AI Agent 完成的贡献。
 
 **基本流程**
 
-1. 创建 Issue — Bug 修复、新功能、优化等，先在 [issues](https://github.com/mcpp-community/mcpp/issues) 创建讨论
-2. 实现改动 — Fork 仓库，创建分支，并按改动范围验证（行为改动运行 `mcpp build` 与相关测试；纯文档改动复核示例和链接）
-3. 提交 PR — 使用 `gh pr create`，确保 CI 通过
-4. CI 必须通过 — CI 不通过的 PR 不会被合入
+1. 创建 Issue：Bug 修复、新功能或改进，先在 [issues](https://github.com/mcpp-community/mcpp/issues) 中发起讨论
+2. 实现改动：Fork 仓库并创建分支，按改动范围验证（行为改动运行 `mcpp build` 与相关测试；纯文档改动核对示例与链接）
+3. 提交 PR：使用 `gh pr create`，并确保 CI 通过
+4. CI 必须通过：CI 未通过的 PR 不会被合入
 
-**提交信息规范**：`feat:` / `fix:` / `test:` / `docs:` / `refactor:` 前缀
+**提交信息规范**：使用 `feat:` / `fix:` / `test:` / `docs:` / `refactor:` 前缀
 
-**AI Agent 贡献**：项目的 [`.agents/skills/mcpp-contributing/SKILL.md`](.agents/skills/mcpp-contributing/SKILL.md) 提供了完整的 Agent 贡献流程和项目结构说明。将以下提示词发给 AI 助手即可：
+**AI Agent 贡献**：仓库中的 [`.agents/skills/mcpp-contributing/SKILL.md`](.agents/skills/mcpp-contributing/SKILL.md) 给出完整的 Agent 贡献流程与项目结构说明。将以下提示词发给 AI 助手即可：
 
 ```
 阅读 https://github.com/mcpp-community/mcpp 仓库的
 .agents/skills/mcpp-contributing/SKILL.md，
-按照指南帮我给 mcpp 项目提交一个贡献。
+按照其中的指南为 mcpp 项目提交一个贡献。
 ```
 
 ## 社区 & 生态
 
-- [社区论坛](https://forum.d2learn.org/category/20) — 交流群 (Q: 1067245099)
-- [mcpp-index](https://mcpplibs.github.io/mcpp-index/) — 默认包索引
-- [mcpplibs](https://github.com/mcpplibs) — 模块化 C++ 库集合
+- [社区论坛](https://forum.d2learn.org/category/20)：交流群（QQ：1067245099）
+- [mcpp-index](https://mcpplibs.github.io/mcpp-index/)：默认包索引
+- [mcpplibs](https://github.com/mcpplibs)：模块化 C++ 库集合
 
 ### 致谢
 
-项目依赖和灵感来源：
+项目依赖与灵感来源：
 
-- [xlings](https://github.com/openxlings/xlings) — 工具链 / 包管理底座
-- [mcpplibs.cmdline](https://github.com/mcpplibs/cmdline) — CLI 框架
-- [ninja](https://github.com/ninja-build/ninja) — 底层构建引擎
-- [xmake](https://github.com/xmake-io/xmake) — 跨平台构建工具
-- [cargo](https://github.com/rust-lang/cargo) — Rust 包管理器
+- [xlings](https://github.com/openxlings/xlings)：工具链 / 包管理底座
+- [mcpplibs.cmdline](https://github.com/mcpplibs/cmdline)：CLI 框架
+- [ninja](https://github.com/ninja-build/ninja)：底层构建引擎
+- [xmake](https://github.com/xmake-io/xmake)：跨平台构建工具
+- [cargo](https://github.com/rust-lang/cargo)：Rust 包管理器
diff --git a/docs/92-release.md b/docs/92-release.md
index 22db5ba95..84bd3d144 100644
--- a/docs/92-release.md
+++ b/docs/92-release.md
@@ -89,7 +89,7 @@ The workflow then downloads the public release again, regenerates the manifest,
 and requires a byte-for-byte match. A workflow rerun accepts an existing
 manifest only when it is already byte-identical; it never overwrites different
 bytes for the same tag. Downstream release consumers (notably the `mcpp-bin`
-AUR reconciler) must consume this manifest instead of guessing completeness
+AUR reconciler and the `mcpp-bin` PyPI wheel builder in `scripts/pypi/`) must consume this manifest instead of guessing completeness
 from a moving workspace or from a subset of release assets.
 
 Two steps are **not** automated:
diff --git a/docs/zh/00-what-mcpp-is.md b/docs/zh/00-what-mcpp-is.md
index a572265b2..e6618a506 100644
--- a/docs/zh/00-what-mcpp-is.md
+++ b/docs/zh/00-what-mcpp-is.md
@@ -1,99 +1,99 @@
 # 00 —— mcpp 是什么
 
-## 背景:C++ 工程侧的工具现状
+## 背景：C++ 工程侧的工具现状
 
-一个 C++ 工程需要四样东西同时成立:一份构建描述、一组依赖、一个新到足以编译这份
-代码的编译器,以及一个能让产物真正运行起来的环境。C++ 没有任何一个工具同时负责
-这四样,它们由四类互不隶属的工具分别承担,而把它们对齐是工程自己的工作。
+一个 C++ 工程需要四样东西同时成立：一份构建描述、一组依赖、一个新到足以编译这份
+代码的编译器，以及一个能让产物真正运行起来的环境。C++ 没有任何一个工具同时负责
+这四样，它们由四类互不隶属的工具分别承担，而把它们对齐是工程自己的工作。
 
-CMake 是其中第一样的事实标准。事实标准陈述的是采用率,不是使用体验:CMake 不解析
-依赖、不安装编译器、也不描述运行期环境,而这三件恰好是新参与者在第一天遇到的。
-补齐它们意味着再引入一个包管理器、发行版的软件包,以及 README 里的一段环境说明
-—— 三套新的模型,而它们之间的对齐仍然落在工程身上。
+CMake 是其中第一样的事实标准。事实标准陈述的是采用率，不是使用体验：CMake 不解析
+依赖、不安装编译器、也不描述运行期环境，而这三件恰好是新参与者在第一天遇到的。
+补齐它们意味着再引入一个包管理器、发行版的软件包，以及 README 里的一段环境说明
+—— 三套新的模型，而它们之间的对齐仍然落在工程身上。
 
-最经常失效的是环境这一层,因为只有它没有任何东西在检查。构建描述会在配置阶段
-报错,包管理器会解析失败,而「机器上的库不是这份代码构建时所依据的那一份」在
-链接之前不产生任何信号,有时到程序运行时才产生。
+最经常失效的是环境这一层，因为只有它没有任何东西在检查。构建描述会在配置阶段
+报错，包管理器会解析失败，而「机器上的库不是这份代码构建时所依据的那一份」在
+链接之前不产生任何信号，有时到程序运行时才产生。
 
-模块给这个结构再加一条约束。C++20 的模块改变的是一个翻译单元的代价:接口只声明
-一次并被 import,而不是被每个需要它的文件从头文件里重新解析一遍;消费者看到的是
-作者导出的东西,不是头文件恰好 include 进来的一切。代价是这个语言特性由构建系统
-实现:构建要扫描源里的 `import`、据此给编译定序、缓存编译好的接口并正确地让它
-失效,而且要在一个新到具备这个特性的编译器上完成这些。`import std` 再加一条:
-标准库自己的模块必须先被构建出来,别的东西才能用它。
+模块给这个结构再加一条约束。C++20 的模块改变的是一个翻译单元的代价：接口只声明
+一次并被 import，而不是被每个需要它的文件从头文件里重新解析一遍；消费者看到的是
+作者导出的东西，不是头文件恰好 include 进来的一切。代价是这个语言特性由构建系统
+实现：构建要扫描源里的 `import`、据此给编译定序、缓存编译好的接口并正确地让它
+失效，而且要在一个新到具备这个特性的编译器上完成这些。`import std` 再加一条：
+标准库自己的模块必须先被构建出来，别的东西才能用它。
 
-于是采用模块的工程需要上述四层全部成立,而不是其中三层。这个落差是具体的。在写
-这一章的这台机器上:
+于是采用模块的工程需要上述四层全部成立，而不是其中三层。这个落差是具体的。在写
+这一章的这台机器上：
 
 ```console
 $ g++ --version
 g++ (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
 ```
 
-这个编译器编不了 `import std`。工程本身没有任何问题;是这台机器不是这个工程需要
+这个编译器编不了 `import std`。工程本身没有任何问题；是这台机器不是这个工程需要
 的那台机器。
 
 ## 这一现状的代价
 
-**对人,代价是一次搭建**,每台机器一次、每个新参与者一次:装一个更新的编译器、
-确定哪些构建旗标把模块打开、取得依赖,然后在链接失败时判断坏的是这三者中的哪一
-件。这个代价不随工程成熟而下降,它按人数和机器数重复。
+**对人，代价是一次搭建**，每台机器一次、每个新参与者一次：装一个更新的编译器、
+确定哪些构建旗标把模块打开、取得依赖，然后在链接失败时判断坏的是这三者中的哪一
+件。这个代价不随工程成熟而下降，它按人数和机器数重复。
 
-**对 agent,代价是上下文**,并且在写下第一行代码之前就消耗在三处:读构建描述以
-确定它究竟做了什么、重建它所假定的环境,以及顺着一个头文件穿过传递 include 去
-确定究竟声明了什么。
+**对 agent，代价是上下文**，并且在写下第一行代码之前就消耗在三处：读构建描述以
+确定它究竟做了什么、重建它所假定的环境，以及顺着一个头文件的传递 include 一路
+追下去，才能确定其中究竟声明了什么。
 
-模块消掉了第三处,因为接口是显式的,`import` 陈述了用到什么。mcpp 消掉另外两处,
+模块消掉了第三处，因为接口是显式的，`import` 陈述了用到什么。mcpp 消掉另外两处，
 并把第一处收敛为一条命令。
 
 ## mcpp 的组成
 
 ```
-mcpp = 通用构建系统
-     + 构建插件
-     + 包管理
-     + 工具链管理
-     + 环境与运行时(xlings)
+mcpp = build system
+     + build plugins
+     + package manager
+     + toolchain management
+     + the environment and runtime (xlings)
 ```
 
-多数 C++ 工程要把这五个部分从不同工具里拼起来,而上面那份搭建代价正是拼装本身的
-代价:构建文件假定机器上有某个编译器,包管理器假定一份不是它写的构建文件,而环境
+多数 C++ 工程要把这五个部分从不同工具里拼起来，而上面那份搭建代价正是拼装本身的
+代价：构建文件假定机器上有某个编译器，包管理器假定一份不是它写的构建文件，而环境
 是 README 里的一段话。
 
-mcpp 是一个程序,五个部分共用同一套模型。
+mcpp 是一个程序，五个部分共用同一套模型。
 
-对于已经在用相应工具的读者:
+对于已经在用相应工具的读者：
 
 | 组成部分 | 在 mcpp 中的形式 | 可对照的工具 |
 |---|---|---|
 | 通用构建系统 | `mcpp.toml`、模块图、ninja 后端 | CMake、Meson |
 | 构建插件 | `build.mcpp`、规则包 | `build.zig`、xmake rules |
 | 包管理 | `[dependencies]`、`mcpp.lock`、索引 | Conan、vcpkg |
-| 工具链管理 | 编译器作为被安装并钉住的载荷 | Zig 自带的工具链、rustup、手工安装 GCC / LLVM / MSVC |
+| 工具链管理 | 已安装并钉版本的编译器载荷 | Zig 自带的工具链、rustup、手工安装 GCC / LLVM / MSVC |
 | 环境与运行时 | `[xlings]`、载荷、运行期搜索路径 | Nix、conda |
 
-整体上最接近的两个类比是 Cargo 与 Zig,二者各对应同一个想法的一半。Cargo 是一个
-程序同时充当构建、包管理、锁文件与测试运行器,于是一个 Rust 工程克隆下来直接构建、
-没有前置步骤。Zig 把工具链随工具一起发布,并且默认支持交叉编译,于是编译器不是
+整体上最接近的两个类比是 Cargo 与 Zig，二者各对应同一个想法的一半。Cargo 是一个
+程序同时充当构建、包管理、锁文件与测试运行器，于是一个 Rust 工程克隆下来直接构建、
+没有前置步骤。Zig 把工具链随工具一起发布，并且默认支持交叉编译，于是编译器不是
 机器必须先具备的东西。
 
-mcpp 在 C++ 上是这个形状,外加二者都没有的一部分:环境层 —— 工程通过它声明构建
+mcpp 在 C++ 上是这个形状，外加二者都没有的一部分：环境层 —— 工程通过它声明构建
 所需的非编译器工具。
 
-**这张表为各部分定位,不宣称等价。** 表中每个工具在它自己的领域里做的都比 mcpp
-多,需要那种深度的工程使用它。
+**这张表为各部分定位，不宣称等价。** 表中每个工具在它自己的领域里做的都比 mcpp
+多，需要那种深度的工程使用它。
 
 ## 核心保证
 
-> **拿到任何一个 mcpp 工程,`mcpp build` 就能构建** —— 不需要自行安装编译器、
-> 配置环境,也不需要寻找依赖。
+> **拿到任何一个 mcpp 工程，`mcpp build` 就能构建** —— 不需要自行安装编译器、
+> 配置环境，也不需要寻找依赖。
 
-这里写下两条边界,以便这句话可以被依赖:面向设备的工程第一次构建仍会下载该设备的
-工具包;而这台机器服务不了的目标会被点名拒绝,不会被错误地构建出来。
+这里写下两条边界，以便这句话可以被依赖：面向设备的工程第一次构建仍会下载该设备的
+工具包；而这台机器服务不了的目标会被点名拒绝，不会被错误地构建出来。
 
 ## 最小示例
 
-还是那台机器,唯一的 C++ 编译器是上面那个 GCC 13。
+还是那台机器，唯一的 C++ 编译器是上面那个 GCC 13。
 
 ```console
 $ mcpp new hello
@@ -101,7 +101,7 @@ Created bin package 'hello' at /tmp/zero-demo/hello
 Next: cd hello && mcpp build && mcpp run  (or `mcpp test`)
 ```
 
-四个文件,manifest 五行:
+四个文件，manifest 五行：
 
 ```toml
 [package]
@@ -112,7 +112,7 @@ license     = "Apache-2.0"
 ```
 
 **没有声明编译器、没有声明语言档位、没有声明任何依赖。** 这就是一个读者在改动
-这个工程之前需要理解的全部。而源码用的正是这台机器的编译器不具备的那个特性:
+这个工程之前需要理解的全部。而源码用的正是这台机器的编译器不具备的那个特性：
 
 ```cpp
 import std;
@@ -133,17 +133,17 @@ Hello from hello!
 Built with import std + std::println on modular C++23.
 ```
 
-墙钟 1.25 秒,含首次运行。完成这次构建的编译器:
+墙钟 1.25 秒，含首次运行。完成这次构建的编译器：
 
 ```console
 $ mcpp self env
 default toolchain   = gcc@16.1.0
 ```
 
-mcpp 安装了 GCC 16 并使用它。宿主上没有任何东西被改动,而克隆这个工程的同事 ——
-或者 agent —— 得到的是同一个编译器,不是那台机器恰好自带的那个。
+mcpp 安装了 GCC 16 并使用它。宿主上没有任何东西被改动，而克隆这个工程的同事 ——
+或者 agent —— 得到的是同一个编译器，不是那台机器恰好自带的那个。
 
-**增加一个依赖是一行,不需要其他步骤:**
+**增加一个依赖是一行，不需要其他步骤：**
 
 ```toml
 [dependencies]
@@ -154,18 +154,18 @@ mcpp 安装了 GCC 16 并使用它。宿主上没有任何东西被改动,而克
 
 ## 适用范围
 
-mcpp 围绕 **C++20/23 模块与较新的语言特性**建立,它维护的生态由此而来,而不是
-来自一个泛化的目标:
+mcpp 围绕 **C++20/23 模块与较新的语言特性**建立，它维护的生态由此而来，而不是
+来自一个泛化的目标：
 
 | | |
 |---|---|
 | 模块化 C++ | `import std` 零配置、模块扫描、跨工程 BMI 缓存 |
 | 嵌入式与裸机 | freestanding 目标、板级支持包、从源码到一个可运行镜像只需一条命令 |
-| 异构计算与 GPU | CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C,每一条都是规则包而不是引擎特性 |
-| 图形 | 着色器作为构建的一部分被编译,并以模块到达 |
+| 异构计算与 GPU | CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C，每一条都是规则包而不是引擎特性 |
+| 图形 | 着色器随构建一起编译，并以模块到达 |
 | 内核与底层 | 零 libc 档、显式的链接模型、没有隐藏的宿主依赖 |
 
-不需要其中任何一项的工程,同样得到上述保证;需要其中之一的工程,不必离开这个
+不需要其中任何一项的工程，同样得到上述保证；需要其中之一的工程，不必离开这个
 工具去得到它。
 
 ## 阅读路径
@@ -176,5 +176,5 @@ mcpp 围绕 **C++20/23 模块与较新的语言特性**建立,它维护的生态
 | 判断 mcpp 是否适用于当前工作 | [02 —— 场景](02-scenarios.md) |
 | 阅读一个结构相近的工程 | [03 —— 示例项目](03-examples.md) |
 
-本章之后的一切都是参考:manifest 可以陈述什么、依赖怎样解析、目标怎样命名。本章
+本章之后的一切都是参考：manifest 可以陈述什么、依赖怎样解析、目标怎样命名。本章
 按设计不写任何字段与旗标。
diff --git a/docs/zh/01-getting-started.md b/docs/zh/01-getting-started.md
index 4ee3852a0..d081df364 100644
--- a/docs/zh/01-getting-started.md
+++ b/docs/zh/01-getting-started.md
@@ -1,37 +1,41 @@
 # 01 —— 快速开始
 
-**读者:**还什么都没装的新用户。
+**读者：** 还什么都没装的新用户。
 
-**本章回答的那一个问题:**从一台空机器开始,怎样把一个程序编译并运行起来。
+**本章回答的那一个问题：** 从一台空机器开始，怎样把一个程序编译并运行起来。
 
-**不在这里:**mcpp 有哪些部件 —— 那是 [00 —— mcpp 是什么](00-what-mcpp-is.md),
-本章假定它而不重复它;以及 manifest 可以写的每一个字段,那是
-[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md)。下一章:[03 —— 示例项目](03-examples.md)。
+**不在这里：** mcpp 有哪些部件——那是
+[00 —— mcpp 是什么](00-what-mcpp-is.md)，本章假定它而不重复它；以及
+manifest 可以写的每一个字段，那是
+[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md)。在此之后：
+[03 —— 示例项目](03-examples.md)。
 
-> 5 分钟完成 install → new → build → run → pack 全流程。
+> 5 分钟走完 install → new → build → run → pack 全流程。
 
 ## 安装
 
-支持的宿主为 Linux x86_64 / aarch64、macOS ARM64 与 Windows x86_64。GCC、xlings 以及
-其余构建依赖都由 mcpp 安装,一个都不需要预先具备。
+支持的宿主为 Linux x86_64 / aarch64、macOS ARM64 与 Windows x86_64。
+GCC、xlings 以及其余构建依赖都由 mcpp 安装，都不需要预先具备。
 
-**推荐方式是 [xlings](https://xlings.d2learn.org)**,它让 mcpp 与系统环境保持隔离:
+**推荐方式是 [xlings](https://xlings.d2learn.org)**，它让 mcpp 与系统
+环境保持隔离：
 
 ```bash
 xlings install mcpp -y
 ```
 
 <details>
-<summary>其它方式:独立安装脚本,以及首次运行会装什么</summary>
+<summary>其它方式：独立安装脚本，以及首次运行会装什么</summary>
 
-在 Linux x86_64/aarch64 或 macOS ARM64 上,有一个内置 xlings 的一键脚本,把一切装到
-`~/.mcpp/` 下。它不支持 Windows —— 那里的入口是 README 里的 PowerShell xlings 命令。
+在 Linux x86_64/aarch64 或 macOS ARM64 上，有一个内置 xlings 的一键脚本，
+把一切装到 `~/.mcpp/` 下。它不支持 Windows——那里的入口是 README 中的
+PowerShell xlings 命令。
 
 ```bash
 curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
 ```
 
-mcpp 首次运行时会把一条默认工具链装进 `~/.mcpp/`,按宿主选择:
+mcpp 首次运行时会把一条默认工具链装进 `~/.mcpp/`，按宿主选择：
 
 | 宿主 | 默认 |
 |---|---|
@@ -41,11 +45,12 @@ mcpp 首次运行时会把一条默认工具链装进 `~/.mcpp/`,按宿主选择
 | 有可用 MSVC 的 Windows | `llvm@20.1.7` |
 | 没有 MSVC 的 Windows | 面向 `x86_64-windows-gnu` 的 `gcc@16.1.0` |
 
-完整安装说明(含 Windows)见 [README 的「安装」小节](../../README.zh-CN.md#安装)。
+完整安装说明（含 Windows）见
+[README 的「安装」小节](../../README.zh-CN.md#安装)。
 
 </details>
 
-安装完成后,启动新的 shell 会话,然后验证:
+安装完成后，启动一个新的 shell 会话，然后验证：
 
 ```bash
 mcpp --version
@@ -53,12 +58,13 @@ mcpp --version
 ```
 
 > [!TIP]
-> Unix release 安装脚本若提示 `command not found`,通常是 `~/.mcpp/bin`
-> 尚未加入当前 shell 的 PATH。重启终端,或执行 `source ~/.bashrc`(zsh 对应
-> `~/.zshrc`,fish 使用 `exec fish`)即可生效；该安装方式可直接通过
-> `~/.mcpp/bin/mcpp` 调用。若经 xlings 安装,应使用 xlings 当前激活的 bin
-> 目录。Windows 请使用 PowerShell 的 xlings 安装命令，重启 PowerShell 而不是
-> 执行 `source`，并用 `Get-Command mcpp.exe` 确认当前命令。
+> 若 Unix release 安装脚本提示 `command not found`，通常是因为
+> `~/.mcpp/bin` 尚未加入当前 shell 的 PATH。重启终端，或执行
+> `source ~/.bashrc`（zsh 对应 `~/.zshrc`，fish 用 `exec fish`）以生效；
+> 该安装方式下可直接用 `~/.mcpp/bin/mcpp` 调用。若通过 xlings 安装，应改
+> 用 xlings 当前激活的 bin 目录。Windows 上请通过 PowerShell 的 xlings
+> 命令安装，重启 PowerShell 而不是执行 `source`，并用
+> `Get-Command mcpp.exe` 确认当前生效的命令。
 
 ## 创建项目
 
@@ -66,18 +72,19 @@ mcpp --version
 mcpp new hello && cd hello
 ```
 
-生成的目录结构如下:
+生成的目录结构如下：
 
 ```
 hello/
-├── mcpp.toml            ← 工程描述
+├── mcpp.toml            ← project manifest
 ├── src/
 │   └── main.cpp
 └── tests/
-    └── test_smoke.cpp   ← 可由 `mcpp test` 运行
+    └── test_smoke.cpp   ← runs with `mcpp test`
 ```
 
-生成的 manifest 只包含包元数据；mcpp 会从 `src/main.cpp` 推断 binary target。该文件默认为 C++23 模块化的 hello world:
+生成的 manifest 只含包元数据；mcpp 从 `src/main.cpp` 推断 binary
+target。默认情况下该文件是一个 C++23 模块化的 hello world：
 
 ```cpp
 import std;
@@ -88,23 +95,24 @@ int main() {
 }
 ```
 
-### 从包模板创建项目
+### 从包模板创建
 
-`mcpp new --template` 与 `mcpp add` 使用同一种精确包 selector 风格:
+`mcpp new --template` 与 `mcpp add` 使用完全相同的包 selector 语法：
 
 ```bash
 mcpp new gui-demo --template ocornut.imgui@1.92.8:docking
 mcpp new --list-templates ocornut.imgui@1.92.8
 ```
 
-文法是 `[namespace.]name[@version][:template]`，namespace、version 与模板名可分别
-省略。省略 namespace 只表示唯一默认命名空间 `mcpplibs`，不会按短名扫描整个索引。
-省略模板名时，mcpp 使用唯一的 `default = true`；若包只有一个模板且未显式声明
-default，该单模板自动成为默认。多个模板却没有 default 会明确报错并提示
-`--list-templates`。不再引入另一套 `--variant` 词汇。
+文法是 `[namespace.]name[@version][:template]`。namespace、version 与
+模板名各自独立可省略；省略 namespace 表示唯一的默认命名空间
+`mcpplibs`，而不是按短名扫描整个索引。省略模板名时，mcpp 使用唯一那个
+`default = true` 声明；若没有显式标记默认值而包只有一个模板，就自动使用
+那个唯一的模板。存在多个模板却没有默认值是一个错误，会指向
+`--list-templates`。没有另一套 `--variant` 词汇。
 
-包身份、版本与模板会在提交目标目录前全部解析完成；下载、渲染、hook 或校验失败时，
-不会留下半成品项目目录。
+包身份、版本与模板会在提交目标目录之前全部解析完成。下载、渲染、hook 或
+校验失败时，不会留下一个半成品的工程目录。
 
 ## 构建与运行
 
@@ -117,103 +125,114 @@ mcpp run
 # Built with import std + std::println on modular C++23.
 ```
 
-首次构建需下载随宿主选择的默认工具链,期间显示进度与速度。下载完成后,所有 mcpp 项目共用同一份沙盒。
+首次构建会下载按宿主选择的默认工具链，期间显示进度与速度。下载完成后，
+所有 mcpp 工程共用同一份沙盒。
 
-### 在首次成功构建前配置 IDE
+### 在首次成功构建前配置编辑器
 
-源码尚未可构建时,可以先生成编译数据库,而不编译普通翻译单元或链接最终目标:
+源码尚不可构建时，可以只生成编译数据库，而不编译普通翻译单元、也不链接
+最终目标：
 
 ```bash
 mcpp build --configure-only
 # Configured hello (... compile commands)
 ```
 
-该命令与普通构建使用相同的包、workspace member、profile、feature、capability、
-target 和 toolchain 解析结果。生成的 `compile_commands.json` 同时覆盖普通源码与
-`tests/**/*.cpp`,并把测试专用依赖及匹配的 `[build].flags` 带入测试 TU,因此 clangd/ccls
-可以在代码尚未编译通过时索引工程。它是“只配置”而不是只读操作:`build.mcpp`、缺失的
-依赖或 toolchain、lock/resolution 元数据以及构建目录元数据仍可能被更新,只能在可信
-workspace 中运行。插件稳定依赖进程退出码和生成的 `compile_commands.json`,标准输出仍是
-面向人的文本,不作为机器协议。
+该命令解析的包、workspace 成员、profile、feature、capability provider、
+target 与 toolchain 与一次真实构建完全相同。生成的 `compile_commands.json`
+覆盖普通源码与 `tests/**/*.cpp`，包含仅测试使用的依赖以及匹配的
+`[build].flags`，因此 clangd/ccls 可以在工程仍处于编辑状态时为它建立
+索引。这是一次配置操作，不是只读操作：`build.mcpp`、缺失的依赖或
+toolchain、lock/resolution 元数据以及构建目录元数据都可能被更新。只应在
+可信的 workspace 中运行。进程退出码与生成的 `compile_commands.json` 是
+稳定的集成契约；标准输出仍是面向人的文本。
 
-不允许写入工程目录的编辑器在标准输出上取得同一份计划 *(mcpp 2026.9.15.1+)*:
+不允许写入工程目录的编辑器，在标准输出上取得同一份计划
+*(mcpp 2026.9.15.1+)*：
 
 ```bash
 mcpp emit build-database --format json
 ```
 
-文档是 S1 构建数据库:每个翻译单元及其编译命令、它提供与导入的模块、工具链以及标准库
-模块单元。`--spec compile-commands` 改为输出 `compile_commands.json` 的条目。字段见
-[50 —— 机器可读输出](50-machine-output.md),规则见 [SPEC-005](../specs/build-database.md)。
+该文档是一份 S1 构建数据库：每个翻译单元及其编译命令、它提供与导入的
+模块、工具链，以及标准库模块单元。`--spec compile-commands` 改为输出
+`compile_commands.json` 的条目。字段列在
+[50 —— 机器可读输出](50-machine-output.md)，规则见
+[SPEC-005](../specs/build-database.md)。
 
 ## 增量编译与测试
 
-[08 —— 测试](08-testing.md) 是拥有这个主题的章节;下面只是本教程需要的那一步。
-
 ```bash
-mcpp build              # 增量构建
-mcpp clean              # 清理 target/
-mcpp clean --stale      # 只删 target/<三元组>/<指纹>/ 下已无构建使用的目录 (--dry-run 只列出; --older-than 3d 保留更新的未记录目录)
-mcpp test               # 编译并运行 tests/**/*.cpp —— 每文件一个独立二进制,
-                        # 框架无关(裸 main,或经 [dev-dependencies] 使用 gtest)
-mcpp test <pattern>     # 只运行名字包含 <pattern> 的测试
-mcpp test --list        # 只枚举测试,不构建
-mcpp test --timeout 30  # 单个测试**运行**超过 30s 被终止(默认 300;0 = 不限)
-mcpp test --build-timeout 120   # 单次编译/链接超过 120s 被终止(默认关闭)
+mcpp build              # incremental build
+mcpp clean              # clean target/
+mcpp clean --stale      # drop only target/<triple>/<fingerprint>/ dirs no build still uses
+                        # (--dry-run lists and deletes nothing; --older-than 3d keeps newer unrecorded ones)
+mcpp test               # compile and run tests/**/*.cpp — one binary per file,
+                        # framework-agnostic (bare main, or gtest via [dev-dependencies])
+mcpp test <pattern>     # only tests whose name contains <pattern>
+mcpp test --list        # enumerate tests without building
+mcpp test --timeout 30  # kill a test still RUNNING after 30s (default 300; 0 = no limit)
+mcpp test --build-timeout 120   # kill a compile/link still running after 120s (off by default)
 ```
 
-**运行**那一半默认有界 —— 无人值守的 CI 不该被一个挂住的测试吃掉整个 job。两个期限
-覆盖的是不同的一半,互不蕴含:`--timeout` 约束测试**进程的运行**,`--build-timeout`
-约束**单次 ninja 驱动**(包级构建、批量测试构建、每个测试各自独立计时)。
-**链接卡死属于 `--build-timeout`,`--timeout` 设多大都无效。**
+**运行**那一半默认有界，这样无人值守的 CI 任务就不会被一个挂住的测试拖住
+整个 job。两个期限覆盖不同的一半，互不蕴含：`--timeout` 约束测试
+**进程**，`--build-timeout` 约束**一次 ninja 驱动**（包级构建、批量测试
+构建、每个测试各自的构建分别计时）。**一次永不返回的链接属于
+`--build-timeout` 管辖的情形；任何 `--timeout` 值都拦不住它。**
 
-`--build-timeout` 默认关闭,这个不对称是**实测**出来的而非风格选择:单个测试跑过 5 分钟
-不寻常,而冷依赖构建跑过 15 分钟很平常(mcpp-index 有一个成员要从源码建 OpenCV,
-linux 1019s、windows 1289s)。给它一个默认上限会把「慢但正确」的构建判红。构建可以跑多久
-是工程自身的性质,所以由工程来说。仅 POSIX 有效 —— Windows 上没有 kill-by-handle 路径,
-该值被忽略。
+`--build-timeout` 默认关闭，这种不对称是**实测**得到的，而不是风格选择：
+一个测试二进制运行超过五分钟不寻常，一次冷依赖构建运行超过十五分钟很
+平常（mcpp-index 有一个成员从源码构建 OpenCV，Linux 上 1019 秒、
+Windows 上 1289 秒）。给它一个默认上限会把「慢但正确」的构建判红。构建
+可以跑多久是工程自身的性质，所以由工程来说。仅 POSIX 有效——期限运行器
+在 Windows 上没有按句柄终止的路径，该值在那里被忽略。
 
 ## 添加依赖
 
-在 `mcpp.toml` 中声明依赖:
+在 `mcpp.toml` 中声明依赖：
 
 ```toml
 [dependencies]
 "mcpplibs.cmdline" = "^0.0.1"
 ```
 
-`mcpp build` 将自动从
+`mcpp build` 会自动针对
 [mcpp-index](https://github.com/mcpplibs/mcpp-index) 解析 SemVer
-约束、拉取源码并加入编译图。完整示例参见
-[03 — 示例项目](03-examples.md) 中的 `02-with-deps`。
+约束、拉取源码并加入构建图。完整示例见
+[03 —— 示例项目](03-examples.md) 中的 `02-with-deps`。
 
 ## 生成发布包
 
-`mcpp pack` 将构建产物与运行期依赖打包为可独立分发的 tarball:
+`mcpp pack` 把构建产物与运行期依赖打包为可独立分发的 tarball：
 
 ```bash
-mcpp pack                          # 默认 vendored,打包项目第三方 .so
-mcpp pack --mode system            # 依赖目标系统提供库
-mcpp pack --mode static            # musl 全静态构建
-mcpp pack --mode self-contained    # 打包 loader、libc 与依赖
+mcpp pack                          # vendored by default: bundle project third-party .so files
+mcpp pack --mode system            # rely on target-system libraries
+mcpp pack --mode static            # fully static musl build
+mcpp pack --mode self-contained    # bundle loader, libc, and dependencies
 ```
 
-四种模式的差异及产物布局参见 [10 — 发布打包](10-pack-and-release.md)。`bundle-project` 与 `bundle-all` 仍分别是 `vendored` 与 `self-contained` 的兼容别名。
+四种模式的差异及产物布局见
+[10 —— 发布打包](10-pack-and-release.md)。`bundle-project` 与
+`bundle-all` 仍然是 `vendored` 与 `self-contained` 的可用别名。
 
 ## 后续阅读
 
-- [03 — 示例项目](03-examples.md) — 可直接运行的最小工程集合
-- [10 — 发布打包](10-pack-and-release.md) — 构建可分发产物
-- [20 — 工具链管理](20-toolchains.md) — 切换编译器与多版本管理
-- 任意命令的完整选项可通过 `mcpp <cmd> --help` 查阅
-
+- [03 —— 示例项目](03-examples.md)——可直接运行的最小工程集合
+- [10 —— 发布打包](10-pack-and-release.md)——构建可分发产物
+- [20 —— 工具链管理](20-toolchains.md)——切换编译器与管理多个版本
+- 任意命令的完整选项都可通过 `mcpp <cmd> --help` 查阅
 
 ## 更多入口
 
-- GUI 起步:`mcpp new myapp --template ocornut.imgui@1.92.8:docking`(模板随包分发；
-  省略 `:docking` 使用已声明 default/唯一模板，或运行
-  `mcpp new --list-templates ocornut.imgui@1.92.8`)。
-- 解释默认决策:`mcpp why [toolchain|runtime|deps]`;主机能力体检:`mcpp self doctor`;
-  机器可读解析清单:构建产物 `target/<triple>/<fp>/resolution.json`。
-- 离线运行:`mcpp --offline` 或 `MCPP_OFFLINE=1` 可阻止索引刷新、下载和工具链安装。在从未使用过的 home 中,它同时跳过首次使用时的沙箱引导(索引克隆、ninja、patchelf),只提示一次,并让该 home 保持未引导状态;需要这些工具的命令会自行报告。
-
+- GUI 起步：`mcpp new myapp --template ocornut.imgui@1.92.8:docking`
+  （模板随包分发；省略 `:docking` 使用已声明的 default / 唯一模板，或
+  运行 `mcpp new --list-templates ocornut.imgui@1.92.8`）。
+- 解释默认决策：`mcpp why [toolchain|runtime|deps]`；宿主能力体检：
+  `mcpp self doctor`；机器可读的解析清单：构建产物
+  `target/<triple>/<fp>/resolution.json`。
+- 离线运行：`mcpp --offline` 或 `MCPP_OFFLINE=1` 会阻止索引刷新、下载与
+  工具链安装。在从未使用过的 home 中，它还会跳过首次使用时的沙箱引导
+  （索引克隆、ninja、patchelf），只提示一次，并让该 home 保持未引导
+  状态；需要这些工具的命令会各自报告缺失。
diff --git a/docs/zh/02-scenarios.md b/docs/zh/02-scenarios.md
index 4f4f375cd..55990490c 100644
--- a/docs/zh/02-scenarios.md
+++ b/docs/zh/02-scenarios.md
@@ -1,17 +1,18 @@
 # 02 —— 场景
 
-**读者:**正在判断 mcpp 适不适合手头这份工作、以及这份工作会用到它哪些功能的
+**读者：** 正在判断 mcpp 是否适合手头这份工作、以及这份工作会用到它哪些功能的
 开发者。
 
-**本章回答的那一个问题:**mcpp 服务哪几类工程,而对其中一类,要用到哪些功能、
+**本章回答的那一个问题：** mcpp 服务哪几类工程，而对其中一类，要用到哪些功能、
 按什么顺序。
 
-**不在这里:**字段参考,那是 [04](04-mcpp-toml.md);示例目录,那是
-[03](03-examples.md) —— 它按**示例**索引而不是按场景;以及命令查阅,那是
+**不在这里：** 字段参考，那是 [04](04-mcpp-toml.md)；示例目录，那是
+[03](03-examples.md)——它按**示例**索引而不是按场景；以及命令查阅，那是
 [09](09-commands-by-scenario.md)。本章按**工作本身**索引。
 
-每个场景陈述:处境、mcpp 对它贡献了什么、穿过章节的路径、可以跑的一个工程,以及
-**最常让人意外的那一件事**。只读与手头工作相符的那个场景即可;它们之间不相互叠加。
+每个场景陈述：处境、mcpp 对它贡献了什么、穿过各章节的路径、一个可以跑的工程，
+以及**最常让人意外的那一件事**。只读与手头工作相符的那一个场景即可；场景之间
+互不叠加。
 
 ## 场景一览
 
@@ -25,225 +26,236 @@
 | [6](#6-没有操作系统的目标) | 没有操作系统的目标 | `mcpp new … --template riscv-virt-rt` |
 | [7](#7-gpu-或加速器上的计算) | GPU 或加速器上的计算 | `examples/09-heterogeneous` |
 | [8](#8-图形渲染) | 图形渲染 | `examples/10-graphics/offscreen` |
-| [9](#9-工程需要的一步构建工作) | 工程需要的一步构建工作,以及把它共享出去 | `examples/08-build-rules`、`12-a-new-device-language` |
+| [9](#9-工程需要的一步构建工作) | 工程需要的一步构建工作，以及把它共享出去 | `examples/08-build-rules`、`12-a-new-device-language` |
 | [10](#10-为别人打包一个工具一个驱动或一块板子) | 为别人打包一个工具、一个驱动或一块板子 | `xim-pkgindex` 与 `mcpp-index` 里的描述符 |
 
 ## 1. 命令行工具或服务
 
-**处境。** 一个由 C++23 模块构建的程序,带几个依赖,而且要跑在一台没有 mcpp 的
-机器上。
+**处境。** 一个由 C++23 模块构建的程序，带几个依赖，而且要跑在一台没有 mcpp
+的机器上。
 
-**mcpp 贡献了什么。** `import std` 零配置可用;编译器是被钉住的载荷,而不是机器
-上恰好有的那个;并且一条命令产出一个自带所需之物的二进制。
+**mcpp 贡献了什么。** `import std` 零配置可用；编译器是被钉住的载荷，而不是
+机器上恰好有的那一个；一条命令产出一个自带所需之物的二进制。
 
 **路径。**
 
-1. [00 —— mcpp 是什么](00-what-mcpp-is.md) —— 五个名词。
-2. [01 —— 快速开始](01-getting-started.md) —— 把程序跑起来。
-3. [05 —— 依赖与解析](05-dependencies.md) —— `[dependencies]`、锁文件。
-4. [08 —— 测试](08-testing.md) —— `tests/**/*.cpp`。
-5. [20 —— 工具链管理](20-toolchains.md) —— 当编译器版本要紧,或者工程必须钉住
+1. [00 —— mcpp 是什么](00-what-mcpp-is.md)——五个名词。
+2. [01 —— 快速开始](01-getting-started.md)——把程序跑起来。
+3. [05 —— 依赖与解析](05-dependencies.md)——`[dependencies]`、锁文件。
+4. [08 —— 测试](08-testing.md)——`tests/**/*.cpp`。
+5. [20 —— 工具链管理](20-toolchains.md)——编译器版本要紧、或工程必须钉住
    一个的时候。
-6. [10 —— 发布打包](10-pack-and-release.md) —— `mcpp pack`。
+6. [10 —— 发布打包](10-pack-and-release.md)——`mcpp pack`。
 
-**跑。** [`examples/01-hello`](../../examples/01-hello/),然后
-[`02-with-deps`](../../examples/02-with-deps/),再
+**跑。** [`examples/01-hello`](../../examples/01-hello/)，然后
+[`02-with-deps`](../../examples/02-with-deps/)，再
 [`03-pack-static`](../../examples/03-pack-static/)。
 
-**最让人意外的一件事。** debug 构建与 release 构建互不失效。每种配置在 `target/`
-下有自己的指纹目录,所以在两者之间来回切换不是一次重建。
+**最让人意外的一件事。** debug 构建与 release 构建互不失效。每种配置在
+`target/` 下有自己的指纹目录，所以在两者之间来回切换不是一次重建。
 
 ## 2. 供他人 import 的库
 
-**处境。** 别的包会把它写进 `[dependencies]` 的代码,其中可能有可选的部分。
+**处境。** 别的包会把它写进自己的 `[dependencies]`，其中可能含可选的部分。
 
-**mcpp 贡献了什么。** 模块接口就是被发布的表面;feature 让其中一部分成为可选而
-不必拆出第二个包;预建二进制可以声明它与哪些工具链兼容。
+**mcpp 贡献了什么。** 模块接口就是被发布的表面；feature 让其中一部分成为可选
+而不必拆出第二个包；预建二进制可以声明它与哪些工具链兼容。
 
 **路径。**
 
-1. [04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) —— `[lib]`、库根。
-2. [06 —— Feature 与能力](06-features-and-capabilities.md) —— 可选部分,以及它们
-   拉取的依赖。
-3. [08 —— 测试](08-testing.md) —— `[dev-dependencies]`。
-4. [11 —— 发布一个库](11-publishing-a-library.md) —— 描述符。
-5. [12 —— 分发预编译库](12-binary-distribution.md) —— 如果同时交付二进制。
+1. [04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md)——`[lib]`、库根。
+2. [06 —— Feature 与能力](06-features-and-capabilities.md)——可选部分，
+   以及它们拉取的依赖。
+3. [08 —— 测试](08-testing.md)——`[dev-dependencies]`。
+4. [11 —— 发布一个库](11-publishing-a-library.md)——描述符。
+5. [12 —— 分发预编译库](12-binary-distribution.md)——如果同时交付二进制。
 
-**跑。** [`examples/11-features`](../../examples/11-features/) 把三种 feature 形态
-都声明了一遍;[`05-lib-distribution`](../../examples/05-lib-distribution/) 是
-生产方与消费方成对的那个。
+**跑。** [`examples/11-features`](../../examples/11-features/) 把三种 feature
+形态都声明了一遍；[`05-lib-distribution`](../../examples/05-lib-distribution/)
+是生产方与消费方成对的那一个。
 
-**最让人意外的一件事。** 判断一个可选后端是否真的可选,判据**不是**「默认构建仍然
-能过」,而是「默认构建的**解析里不出现**那个包」。一个被解析出来却没被用到的依赖,
-仍然要付下载的代价。
+**最让人意外的一件事。** 判断一个可选后端是否真的可选，判据**不是**「默认
+构建仍然能过」，而是「默认构建的**解析里不出现**那个包」。一个被解析出来却
+没被用到的依赖，仍然要付下载的代价。
 
 ## 3. 一个仓库里的多个包
 
-**处境。** 多个包一起开发,彼此按路径依赖。
+**处境。** 多个包一起开发，彼此按路径相互依赖。
 
-**mcpp 贡献了什么。** 一条命令构建或测试整组;成员之间不经注册表就能相互解析;
-每个成员保留自己的 manifest 与身份。
+**mcpp 贡献了什么。** 一条命令构建或测试整组；成员之间不经注册表就能相互
+解析；每个成员保留自己的 manifest 与身份。
 
 **路径。**
 
-1. [07 —— 工作空间](07-workspace.md) —— `[workspace]`、path 依赖。
-2. [05 —— 依赖与解析](05-dependencies.md) —— path 依赖做什么、不做什么。
-3. [08 —— 测试](08-testing.md) —— 扇出。
+1. [07 —— 工作空间](07-workspace.md)——`[workspace]`、path 依赖。
+2. [05 —— 依赖与解析](05-dependencies.md)——path 依赖做什么、不做什么。
+3. [08 —— 测试](08-testing.md)——扇出。
 
 **跑。** [`examples/04-workspace`](../../examples/04-workspace/)。
 
-**最让人意外的一件事。** 工作空间的成员**不是**一个根。任何枚举「每一个包」的工具
-都必须说清它指的是两者中的哪一个,而答案会改变构建什么。
+**最让人意外的一件事。** 工作空间的成员**不是**一个根。任何枚举「每一个包」的
+工具都必须说清它指的是两者中的哪一个，而答案会改变构建什么。
 
 ## 4. 图形应用
 
 **处境。** 一个带窗口、渲染器与字体的桌面程序。
 
-**mcpp 贡献了什么。** 窗口与渲染栈就是普通依赖;模板脚手架出一个能跑的工程;产物
-在运行期需要什么是**被声明的**,不是被发现的。
+**mcpp 贡献了什么。** 窗口与渲染栈就是普通依赖；模板脚手架出一个能跑的工程；
+产物在运行期需要什么是**被声明的**，不是被发现的。
 
 **路径。**
 
-1. [01 —— 快速开始](01-getting-started.md) —— `mcpp new --template`。
-2. [05 —— 依赖与解析](05-dependencies.md) —— 那套栈。
-3. [10 —— 发布打包](10-pack-and-release.md) —— 可执行文件旁边还要带什么。
+1. [01 —— 快速开始](01-getting-started.md)——`mcpp new --template`。
+2. [05 —— 依赖与解析](05-dependencies.md)——那套栈。
+3. [10 —— 发布打包](10-pack-and-release.md)——可执行文件旁边还要带什么。
 
 **跑。** `mcpp new myapp --template ocornut.imgui`。
 
-**最让人意外的一件事。** 在 Linux 上,mcpp 的产物跑在一个**不查 `/usr/lib`** 的
-私有加载器后面。任何必须由宿主供给的东西 —— 图形驱动、Vulkan ICD —— 都经由工程
-声明的适配包到达,而不是靠它装在机器上。
+**最让人意外的一件事。** 在 Linux 上，mcpp 的产物跑在一个**不查 `/usr/lib`**
+的私有加载器后面。任何必须由宿主供给的东西——图形驱动、Vulkan ICD——都经由
+工程声明的适配包到达，而不是靠它装在机器上。
 
 ## 5. 为另一个操作系统构建
 
 **处境。** 一份源码树要产出 Linux、Windows 与 macOS 的二进制。
 
-**mcpp 贡献了什么。** 目标是一个参数,不是第二份检出;交叉工具链是载荷;而这台
-宿主服务不了的目标会被**拒绝**,不会被悄悄按宿主构建。
+**mcpp 贡献了什么。** 目标是一个参数，不是第二份检出；交叉工具链是载荷；这台
+宿主服务不了的目标会被**拒绝**，而不是被悄悄按宿主构建。
 
 **路径。**
 
-1. [21 —— 目标三元组](21-the-target-triple.md) —— 目标怎么命名,哪台宿主服务哪个。
-2. [24 —— 基于 openkal 的交叉构建](24-openkal-cross.md) —— 机制。
-3. [22 —— 目标侧](22-target-side.md) —— manifest 必须按目标不同时。
+1. [21 —— 目标三元组](21-the-target-triple.md)——目标怎么命名、哪台宿主服务
+   哪个。
+2. [24 —— 基于 openkal 的交叉构建](24-openkal-cross.md)——机制。
+3. [22 —— 目标侧](22-target-side.md)——manifest 必须按目标不同的时候。
 
-**跑。** [`examples/06-openkal-cross`](../../examples/06-openkal-cross/) —— 一个
-程序在任意宿主上为四个目标构建。
+**跑。** [`examples/06-openkal-cross`](../../examples/06-openkal-cross/)——
+一个程序在任意宿主上为四个目标构建。
 
-**最让人意外的一件事。** `--target` 不要求机器上**已经有**那条工具链。它要求的是
-这个目标能被这台宿主**服务**;[21](21-the-target-triple.md) 里的支持矩阵说明哪些
-可以。
+**最让人意外的一件事。** `--target` 不要求机器上**已经有**那条工具链。它要求
+的是这个目标能被这台宿主**服务**；[21](21-the-target-triple.md) 的支持矩阵
+说明哪些可以。
 
 ## 6. 没有操作系统的目标
 
-**处境。** 板子或单片机上的固件:没有 OS、默认没有 libc、有链接脚本与向量表。
+**处境。** 板子或单片机上的固件：没有 OS、默认没有 libc、有链接脚本与向量表。
 
-**mcpp 贡献了什么。** 板级支持包供给整个目标世界 —— 链接脚本、启动代码,以及
-**runner** —— 于是 `mcpp run` 在模拟器上与在真实硬件上是同一条命令。
+**mcpp 贡献了什么。** 板级支持包供给整个目标世界——链接脚本、启动代码，以及
+**runner**——于是 `mcpp run` 在模拟器上与在真实硬件上是同一条命令。
 
 **路径。**
 
-1. [40 —— 裸机与 freestanding 目标](40-baremetal.md) —— 目标、档位、`std` 还剩什么。
-2. [41 —— 抵达一台设备](41-devices.md) —— runner、具名 runner。
-3. [08 —— 测试](08-testing.md) —— 跑在板子上的测试。
+1. [40 —— 裸机与 freestanding 目标](40-baremetal.md)——目标、档位、`std`
+   还剩什么。
+2. [41 —— 在设备上运行](41-devices.md)——runner、具名 runner。
+3. [08 —— 测试](08-testing.md)——跑在板子上的测试。
 
 **跑。** `mcpp new blinky --template riscv-virt-rt`。
 
-**最让人意外的一件事。** 模拟器与真实板子相差的是**一个 feature**,不是两个包。
-`mcpp run --features hardware` 移动的是默认 runner;开发者敲的那条命令不变。
+**最让人意外的一件事。** 模拟器与真实板子相差的是**一个 feature**，不是两个
+包。`mcpp run --features hardware` 移动的是默认 runner；开发者敲的那条命令
+不变。
 
 ## 7. GPU 或加速器上的计算
 
 **处境。** 程序的一部分是由厂商编译器编译、再链接进普通二进制的 kernel。
 
-**mcpp 贡献了什么。** 设备工具包由规则包声明、由构建安装;加速器是**一条只写一次
-的轴**;产物记录下它携带了哪些设备的代码。
+**mcpp 贡献了什么。** 设备工具包由规则包声明、由构建安装；加速器是**一条只
+写一次的轴**；产物记录下它携带了哪些设备的代码。
 
 **路径。**
 
-1. [42 —— 异构硬件构建](42-heterogeneous-builds.md) —— `accel`、岛、接缝。
-2. [30 —— 构建程序](30-build-mcpp.md) —— 规则怎样到达图。
-3. [06 —— Feature 与能力](06-features-and-capabilities.md) —— 选中一条 lane 的
-   那个 feature。
+1. [42 —— 异构硬件构建](42-heterogeneous-builds.md)——`accel`、岛、接缝。
+2. [30 —— 构建程序](30-build-mcpp.md)——规则怎样到达图。
+3. [06 —— Feature 与能力](06-features-and-capabilities.md)——选中一条 lane
+   的那个 feature。
 
 **跑。** 先
 [`examples/09-heterogeneous/boundary`](../../examples/09-heterogeneous/boundary/)
-—— 它不需要设备 —— 再
+——它不需要设备——再
 [`…/cuda`](../../examples/09-heterogeneous/cuda/)。
 
-**最让人意外的一件事。** 不点名加速器的构建**一个字节都不下载**。多 GB 的工具包
-被取之前要开两道闸:选中规则的那个 feature,以及说明「这次构建确实为设备编译」的
-`cfg(accelerator = …)` 选择器。
+**最让人意外的一件事。** 不点名加速器的构建**一个字节都不下载**。多 GB 的
+工具包被取之前要开两道闸：选中规则的那个 feature，以及说明「这次构建确实为
+设备编译」的 `cfg(accelerator = …)` 选择器。
 
 ## 8. 图形渲染
 
-**处境。** 编译到 SPIR-V 的着色器、一条管线,以及必须正确的像素。
+**处境。** 编译到 SPIR-V 的着色器、一条管线，以及必须正确的像素。
 
-**mcpp 贡献了什么。** 着色器编译器是被声明的载荷;编译好的着色器以**模块**到达,
-而不是一个没人写过其名字的生成头;并且渲染结果可以在没有 GPU 的情况下被断言。
+**mcpp 贡献了什么。** 着色器编译器是被声明的载荷；编译好的着色器以
+**模块**到达，而不是一个没人写过其名字的生成头；渲染结果可以在没有 GPU 的
+情况下被断言。
 
 **路径。**
 
-1. [42 —— 异构硬件构建](42-heterogeneous-builds.md) —— 着色器那条 lane。
-2. [30 —— 构建程序](30-build-mcpp.md) —— 要模块表面的那一行。
-3. [10 —— 发布打包](10-pack-and-release.md) —— 交付它。
+1. [42 —— 异构硬件构建](42-heterogeneous-builds.md)——着色器那条 lane。
+2. [30 —— 构建程序](30-build-mcpp.md)——要模块表面的那一行。
+3. [10 —— 发布打包](10-pack-and-release.md)——交付它。
 
 **跑。** [`examples/10-graphics/offscreen`](../../examples/10-graphics/offscreen/)
-—— 离屏渲染一个三角形,并与软件光栅器逐像素比对。
+——离屏渲染一个三角形，并与软件光栅器逐像素比对。
 
-**最让人意外的一件事。** 软件设备不自动等价于硬件的替身。框架可能因为设备的**类型**
-就拒绝它,哪怕它满足框架要求的每一项;那是框架自己的策略,不是打包缺陷。
+**最让人意外的一件事。** 软件设备不自动等价于硬件的替身。框架可能因为设备的
+**类型**就拒绝它，哪怕它满足框架要求的每一项；那是框架自己的策略，不是打包
+缺陷。
 
 ## 9. 工程需要的一步构建工作
 
-**处境。** 代码生成、嵌入资源、一项检查,或者第二个编译器 —— 引擎没有规则的东西。
+**处境。** 代码生成、嵌入资源、一项检查，或者第二个编译器——引擎没有规则的
+东西。
 
-**mcpp 贡献了什么。** 这一步变成与其余一切同一张图上的边:被定序、进指纹、可增量,
-失败时按自己的名字被报出。它不是一个构建前脚本。
+**mcpp 贡献了什么。** 这一步变成与其余一切同一张图上的边：被定序、进指纹、
+可增量，失败时按自己的名字被报出。它不是一个构建前脚本。
 
 **路径。**
 
-1. [30 —— 构建程序](30-build-mcpp.md) —— `mcpp::action`、四种 role。
-2. [31 —— 编写规则包](31-authoring-a-rule-package.md) —— 如果别的工程也该用上它。
-3. [23 —— 项目环境](23-the-project-environment.md) —— 声明这一步要跑的工具。
+1. [30 —— 构建程序](30-build-mcpp.md)——`mcpp::action`、四种 role。
+2. [31 —— 编写规则包](31-authoring-a-rule-package.md)——如果别的工程也该
+   用上它。
+3. [23 —— 项目环境](23-the-project-environment.md)——声明这一步要跑的工具。
 
-**跑。** [`examples/08-build-rules`](../../examples/08-build-rules/) 是做检查与
-嵌入的规则;[`12-a-new-device-language`](../../examples/12-a-new-device-language/)
-教会 mcpp 一门引擎从未听说过的语言。
+**跑。** [`examples/08-build-rules`](../../examples/08-build-rules/) 是做检查
+与嵌入的规则；
+[`12-a-new-device-language`](../../examples/12-a-new-device-language/) 教会
+mcpp 一门引擎从未听说过的语言。
 
-**最让人意外的一件事。** 这一步调用的**那个工具本身是它的输入**。少了这一条,改动
-生成器会让每条边都是干净的,产物保留上一个生成器产生的字节 —— 一次覆盖在陈旧结果
-之上的绿色构建。
+**最让人意外的一件事。** 这一步调用的**那个工具本身是它的输入**。少了这一条，
+改动生成器会让每条边都是干净的，产物保留上一个生成器产生的字节——一次覆盖在
+陈旧结果之上的绿色构建。
 
 ## 10. 为别人打包一个工具、一个驱动或一块板子
 
-**处境。** 别的工程应当能够声明并得到的东西:一个编译器、一个着色器编译器、一个
-模拟器、一个宿主图形驱动、一块板子。
+**处境。** 别的工程应当能够声明并得到的东西：一个编译器、一个着色器编译器、
+一个模拟器、一个宿主图形驱动、一块板子。
 
-**mcpp 贡献了什么。** 消费者按名字声明它就能得到一个能用的程序 —— 载荷被安装、它的
-库进了产物的搜索路径,而档位决定「一次从不运行的构建要不要为它付代价」。
+**mcpp 贡献了什么。** 消费者按名字声明它就能得到一个能用的程序——载荷被
+安装，它的库进了产物的搜索路径，而档位决定「一次从不运行的构建要不要为它
+付代价」。
 
 **路径。**
 
-1. [32 —— 编写一个载荷](32-authoring-a-payload.md) —— 由 mcpp 安装的工具或预编译库。
-2. [33 —— 编写运行时适配包](33-authoring-an-adapter.md) —— 当那个库属于宿主、
+1. [32 —— 编写一个载荷](32-authoring-a-payload.md)——由 mcpp 安装的工具或
+   预编译库。
+2. [33 —— 编写运行时适配包](33-authoring-an-adapter.md)——当那个库属于宿主、
    不可再分发时。
-3. [34 —— 编写板级支持包](34-authoring-a-bsp.md) —— 一块板子、它的内存布局,以及
-   抵达它的方式。
-4. [31 —— 编写规则包](31-authoring-a-rule-package.md) —— 如果有一步构建工作要驱动
-   这个工具。
+3. [34 —— 编写板级支持包](34-authoring-a-bsp.md)——一块板子、它的内存布局，
+   以及抵达它的方式。
+4. [31 —— 编写规则包](31-authoring-a-rule-package.md)——如果有一步构建工作
+   要驱动这个工具。
 
-**跑。** 描述符本身:载荷看 `xim-pkgindex/pkgs/g/glslang.lua`,适配包看
-`mcpp-index/pkgs/c/compat.vulkan-runtime.lua`,板子看 `mcpplibs/cortex-m-rt`。
+**跑。** 描述符本身：载荷看 `xim-pkgindex/pkgs/g/glslang.lua`，适配包看
+`mcpp-index/pkgs/c/compat.vulkan-runtime.lua`，板子看 `mcpplibs/cortex-m-rt`。
 
-**最让人意外的一件事。** 该用哪个答案,由**许可证与 ABI** 决定,不由偏好决定。
-用户态与内核模块处于锁步、且许可证禁止再分发的驱动**不能**是载荷;它是宿主能力,
-而适配包是产物够到它的方式。开源驱动就是载荷,用着它的机器完全不需要适配包。
+**最让人意外的一件事。** 该用哪个答案，由**许可证与 ABI** 决定，不由偏好
+决定。用户态与内核模块处于锁步、且许可证禁止再分发的驱动**不能**是载荷；
+它是宿主能力，而适配包是产物够到它的方式。开源驱动就是载荷，用着它的机器
+完全不需要适配包。
 
 ## 当前边界
 
-- 这里列出的场景,都是背后有**可运行的工程或已发布模板**的那些。mcpp 服务得了、
-  但本仓库没有任何东西演示的场景不在此列 —— 一条没有工程可跑的路径是一个主张,
-  不是一个场景。
-- 在既有构建系统内部采用 mcpp 不是这里的场景。mcpp 构建它自己拥有的工程;与另一个
-  构建系统的产物互操作既无文档也无示例覆盖。
+- 这里列出的场景，都是背后有**可运行的工程或已发布模板**的那些。mcpp 服务
+  得了、但本仓库没有任何东西演示的场景不在此列——一条没有工程可跑的路径是
+  一个主张，不是一个场景。
+- 在既有构建系统内部采用 mcpp 不是这里的场景。mcpp 构建它自己拥有的工程；
+  与另一个构建系统的产物互操作既无文档也无示例覆盖。
diff --git a/docs/zh/03-examples.md b/docs/zh/03-examples.md
index ff9cc3549..9dffbd2b4 100644
--- a/docs/zh/03-examples.md
+++ b/docs/zh/03-examples.md
@@ -1,16 +1,16 @@
 # 03 —— 示例项目
 
-**读者:**在挑一个起点,或者在找一个与自己形状相近的工程的人。
+**读者：**在挑一个起点，或者在找一个与自己形状相近的工程的人。
 
-**本章回答的那一个问题:**哪个示例教什么,以及它们以什么顺序相互叠加。
+**本章回答的那一个问题：**哪个示例教什么，以及它们以什么顺序相互叠加。
 
-**不在这里:**任何一个示例的内容 —— 每个示例自带 README,只解释它新增的部分。
-在此之前:[01 —— 快速开始](01-getting-started.md)。在此之后:
+**不在这里：**任何一个示例的内容 —— 每个示例自带 README，只解释它新增的部分。
+在此之前：[01 —— 快速开始](01-getting-started.md)。在此之后：
 [04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md)。
 
-[`examples/`](../../examples) 目录是一套课程。每个工程都可以单独跑起来,而且每个
-工程都教**一件更早的示例没有教过的事**。本章说明那件事是什么,于是你可以按自己
-需要的深度进入,而不必从头读起。
+[`examples/`](../../examples) 目录是一套课程。每个工程都可以单独跑起来，而且每个
+工程都教**一件更早的示例没有教过的事**。本章说明那件事是什么，于是你可以按自己
+需要的深度进入，而不必从头读起。
 
 ## 运行方式
 
@@ -20,8 +20,8 @@ cd mcpp/examples/01-hello
 mcpp build && mcpp run
 ```
 
-每个示例自带 README,只解释它新增的部分。安装与工具链初始化在
-[01 —— 快速开始](01-getting-started.md),不在示例里重复。
+每个示例自带 README，只解释它新增的部分。安装与工具链初始化在
+[01 —— 快速开始](01-getting-started.md)，不在示例里重复。
 
 ## 课程
 
@@ -32,64 +32,64 @@ mcpp build && mcpp run
 | [`01-hello`](../../examples/01-hello/) | 一个包、`import std`、`mcpp build` 与 `mcpp run` |
 | [`02-with-deps`](../../examples/02-with-deps/) | `[dependencies]`、锁文件、`mcpp add` |
 | [`04-workspace`](../../examples/04-workspace/) | `[workspace]`、path 依赖、`mcpp build --workspace` |
-| [`11-features`](../../examples/11-features/) | **声明** feature 而不是消费它,`[feature-deps]`、`[dev-dependencies]`、`[profile.<name>]`、`mcpp::has_feature` |
+| [`11-features`](../../examples/11-features/) | **声明** feature 而不是消费它，`[feature-deps]`、`[dev-dependencies]`、`[profile.<name>]`、`mcpp::has_feature` |
 
 ### B —— 发布
 
 | 示例 | 首次引入的内容 |
 |---|---|
 | [`03-pack-static`](../../examples/03-pack-static/) | `mcpp pack --mode static`、`[target.<triple>]`、`[pack]` |
-| [`05-lib-distribution`](../../examples/05-lib-distribution/) | 一个库的接口与它的预编译二进制;从同一份源产出 C 头文件与 C++ 模块 |
+| [`05-lib-distribution`](../../examples/05-lib-distribution/) | 一个库的接口与它的预编译二进制；从同一份源产出 C 头文件与 C++ 模块 |
 
 ### C —— 环境
 
 | 示例 | 首次引入的内容 |
 |---|---|
-| [`07-project-subos`](../../examples/07-project-subos/) | `[xlings]`、`[xlings.workspace]`,以及 `PATH` 来自工程声明环境的构建程序 |
+| [`07-project-subos`](../../examples/07-project-subos/) | `[xlings]`、`[xlings.workspace]`，以及 `PATH` 来自工程声明环境的构建程序 |
 
 ### D —— 目标
 
 | 示例 | 首次引入的内容 |
 |---|---|
-| [`06-openkal-cross`](../../examples/06-openkal-cross/) | `--target`,同一份源在任意宿主上为四台机器构建 |
+| [`06-openkal-cross`](../../examples/06-openkal-cross/) | `--target`，同一份源在任意宿主上为四台机器构建 |
 
 裸机由**模板**而不是本目录里的一个工程来教 —— 见下面的*以模板形式到达的课程*。
 
 ### E —— 设备与图形
 
 [`09-heterogeneous`](../../examples/09-heterogeneous/) 按顺序读。它的 README 是
-地图;下表是每个子示例新增的部分。
+地图；下表是每个子示例新增的部分。
 
 | 示例 | 首次引入的内容 |
 |---|---|
-| [`…/boundary`](../../examples/09-heterogeneous/boundary/) | 单独的岛边界:消费者 import 一个生成的模块,工程里没有接缝也没有头文件。不需要设备 |
-| [`…/cuda`](../../examples/09-heterogeneous/cuda/) | 设备编译器、生成边界之上的接缝、把驱动陈述为 fact 与 floor |
-| [`…/vulkan`](../../examples/09-heterogeneous/vulkan/) | 一个 compute shader,其 SPIR-V 载荷以模块到达 |
-| [`…/sycl`](../../examples/09-heterogeneous/sycl/) | 第二个编译器,自带它自己的标准库 |
+| [`…/boundary`](../../examples/09-heterogeneous/boundary/) | 单独的岛边界：消费者 import 一个生成的模块，工程里没有接缝也没有头文件。不需要设备 |
+| [`…/cuda`](../../examples/09-heterogeneous/cuda/) | 设备编译器、生成边界之上的接缝、把驱动版本既陈述为事实也陈述为下限 |
+| [`…/vulkan`](../../examples/09-heterogeneous/vulkan/) | 一个 compute shader，其 SPIR-V 载荷以模块到达 |
+| [`…/sycl`](../../examples/09-heterogeneous/sycl/) | 第二个编译器，自带它自己的标准库 |
 | [`…/hip`](../../examples/09-heterogeneous/hip/) | 手写的边界 —— 与 `boundary/` 和 `cuda/` 的对照 |
 | [`…/cann`](../../examples/09-heterogeneous/cann/) | NVIDIA 与 Khronos 谱系之外的厂商 |
-| [`…/multi-backend`](../../examples/09-heterogeneous/multi-backend/) | 多个后端进同一个产物,运行期选择 |
-| [`10-graphics/offscreen`](../../examples/10-graphics/offscreen/) | 结果是像素的渲染管线,并与软件光栅器逐像素比对 |
+| [`…/multi-backend`](../../examples/09-heterogeneous/multi-backend/) | 多个后端进同一个产物，运行期选择 |
+| [`10-graphics/offscreen`](../../examples/10-graphics/offscreen/) | 结果是像素的渲染管线，以软件光栅器为参照核验 |
 
 ### F —— 为生态编写扩展
 
 | 示例 | 首次引入的内容 |
 |---|---|
-| [`08-build-rules`](../../examples/08-build-rules/) | 两个规则包与同时使用它们的工程;`host-module = true`、`role = "check"` 的 `mcpp::action` |
-| [`12-a-new-device-language`](../../examples/12-a-new-device-language/) | `device_extensions` 与 `rule_module`:规则包教会 mcpp 一门引擎从未听说过的语言,而它的编译器是一个经 `tools = [...]` 为构建机构建出来的包 |
-| [`13-platform-targets`](../../examples/13-platform-targets/) | 一份源码、零个 `cfg`,只改 `--target` 就为 Linux、WebAssembly 和两个 Android ABI 构建;`min_api_level` 作为工程自己的决定,以及一条不能被覆盖的能力钉 |
+| [`08-build-rules`](../../examples/08-build-rules/) | 两个规则包与同时使用它们的工程；`host-module = true`、`role = "check"` 的 `mcpp::action` |
+| [`12-a-new-device-language`](../../examples/12-a-new-device-language/) | `device_extensions` 与 `rule_module`：规则包教会 mcpp 一门引擎从未听说过的语言，而它的编译器是一个经 `tools = [...]` 为构建机构建出来的包 |
+| [`13-platform-targets`](../../examples/13-platform-targets/) | 一份源码、零个 `cfg`，只改 `--target` 就为 Linux、WebAssembly 和两个 Android ABI 构建；`min_api_level` 作为工程自己的决定，以及一条不能被覆盖的能力钉 |
 
 [31 —— 编写规则包](31-authoring-a-rule-package.md) 是这两个示例所演示内容的参考。
 
 ## 以模板形式到达的课程
 
-一个包可以提供 `templates/<name>/`,由 `mcpp new --template` 实例化。那是与本目录
-和章节并列的第三个教学面;当被教的东西属于某个包而不属于 mcpp 时,课程就落在那里。
+一个包可以提供 `templates/<name>/`，由 `mcpp new --template` 实例化。那是与本目录
+和章节并列的第三个教学面；当被教的东西属于某个包而不属于 mcpp 时，课程就落在那里。
 
 | 模板 | 课程 | 章节 |
 |---|---|---|
 | `riscv-virt-rt` | 一个裸机工程、它的板级支持与它的 runner | [40](40-baremetal.md) |
-| `riscv-virt-rt:nolibc` | 同上,但没有 C 库 | [40](40-baremetal.md) |
+| `riscv-virt-rt:nolibc` | 同上，但没有 C 库 | [40](40-baremetal.md) |
 | `ocornut.imgui` | 一个带窗口与渲染栈的图形应用 | [20](20-toolchains.md) |
 
 ```bash
@@ -98,12 +98,12 @@ mcpp new blinky --template riscv-virt-rt
 
 ## 新增一个示例
 
-一个示例目录是 `mcpp.toml` + `src/` + `README.md`,编号接在最后一个之后。什么时候
-值得新增一个示例:当一个能力**改变工程的形状** —— 它包含的文件、它声明的 manifest、
-或者作者敲的命令。如果一个能力只是既有示例工程里的一行,它属于对应章节里的一个
-代码块;如果它只经由命令到达,它属于
+一个示例目录是 `mcpp.toml` + `src/` + `README.md`，编号接在最后一个之后。值得
+新增一个示例的判据：一个能力**改变了工程的形状** —— 它包含的文件、它声明的 manifest、
+或者作者敲的命令。如果一个能力只是既有示例工程里的一行，它属于对应章节里的一个
+代码块；如果它只经由命令到达，它属于
 [09 —— 按场景选命令](09-commands-by-scenario.md)。
 
-README 要写明这个示例第一个教什么,以及判断它是否成立的判据。贡献流程见
+README 要写明这个示例第一个教什么，以及判断它是否成立的判据。贡献流程见
 [90 —— 从源码构建 & 参与贡献](90-build-from-source.md)。
 
diff --git a/docs/zh/04-mcpp-toml.md b/docs/zh/04-mcpp-toml.md
index 37d9c4b93..a9f42ed6b 100644
--- a/docs/zh/04-mcpp-toml.md
+++ b/docs/zh/04-mcpp-toml.md
@@ -1,19 +1,22 @@
 # 04 —— mcpp.toml 工程文件指南
 
-**读者:**正在写或正在读一份 manifest 的作者。
+**读者：**编写或阅读一份 manifest 的作者。
 
-**本章回答的那一个问题:**一份 `mcpp.toml` 可以说什么,逐字段地。
+**本章回答的那一个问题：**一份 `mcpp.toml` 可以逐字段写下什么。
 
-**不在这里:**四个主题的表虽然写在这个文件里,但本章不拥有它们 —— 依赖是
-[05](05-dependencies.md),feature 是 [06](06-features-and-capabilities.md),
-以目标为条件是 [22](22-target-side.md),工程的环境是
-[23](23-the-project-environment.md)。每一处都在它的表本该出现的位置点名。
+**不在这里：**本文件里的这些表分属四个主题，但都不归本章拥有——依赖属于
+[05](05-dependencies.md)，feature 属于
+[06](06-features-and-capabilities.md)，对目标的条件化属于
+[22](22-target-side.md)，工程的环境属于
+[23](23-the-project-environment.md)。每个主题都在它对应的表所在处点名。
 
-`mcpp.toml` 是 mcpp 构建工具的项目配置文件,类似 Cargo 的 `Cargo.toml` 或 Node 的 `package.json`。放在项目根目录下,`mcpp build` 会自动发现并读取它。
+`mcpp.toml` 是 mcpp 构建工具的工程配置文件，类似于 Cargo 的 `Cargo.toml` 或
+Node 的 `package.json`。把它放在工程根目录；`mcpp build` 会自动发现并读取它。
 
 ## 1. 最小化示例
 
-mcpp 的设计原则是 **约定优于配置** —— 大多数字段都有合理默认值,最简单的 `mcpp.toml` 只需几行:
+mcpp 按**约定优于配置**设计——大多数字段都有合理的默认值，因此最简单的
+`mcpp.toml` 只需要几行：
 
 ### 1.1 可执行程序（最简）
 
@@ -23,11 +26,11 @@ name    = "hello"
 version = "0.1.0"
 ```
 
-mcpp 自动推断:
-- 源文件: `src/**/*.{cppm,cpp,cc,c,S,s,asm}`
-- 入口: `src/main.cpp` → 生成 `hello` 二进制
-- 标准: C++23
-- 模块: 扫描 `export module ...` 声明自动建立依赖图
+mcpp 自动推断：
+- 源文件：`src/**/*.{cppm,cpp,cc,c,S,s,asm}`
+- 入口点：`src/main.cpp` → 产出 `hello` 二进制
+- 标准：C++23
+- 模块：扫描 `export module ...` 声明并自动构建依赖图
 
 ### 1.2 库项目（最简）
 
@@ -40,55 +43,72 @@ version = "0.1.0"
 kind = "lib"
 ```
 
-lib-root 约定:主模块接口默认在 `src/mylib.cppm`(包名的最后一段)。
+库根约定：主模块接口默认是 `src/mylib.cppm`（包名的最后一段）。
 
 ## 2. 完整字段参考
 
-### 2.1 `[package]` — 包元数据
+### 2.1 `[package]` —— 包元数据
 
 ```toml
 [package]
-name        = "myapp"              # 包名(必填)
-version     = "0.1.0"              # 语义化版本(必填)
-standard    = "c++23"              # C++ 标准(默认 c++23; 可设 c++20 / c++26)
-description = "My awesome app"     # 简介(可选)
-license     = "MIT"                # 许可证(可选)
-authors     = ["Alice", "Bob"]     # 作者列表(可选)
-repo        = "https://github.com/user/myapp"  # 仓库地址(可选)
+name        = "myapp"              # Package name (required)
+version     = "0.1.0"              # Semantic version (required)
+standard    = "c++23"              # C++ standard (default c++23; can be set to c++20 / c++26)
+description = "My awesome app"     # Description (optional)
+license     = "MIT"                # License (optional)
+authors     = ["Alice", "Bob"]     # Author list (optional)
+repo        = "https://github.com/user/myapp"  # Repository URL (optional)
 ```
 
-`standard` 是 C++ 语言标准的一等配置。推荐值:
-
-- `c++23`：默认值，适合当前模块化默认模板。
-- `c++20`：mcpp 接受的最低档位——命名模块本身是 C++20 特性，再往下这套构建模型就不存在了。当外部约束(公司内规、只到 C++20 的第三方 API)必须压低档位时使用。**`import std;` 在这一档依然可用**：它虽然是 C++23 的*库*特性，但 GCC(≥ 15)、Clang + libc++(≥ 17)与 MSVC STL(VS 2022 17.8 起)都在 C++20 模式下提供 `std` 模块。代价是 C++23 库设施(`std::print`、`std::expected` 等)不可用——包括 `mcpp new` 生成的模板代码。
-- `c++26`：需要 C++26 语言特性时使用。
-- `c++2a` / `c++2c`：兼容别名，解析后分别归一为 `c++20` / `c++26`。
-- `gnu++20` / `gnu++23` / `gnu++26`：需要 GNU dialect 时使用，会进入 fingerprint 和 std BMI cache key。
-- `c++latest`：跟随当前 mcpp 支持的最新标准，适合本地试验，不推荐要求可复现的发布包使用。
-- `c++fly`：`c++latest` **再加上该工具链能开启的全部实验性标准特性**(语言 + 标准库)。GCC ≥ 16 上会打开 C++26 反射(`-freflection`)与契约；Clang/libc++ 上追加 `-fexperimental-library`；不支持的门会跳过并打印 summary。刻意是工具链相关的——最前沿的试验场模式，永远不要用于发布包。
-
-两条需要知道的性质：
-
-- **标准是模块图全局的。** 根包的 `standard` 作用于本次构建的每一个 TU，依赖也不例外——
-  依赖自己 manifest 里的 `standard` 在它作为依赖被构建时不生效。这不是简化：BMI 跨档位
-  不兼容(GCC 直接报 `language dialect differs`)，同一张图物理上不可能存在两个档位。
-- **档位之间从不共用缓存。** 标准同时进入 fingerprint、`import std` 的 BMI 身份和依赖构建
-  缓存键，所以在 `c++20` 与 `c++23` 之间切换只会各自拿到独立的产物目录和独立的 std BMI，
-  不会出现错误命中。
-
-如果源码在某个档位上 `import std;` 而解析出的工具链在该档位不提供 `std` 模块，
-mcpp 会在编译前失败，并同时报出工具链与工程档位。
-
-值的两种拼法都接受:`standard = "c++26"` 与 `standard = 26`。
-
-当**依赖声明的档位高于当前图**时,mcpp 会在编译前说出来,而不是让它在那个依赖的源码里
-某处失败。见 [workspace §4.2](07-workspace.md)。
-
-`[package.metadata.<tool>]`(mcpp 2026.9.16.1+)是引擎保留但不解释的表。它是包对自身的
-陈述,供读取它的工具使用,例如收集每个库贡献内容的框架;它通过 `mcpp::graph_file()` 到达根包
-的构建程序([30 —— build.mcpp](30-build-mcpp.md))。其中的路径由读取方相对于该包的清单目录
-解析。`[package]` 中 mcpp 不读取的其他键会被报告,与 `[build]` 一致:给出警告,在 `--strict`
-下报错(2026.9.16.1+)。
+`standard` 是 C++ 语言标准的一等设置。推荐取值：
+
+- `c++23`：默认值，与当前以模块为基础的默认模板相配。
+- `c++20`：mcpp 接受的最低档位——具名模块是 C++20 的特性，所以在这套构建
+  模型里，低于它就没有意义可言。当外部约束（较旧的内部规定、只支持到
+  C++20 的第三方 API）迫使档位下降时使用它。`import std;` 在这一档同样
+  可用：它本是 C++23 的**库**特性，但 GCC（≥ 15）、Clang + libc++（≥ 17）
+  与 MSVC STL（VS 2022 17.8 起）在 C++20 模式下都同样提供 `std` 模块。
+  注意 C++23 的库设施（`std::print`、`std::expected` 等）在这一档不可用，
+  `mcpp new` 生成的代码也不例外。
+- `c++26`：用于 C++26 的语言特性。
+- `c++2a` / `c++2c`：兼容别名，解析后归一化为 `c++20` / `c++26`。
+- `gnu++20` / `gnu++23` / `gnu++26`：GNU 方言；这个选择会进入指纹与 std
+  BMI 的缓存键。
+- `c++latest`：解析为所用工具链支持的最新标准档位。适合本地实验，但不
+  推荐用在要求可复现的发布包上。
+- `c++fly`：`c++latest` **加上所用工具链能启用的每一项实验性标准特性**
+  （语言特性加标准库）。在 GCC ≥ 16 上会打开 C++26 反射（`-freflection`）
+  与 contracts；在 Clang/libc++ 上会加上 `-fexperimental-library`；工具链
+  不支持的开关会被跳过并打印一份摘要。它刻意依赖具体工具链——这是最
+  前沿的试验场模式，绝不用于已发布的包。
+
+两条值得了解的性质：
+
+- **标准是模块图全局的。** 根包的 `standard` 适用于构建中的每一个翻译
+  单元，包括依赖——依赖自身的 `standard`，在它作为依赖被构建时不会被
+  使用。这不是一种简化：BMI 在不同档位之间不兼容（GCC 会报
+  `language dialect differs` 拒绝它），所以一张图在物理上无法同时容纳
+  两个档位。
+- **档位之间从不共享缓存。** 标准是指纹、`import std` BMI 身份与依赖
+  构建缓存键的一部分，所以在 `c++20` 与 `c++23` 之间切换，会让每个档位
+  拿到自己独立的 target 目录与自己独立的 std BMI，而不是一次损坏的命中。
+
+若源码在所用工具链未提供 `std` 模块的档位上写了 `import std;`，mcpp 会
+在编译之前失败，并同时点出工具链与工程档位两者。
+
+字段值的两种写法都被接受：`standard = "c++26"` 与 `standard = 26`。
+
+当**某个依赖声明的档位高于全图的档位**时，mcpp 会在编译之前说明这一点，
+而不是任由构建在那个依赖的源码内部某处失败。见
+[workspace §4.2](07-workspace.md)。
+
+`[package.metadata.<tool>]`（mcpp 2026.9.16.1+）是一张引擎保留、但不解读
+的表。它是这个包对自身的陈述，供读取它的工具使用——例如某个框架收集
+每个库贡献了什么——并通过 `mcpp::graph_file()` 到达根包的构建程序
+（[30 —— build.mcpp](30-build-mcpp.md)）。表中的路径由那个读取者相对包的
+manifest 目录解析。`[package]` 中 mcpp 不读取的任何其它键都会被报告，与
+`[build]` 中的处理一致：一条警告，在 `--strict` 下则是错误
+（2026.9.16.1+）。
 
 ```toml
 [package.metadata.demo]
@@ -97,22 +117,23 @@ resources = "res"
 
 #### 方言标志与 `import std` BMI
 
-有些标志会改变标准库头文件**声明出什么**,因此预编译的 `import std` BMI 也必须带着它们一起
-构建。这就是 `[build] dialect_cxxflags` 的用途:它会被施加到 std BMI 预编译、模块扫描
-**以及**图中每一个 TU(依赖也包括在内)。
+有些标志会改变标准库头文件的声明内容，所以预编译的 `import std` BMI 也
+必须用它们一起构建。这正是 `[build] dialect_cxxflags` 的用途：它会应用
+于 std BMI 的预构建、模块扫描，**以及**图中的每一个翻译单元，包括依赖。
 
 ```toml
 [build]
 dialect_cxxflags = ["-fno-exceptions"]
 ```
 
-其中少数几个标志,mcpp 在 `cxxflags` 里发现时会自动提升进这条通道
-(`-freflection`、`-fchar8_t`、`-D_GLIBCXX_USE_CXX11_ABI=…`)—— 混用这些标志的图本来就是
-病态的,任何依赖都不可能对它们持有另一种自洽的意见。
+当 mcpp 在 `cxxflags` 中发现某些标志时（`-freflection`、`-fchar8_t`、
+`-D_GLIBCXX_USE_CXX11_ABI=…`），会自动把它们提升进那个通道——一张混用
+了这些标志的图本来就是病态的，所以没有哪个依赖能对它们持不同意见。
 
-`-fno-exceptions` 与 `-fno-rtti` **不会**被自动提升,因为依赖可以合法地不同意:它们移除的是
-依赖可能正在使用的语言设施,而消费者无权替它做这个决定。留在 `cxxflags` 里,它们会到达每一个
-TU 却到不了预编译,于是构建不可能成功 —— mcpp 在编译前就拒绝,并指出该用哪个键:
+`-fno-exceptions` 与 `-fno-rtti` **不会**被提升，因为依赖可以合理地持
+不同意见：它们移除了依赖可能要用到的语言设施，而消费者无权替依赖做这个
+选择。若留在 `cxxflags` 里，它们会到达每一个 TU 却到不了预构建，导致
+构建无法成功——mcpp 会在编译之前拒绝，并点名这个键：
 
 ```
 error: `-fno-exceptions` changes the language dialect, but the `import std` BMI is
@@ -124,43 +145,46 @@ error: `-fno-exceptions` changes the language dialect, but the `import std` BMI
          dialect_cxxflags = ["-fno-exceptions"]
 ```
 
-这项检查读的是**生效后的**标志集合,所以同一个标志写在 `[profile.<name>] cxxflags` 或
-`[target.…]` 块里同样会被抓到。而当图中根本没有 `import std` 时它不触发 —— 那里它就是一个
-正常工作的按 TU 选项。
+这项检查读取的是**生效**标志，所以同一个标志写在
+`[profile.<name>] cxxflags` 或某个 `[target.…]` 块里也会触发。当图里
+没有任何单元 import `std` 时不会触发，此时该标志只是一个正常生效的按
+单元选项。
 
-### 2.2 `[targets.<name>]` — 构建目标
+### 2.2 `[targets.<name>]` —— 构建目标
 
 ```toml
-# 可执行程序(默认,有 src/main.cpp 时自动推断)
+# Executable (default; inferred automatically when src/main.cpp exists)
 [targets.myapp]
 kind = "bin"
-main = "src/main.cpp"       # 可选,默认 src/main.cpp
+main = "src/main.cpp"       # Optional, defaults to src/main.cpp
 
-# 静态库
+# Static library
 [targets.mylib]
 kind = "lib"
 
-# 共享库
+# Shared library
 [targets.mylib]
 kind = "shared"
-soname = "libmylib.so.1"  # 可选: Linux/ELF ABI 名称,运行时会生成同名 alias
+soname = "libmylib.so.1"  # Optional: Linux/ELF ABI name; an alias of the same name is generated at runtime
 ```
 
-`soname` 用于共享库的 ABI 名称,类似 Autotools/CMake 中的
-`SOVERSION`/`SONAME`。在 Linux 上,mcpp 会向链接器传递
-`-Wl,-soname,<name>`,并在输出目录生成 `<name> -> lib<target>.so` alias,
-让下游程序可通过标准 ABI 名称 `DT_NEEDED` 或 `dlopen()` 加载该库。
-该字段只对 `kind = "shared"` 有效,值必须是文件名 basename。未声明 `soname`
-的 ELF 共享库以输出文件名作为 SONAME(2026.9.14.2+),这正是消费者已经记录在
-`DT_NEEDED` 中的名字;bionic 自 API level 23 起要求共享库带有 SONAME。
+`soname` 是共享库的 ABI 名，相当于 Autotools/CMake 里的
+`SOVERSION`/`SONAME`。在 Linux 上，mcpp 会向链接器传入
+`-Wl,-soname,<name>`，并在输出目录生成一个 `<name> -> lib<target>.so`
+的别名，使下游程序能通过 `DT_NEEDED` 或 `dlopen()`，按其标准 ABI 名加载
+这个库。这个字段只对 `kind = "shared"` 生效，取值必须是一个文件名
+（不含路径）。一个未声明 `soname` 的 ELF 共享库，会把自己的输出文件名
+记为自己的 SONAME（2026.9.14.2+）——这正是它的消费者已经记录在
+`DT_NEEDED` 里的那个名字；bionic 从 API level 23 起要求必须有这个名字。
 
-共享库目标在三种二进制格式上都可用。ELF 产出带 `soname` 的 `.so` 与 `$ORIGIN`
-搜索路径;Mach-O 产出 install name 为 `@rpath/<file>` 的 `.dylib`,因此移动后
-仍能被找到;PE 同时产出加载器打开的 `.dll` 和链接器消费的 import library,并在
-MSVC ABI 上从对象生成导出表(该 ABI 没有 `__declspec(dllexport)` 或 `.def` 时
-不导出任何符号)。参见 `tests/e2e/08`、`257`、`259`。
+共享库目标在全部三种二进制格式上都能工作。ELF 得到一个带 `soname` 和
+`$ORIGIN` 搜索路径的 `.so`；Mach-O 得到一个 install name 为
+`@rpath/<file>` 的 `.dylib`，因此即使被移动位置也仍然有效；PE 同时得到
+loader 打开的 `.dll` 与链接器消费的导入库，导出列表从对象文件按 MSVC
+ABI 生成（不带 `__declspec(dllexport)` 或 `.def` 时什么都不导出）。见
+`tests/e2e/08`、`257` 与 `259`。
 
-#### `kind = "app"` —— 用户启动的那个东西(mcpp 2026.9.12.3+)
+#### `kind = "app"` —— 用户启动的那个东西（mcpp 2026.9.12.3+）
 
 ```toml
 [targets.myapp]
@@ -168,92 +192,102 @@ kind = "app"
 main = "src/main.cpp"
 ```
 
-`app` 在每一行上表达同一件事——用户启动的程序——而每一行为它提供各自的文件:
+`app` 在每一行上命名的是同一个事实——用户启动的那个程序——而每一行
+为它提供自己的文件形式：
 
-| 行 | `app` 的形态 | 文件 |
+| 行 | `app` 的形式 | 文件 |
 |---|---|---|
-| ELF、PE、Mach-O 各行,`wasm32-emscripten` | 与 `bin` 相同 | `myapp`、`myapp.exe`、`myapp.js` |
+| ELF、PE、Mach-O 各行，`wasm32-emscripten` | 与 `bin` 相同 | `myapp`、`myapp.exe`、`myapp.js` |
 | `*-linux-android` | 与 `shared` 相同 | `libmyapp.so` |
 
-在 `*-linux-android` 上,平台把应用程序作为共享库加载进一个 Java 进程
-(`System.loadLibrary("myapp")`、manifest 里的 `android:name`);这一行上不存在
-应用程序的可执行形态。在其余每一行上,`app` 的链接方式与 `bin` 完全相同,产物
-与 `bin` 目标逐字节相同。
+在 `*-linux-android` 上，平台把一个应用当作共享库加载进一个 Java 进程
+（`System.loadLibrary("myapp")`，manifest 里的 `android:name`）；这一行上
+没有可执行文件形式的应用。在其余每一行上，`app` 的链接方式与 `bin`
+完全相同，产出的文件与 `bin` 目标的产物逐字节相同。
 
-`main` 在每一行上保持同一含义:它指出定义入口点的翻译单元。在 `app` 是可执行文件
-的那些行上,该入口就是 `main` 本身。在 `*-linux-android` 上,这个文件被编译为共享库
-的一个翻译单元,平台自己的入口(`ANativeActivity_onCreate`,或它声明的 JNI 导出)
-是平台的契约,不是 mcpp 指定的名字。`exports`(见上)对 `app` 目标的适用方式与对
-`shared` 完全相同;`windows_subsystem` / `windows_entry`(见下)接受 `app` 的方式
-与接受 `bin` 完全相同。
+`main` 在每一行上都保持同一个含义：它命名定义入口点的翻译单元。当
+`app` 是一个可执行文件时，那个入口就是 `main` 本身。在 `*-linux-android`
+上，这个文件被编译为共享库的一个翻译单元，平台自己的入口
+（`ANativeActivity_onCreate`，或它声明的 JNI 导出）是平台自己的契约，
+不是 mcpp 分配的名字。`exports`（见上）对 `app` 目标的适用方式与对
+`shared` 目标完全相同，`windows_subsystem` / `windows_entry`（见下）
+接受 `app` 的方式也与接受 `bin` 完全相同。
 
-在 `app` 的形态是共享库的那一行上,不带 `--format` 运行 `mcpp run` 会被拒绝,拒绝信息
-指出该旗标以及已解析图提供的格式集合。`mcpp pack --format apk` 把这个库放到闭包已经
-安放共享对象的位置。参见 [10 — 打包与发布](10-pack-and-release.md)里的 `mcpp run
---format`。
+在其形式为共享库的那一行上，`mcpp run` 一个 `app` 目标，若不带
+`--format` 会拒绝执行，并点名这个旗标与所解析出的图提供的那些格式。
+`mcpp pack --format apk` 会把这个库放到闭包已经放置共享对象的位置。见
+[10 —— 打包与发布](10-pack-and-release.md)中的 `mcpp run --format`。
 
-早于 2026.9.12.3 的引擎不认识这个取值,按名字拒绝,并列出它认识的三种:
+早于 2026.9.12.3 的引擎不认识这个取值，会拒绝并点名它认识的三种：
 
 ```
 targets.myapp.kind must be 'bin', 'lib' or 'shared'; got 'app'
 ```
 
-#### `exports` —— 产物发布的符号集合(mcpp 2026.9.6.5+)
+#### `exports` —— 产物发布的符号集合（mcpp 2026.9.6.5+）
 
 ```toml
 [targets.mydriver]
 kind    = "shared"
 soname  = "libmydriver.so.1"
-exports = "abi/mydriver.exports"     # 或内联:exports = ["vk_icd*"]
+exports = "abi/mydriver.exports"     # or inline: exports = ["vk_icd*"]
 ```
 
-**不写这个键就发布全部,而那正是两个平台今天的默认**——ELF 给符号默认可见性,PE 会
-自动生成列出全部符号的 `.def`。`exports` 把它收窄。
+**省略这个键会发布一切，而这恰好是两个平台本来就在做的事**——ELF 给
+符号默认可见性，PE 自动生成一份列出每个符号的 `.def`。`exports` 收窄
+这个范围。
 
-两类工程需要收窄。**有稳定 ABI 的运行时**只发布一份经过评审的集合,不在集合里的东西
-才保持可改。**与同类并存的插件**不能撞名:Vulkan loader 按名字找
-`vk_icdGetInstanceProcAddr`,一个把内部符号也导出的 ICD 会与 loader 以及同进程内另一个
-ICD 相撞。
+两类工程需要这种收窄。**带稳定 ABI 的运行时**只发布一份经过审查的
+集合，其余一概不发布，让不在集合里的东西保留自由变化的空间。**与同类
+插件并存加载的插件**不能相撞：一个 Vulkan ICD 是按名字被找到
+`vk_icdGetInstanceProcAddr` 的，若它同时导出自己的内部符号，就会与
+loader 以及进程中的其它 ICD 相撞。
 
-文件一行一条符号模式,`#` 起注释,`*` 是唯一的通配符。内联数组说的是同一件事,用于
-只有两三个入口、单开一个文件反而是仪式的场合。
+这个文件每行列一个符号模式，`#` 起一行注释，`*` 是唯一的通配符。内联
+数组说的是同一件事，用于只有两三个入口点、单独开一个文件显得多余的场合。
 
-一句话,三种渲染:
+一句陈述，三种渲染：
 
 | 平台 | 渲染为 |
 |---|---|
-| ELF | version script,`-Wl,--version-script=` |
-| Mach-O | `-Wl,-exported_symbols_list`(前导下划线由引擎补) |
-| PE | `.def`,取代自动生成的全导出版本 |
+| ELF | 一份 version script，`-Wl,--version-script=` |
+| Mach-O | `-Wl,-exported_symbols_list`（前导下划线由引擎补上） |
+| PE | 那份 `.def`，替换自动生成的、导出一切的那一份 |
 
-**它不改变编译期可见性,这是有意的。** 三种格式上收窄都是链接期属性,所以一个键只有
-一个效果。`-fvisibility=hidden` 仍可经 `[build] cxxflags` 使用以取得代码生成上的收益,
-而它是一个**单独**的决定,因为它同时改变本库各翻译单元之间如何看见彼此。
+**它不改变编译期可见性，这是刻意的。** 这种收窄在全部三种格式上都是
+链接期属性，所以一个键只有一种效果。`-fvisibility=hidden` 仍可通过
+`[build] cxxflags` 使用，以获取它带来的代码生成收益，它是一个独立的
+决定，因为它同时改变这个库自己的翻译单元之间彼此可见的方式。
 
-**符号版本化不是这个键。** `foo@@LIB_1.0` 与 `foo@LIB_0.9` 并存是 ELF 独有的能力,
-无法中立表达;需要它的包自己写 version script 经 `[build] ldflags` 传入,或者算出来后
-用 `mcpp:link-flag=` 发出(docs/07)。
+**符号版本化不是这个键管的事。** `foo@@LIB_1.0` 与 `foo@LIB_0.9` 并存，
+是一种只有 ELF 才有、无法中立表达的能力；需要它的包自己写 version
+script 并通过 `[build] ldflags` 传入，或者自行计算并发出
+`mcpp:link-flag=`（docs/07）。
 
-`soname` 对 `kind = "lib"` 同样有意义 —— 见下文的 `dependency_linkage`,
-库以何种形态出现是**消费者**的决定。
+`soname` 在 `kind = "lib"` 上同样有意义——见下文的
+[`dependency_linkage`](#dependency_linkage--静态还是动态由消费者决定)，
+在那里，一个库采取的形式变成消费者的决定。
 
-#### `windows_subsystem` 与 `windows_entry` —— Windows GUI 可执行文件(mcpp 2026.9.12.2+)
+#### `windows_subsystem` 与 `windows_entry` —— Windows GUI 可执行文件（mcpp 2026.9.12.2+）
 
 ```toml
 [targets.myapp]
 kind              = "bin"
 main              = "src/main.cpp"
-windows_subsystem = "windows"   # "console"(默认)| "windows"
-windows_entry     = "main"      # "main"(默认)| "wmain" | "WinMain" | "wWinMain"
+windows_subsystem = "windows"   # "console" (default) | "windows"
+windows_entry     = "main"      # "main" (default) | "wmain" | "WinMain" | "wWinMain"
 ```
 
-PE 可执行文件记录一个子系统。`"console"` 为程序附加控制台,`"windows"` 产生启动时不带控制台的
-GUI 程序。`windows_entry` 指程序定义的函数,而不是调用该函数的启动符号;它与子系统相互独立:控制台
-程序可以定义 `wmain`,GUI 程序也可以保留可移植的 `int main()`。
+一个 PE 可执行文件记录一个 subsystem。`"console"` 附带一个控制台，
+`"windows"` 产出一个启动时没有控制台的 GUI 程序。`windows_entry` 命名
+的是程序自己定义的函数，不是调用它的启动符号，它独立于 subsystem 之外：
+一个控制台程序可以定义 `wmain`，一个 GUI 程序也可以保留可移植的
+`int main()`。
 
-这两个键是字段而不是链接标志,原因是正确的标志取决于 ABI,而一条标志无法说明自己面向哪个 ABI:
+这两个键之所以是字段而不是链接旗标，是因为正确的旗标取决于 ABI，而一个
+旗标说不出它面向哪个 ABI：
 
-| `windows_subsystem` / `windows_entry` | MSVC ABI(cl、clang-cl、面向 `*-windows-msvc` 的 clang) | GNU ABI(MinGW gcc、面向 `*-windows-gnu` 的 clang) |
+| `windows_subsystem` / `windows_entry` | MSVC ABI（cl、clang-cl、目标为 `*-windows-msvc` 的 clang） | GNU ABI（MinGW gcc、目标为 `*-windows-gnu` 的 clang） |
 |---|---|---|
 | `"console"` / `"main"` | 无 | 无 |
 | `"windows"` / `"main"` | `/SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup` | `-mwindows` |
@@ -261,121 +295,137 @@ GUI 程序。`windows_entry` 指程序定义的函数,而不是调用该函数
 | `"windows"` / `"wWinMain"` | `/SUBSYSTEM:WINDOWS /ENTRY:wWinMainCRTStartup` | `-mwindows -municode` |
 | `"console"` / `"wmain"` | `/SUBSYSTEM:CONSOLE /ENTRY:wmainCRTStartup` | `-municode` |
 
-在 MSVC ABI 上,只要任一键偏离默认值,两条标志就都写出。原因是链接器在缺少其中一条时由另一条推断:
-单独的 GUI 子系统会选择 `WinMainCRTStartup`,而可移植的 `int main()` 无法满足它;`/ENTRY:main`
-则会跳过 CRT 初始化,静态构造也随之被跳过。GNU 风格的驱动收到的 MSVC ABI 标志形如
-`-Wl,/SUBSYSTEM:...`。
+在 MSVC ABI 上，只要两个键中任意一个偏离其默认值，两个旗标就都会被
+写出，因为链接器在其中一个缺席时会从另一个推断：单独的 GUI subsystem
+会选中 `WinMainCRTStartup`，而一个可移植的 `int main()` 满足不了它；
+`/ENTRY:main` 会跳过 CRT 初始化，包括静态构造函数。GNU 风格的驱动程序
+以 `-Wl,/SUBSYSTEM:...` 的形式接收 MSVC-ABI 旗标。
 
-这两个键只到达声明它们的目标的链接。同一包的其他可执行文件、`mcpp test` 的测试二进制以及该包的消费者
-都保持控制台子系统;这也是这些标志不应写进 `[build] ldflags` 的原因:该通道到达图中的每一次链接。
-在 ELF、Mach-O 与 WebAssembly 上,这两个键不产生任何标志,产物与未声明它们时逐字节相同,因此跨平台的
-manifest 不需要 `cfg` 块。库目标声明任一键会被拒绝,拒绝信息指出目标与键名。
+这两个键只到达声明它们的目标的链接，不会传播出去。第二个可执行文件、
+`mcpp test` 的二进制，以及这个包的消费者，都保持控制台 subsystem——这
+正是为什么这些旗标不应放进 `[build] ldflags`：那条通道会到达图中的每
+一次链接。在 ELF、Mach-O 与 WebAssembly 上，这两个键不渲染出任何东西，
+产物与未写它们时逐字节相同，所以一份跨平台 manifest 不需要 `cfg` 块。
+一个库目标若声明这两个键中的任意一个都会被拒绝，拒绝信息点名该目标与
+该键。
 
-构建程序通过 `mcpp::windows_subsystem("<target>", "windows")` 与
-`mcpp::windows_entry("<target>", "wmain")` 为本包的可执行文件设置同样的字段
-([build.mcpp](30-build-mcpp.md))。
+一个构建程序可以为自己包里的某个可执行文件设置同样的字段，用
+`mcpp::windows_subsystem("<target>", "windows")` 与
+`mcpp::windows_entry("<target>", "wmain")`（[build.mcpp](30-build-mcpp.md)）。
 
-应用程序包、应用程序清单与 DPI 感知不属于这两个键,它们归属于打包格式与 `[resources]`。
+应用程序包（bundle）、应用程序 manifest 与 DPI 感知不属于这两个键管的
+范围；它们属于打包格式与 `[resources]`。
 
-#### 按目标的键(per-target keys)
+#### 按目标的键（per-target keys）
 
 ```toml
 [targets.server]
 kind     = "bin"
 main     = "src/server.cpp"
-defines  = ["BUILD_SERVER=1", "PORT=8080"]   # -D 宏,只作用于该目标的入口
-cxxflags = ["-Wno-deprecated-declarations"]  # 该目标入口的额外 C++ 标志(不要放 -std=...)
-cflags   = ["-DPURE_C"]                       # 该目标入口的额外 C 标志
+defines  = ["BUILD_SERVER=1", "PORT=8080"]   # -D macros, applied to this target's entry only
+cxxflags = ["-Wno-deprecated-declarations"]  # extra C++ flags for this target's entry (no -std=...)
+cflags   = ["-DPURE_C"]                       # extra C flags for this target's entry
 
 [targets.gui]
 kind = "bin"
 main = "src/gui.cpp"
-required_features = ["gui"]                   # 仅当 feature `gui` 激活时才构建
+required_features = ["gui"]                   # only built when feature `gui` is active
 ```
 
 | 键 | 含义 |
 |---|---|
-| `defines` | 预处理宏(`name` 或 `name=value`),脱糖为 `-D<x>`,作用于该目标入口的 C 与 C++ 编译。 |
-| `cxxflags` / `cflags` | 该目标的额外编译标志。**不要**放 `-std=...`——用 `[package].standard`。 |
-| `required_features` | 仅当列出的 feature **全部**激活时才生成该目标,否则静默跳过。只是门禁——不激活 feature(用 `--features` / `[features].default`)。 |
-| `windows_subsystem` *(2026.9.12.2+)* | 可执行文件的 PE 子系统:`"console"`(默认)或 `"windows"`(启动时不带控制台的 GUI 程序)。只到达该目标的链接,在非 PE 目标上不产生任何标志。见上一节。 |
-| `windows_entry` *(2026.9.12.2+)* | 程序定义的入口函数:`"main"`(默认)、`"wmain"`、`"WinMain"` 或 `"wWinMain"`。见上一节。 |
-| `linkage` *(2026.9.15.2+)* | 库目标的**默认**链接形态,`"static"` 或 `"shared"`:不写 `linkage` 的消费者得到的形态。它不同于 `kind = "shared"`,不是约束,因此消费者的显式陈述会被遵从。与 `kind = "shared"` 同写或写在程序目标上会被拒绝。见 [`dependency_linkage`](#dependency_linkage--静态还是动态由消费者决定)。 |
-
-> **作用域(重要):** 目标上的 `defines` / `cxxflags` / `cflags` **只作用于该目标独占的入口源**
-> (它的 `main`)——**绝不**作用于共享的模块/实现对象(那些只编译一次、被每个目标链接,即 mcpp 的
-> compile-once 模型)。当标志只需影响某个二进制(或测试)**自己的入口**时,这正是合适的工具 ——
-> 例如某个测试的 `main` 里触发契约违规、需要按测试设置契约求值语义
-> (`-fcontract-evaluation-semantic=observe`),或入口独享的 feature 宏、局部告警抑制。
-> 若标志必须穿透**共享**代码,就不该放在这里 —— 改用 [workspace](07-workspace.md) member 或
-> `[features]`;若是整次构建的模式,用 `[profile.*]`(`mcpp test --profile <name>` 会让包括被测
-> 代码在内的整个测试镜像都在该 profile 下编译)。
+| `defines` | 预处理宏（`name` 或 `name=value`）；在 C 与 C++ 两种入口编译上都脱糖为 `-D<x>`。 |
+| `cxxflags` / `cflags` | 这个目标专用的额外编译旗标。**不要**把 `-std=...` 写在这里——用 `[package].standard`。 |
+| `required_features` | 只有当构建中**每一个**列出的 feature 都被激活时，这个目标才会被产出；否则被静默跳过。它只是一道闸——不会激活 feature（用 `--features` / `[features].default`）。**一个例外，但它不是第二条规则：** 当这个目标作为 host 工具被请求时（`tools = [...]`，§2.14），这个目标就是被**请求**的那一个，于是它的 `required_features` 变成子构建的**输入**。同一个字段、同一个含义——只是解析的方向反过来了。 |
+| `windows_subsystem` *（2026.9.12.2+）* | 可执行文件的 PE subsystem：`"console"`（默认）或 `"windows"`，一个启动时没有控制台的 GUI 程序。只到达这个目标的链接，别处不受影响，在非 PE 的目标上不渲染任何东西。见上一节。 |
+| `windows_entry` *（2026.9.12.2+）* | 程序定义的入口函数：`"main"`（默认）、`"wmain"`、`"WinMain"` 或 `"wWinMain"`。见上一节。 |
+| `linkage` *（2026.9.15.2+）* | 一个库目标的**默认**链接形态，`"static"` 或 `"shared"`：不写 `linkage` 的消费者得到的形态。与 `kind = "shared"` 不同，它不是约束，因此消费者的显式陈述会被遵从。与 `kind = "shared"` 同写，或写在程序目标上，都会被拒绝。见[`dependency_linkage`](#dependency_linkage--静态还是动态由消费者决定)。 |
+
+> **范围（重要）：** 目标上的 `defines` / `cxxflags` / `cflags` **只**
+> 应用于该目标专属的入口源文件（它的 `main`）——绝不应用于共享的
+> 模块/实现对象，后者只编译一次，并链接进每一个目标（mcpp 的一次编译
+> 模型）。当一个旗标只需要影响单个二进制（或测试）自己的入口时，这两个
+> 键是正确的工具——例如某个测试的 `main` 专门触发违规，需要按测试设置
+> contract 求值语义（`-fcontract-evaluation-semantic=observe`）；或者
+> 只有入口会读到的一个 feature 宏；或者一次局部的警告抑制。如果一个
+> 旗标必须到达**共享**代码，就不属于这里——要么拆成一个
+> [workspace](07-workspace.md) 成员，要么用 `[features]`；若是整个构建
+> 范围的模式，用 `[profile.*]`（`mcpp test --profile <name>` 会在那个
+> profile 下构建整份测试镜像，包括被测代码）。
 >
-> `[targets.<name>]` 下的不支持键会产生 warning(`--strict` 下为 error)。
+> `[targets.<name>]` 下不受支持的键会被报告为警告（`--strict` 下为
+> 错误）。
 
-**构建配置该放哪** —— 当多个二进制需要不同配置时:
+**构建配置该放在哪里**——当不止一个二进制必须有所不同时：
 
-| 目标 | 使用 |
+| 目的 | 做法 |
 |---|---|
-| 某二进制**自己入口**上的不同宏/标志 | per-target `defines` / `cxxflags`(见上) |
-| 两个产品差异在它们**共享**的代码里 | 拆成 [workspace](07-workspace.md) member,各自 `[build]` 标志,共享一个 `lib` |
-| **选择**某共享库的变体(如某后端) | 在该库上用 `[features]`(§2.8)——additive,作用到库自己的编译 |
-| **整次构建的模式**(sanitizer、契约语义、优化档) | `[profile.<name>]`(§2.9)+ `--profile`;`mcpp test --profile <name>` 同样支持 |
-
-mcpp 刻意不在一次构建里把同一个共享源编译成两份:一个源对应一个对象(模块还对应一个 BMI),
-所以"必须穿透共享代码"的差异应放在包/feature 边界,而非单个目标上。
-
-### 2.3 `[build]` — 构建配置
-
-> **`sources` 匹配到的每一项都必须产出一个会被链接的对象。** mcpp 放不下的文件 ——
-> 扩展名既不在内建表也不在 `module_extensions` 里 —— 会被拒绝,并点名文件、
-> 扩展名与该写的键。**不是忽略**:催生这条规则的失败不是「多编了一个文件」,
-> 而是**编了却没人链** —— 扫描器读到 `export module` 就给那条边挂了 BMI,
-> 而分类器说这个文件没有角色,作者看到的是一条模块修饰过的 `undefined reference`。
-> 头文件应放进 `include_dirs`,Windows 资源脚本放进 `[resources]`。
-
-> **`sources = []` 与不写 `sources` 不是一回事。** 不写这条键选择默认 glob;
-> 显式的空列表意味着**什么都不编** —— 那正是一个纯头文件的分发包需要表达的。
-> 在 mcpp 2026.8.18.1 之前两者逐字节等价,于是「什么都不编」无从表达,
-> `src/` 下剩下的任何文件都会被扫进来。
-
-
-> **`sources` 的条目可以带上它所面向的加速器**(2026.9.5.2+):
-> `{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`。glob 与其它条目一样
-> 进入列表;约束决定它是否适用于某一次构建。它必须至少匹配一个文件(空匹配会被拒绝:
-> 那会让这个设备无东西可编,而只在链接时才说话)。`--no-accel` 下该 glob 被排除,
-> 一个工程由此产出它的 CPU-only 变体。`--accel` 未覆盖该约束时构建被拒并给出两侧
-> (`accel-mismatch`)。有效集合匹配到的设备类源文件 —— CUDA 与 HIP、GLSL 各 stage、
-> HLSL、OpenCL C 与 Metal,完整清单见 [42 — 异构硬件构建](42-heterogeneous-builds.md) —— 引擎
-> 从不编译;它们以 `MCPP_DEVICE_SOURCES` 到达构建程序,由工程引入的规则包把每一个
-> 变成一条 `mcpp::action`。
+| 二进制**自己入口**上不同的宏/旗标 | 按目标的 `defines` / `cxxflags`（见上） |
+| 两个产物在**共享**代码上有差异 | 拆成 [workspace](07-workspace.md) 成员，各自在共享的 `lib` 之上有自己的 `[build]` 旗标 |
+| **选择一个变体**的共享库（例如某个后端） | 用该库上的 `[features]`（§2.8）——是增量的，到达库自己的编译 |
+| **整个构建范围**的模式（sanitizer、contract 语义、优化档位） | `[profile.<name>]`（§2.9） + `--profile`；`mcpp test --profile <name>` 同样尊重它 |
+
+mcpp 刻意不在一次构建里用两种方式编译同一份共享源码：一个源文件对应
+一个对象（模块对应一个 BMI），所以凡是必须到达共享代码的分歧，都属于
+包/feature 的边界，不属于单个目标。
+
+### 2.3 `[build]` —— 构建配置
+
+> **每一条 `sources` 匹配到的文件都必须产出一个会被链接的对象。** 一个
+> mcpp 无法归类的文件——扩展名既不在内置集合里，也不在
+> `module_extensions` 里——会被拒绝，拒绝信息点名文件、扩展名与这个键。
+> 它不会被忽略，因为催生这条规则的失败不是「多出一个文件」，而是**被
+> 编译了却没有人链接它**：扫描器读到 `export module` 并给这条边一个
+> BMI，而分类器却说这个文件没有角色，作者看到的是对一个模块修饰符号的
+> `undefined reference`。头文件属于 `include_dirs`；Windows 资源脚本
+> 属于 `[resources]`。
+
+> **`sources = []` 与省略 `sources` 不是一回事。** 缺失这个键会选中
+> 默认 glob；显式的空列表意味着**什么都不编译**，这正是一个纯头文件
+> 分发包需要表达的意思。在 mcpp 2026.8.18.1 之前两者逐字节相同，所以
+> 没有拼法能表达「什么都没有」，`src/` 下留下的任何文件都会被卷进来。
+
+> **一条 `sources` 条目可以携带它所面向的加速器**（2026.9.5.2+）：
+> `{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`。glob
+> 像其它条目一样加入这份列表；约束决定它是否适用于某次给定的构建。它
+> 必须至少匹配一个文件（空匹配会被拒绝：那会让这个设备没有东西可编译，
+> 却要等到链接阶段才说出来）。在 `--no-accel` 下这条 glob 会被排除，
+> 这正是一个工程产出自己 CPU-only 变体的方式。在一个不覆盖该约束的
+> `--accel` 下，构建会被拒绝并点名两者（`accel-mismatch`）。生效集合
+> 匹配到的设备类文件——CUDA 与 HIP、GLSL 各阶段、HLSL、OpenCL C 与
+> Metal，完整列表见[42 —— 异构构建](42-heterogeneous-builds.md)——从不
+> 由引擎编译；它们以 `MCPP_DEVICE_SOURCES` 的形式到达构建程序，工程
+> import 的规则包把每一个都变成一个 `mcpp::action`。
 
 ```toml
 [build]
-sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # 源文件 glob(默认: src/**/*.{cppm,cpp,cc,c,S,s,asm})
-module_extensions = [".ixx"]      # 模块**接口**额外使用的扩展名(见下节)
-build_program_timeout = 1800      # build.mcpp 的运行上限(秒);0 = 不限(见下节)
-include_dirs = ["include", "third_party/include"]  # 头文件搜索路径
-include_dirs_after = ["*"]         # 排在系统目录之后搜索的头文件目录(-idirafter)
-private_include_dirs = ["vendor/src/include"]  # `include_dirs` 中不发布给消费者的那些
-c_standard   = "c11"              # C 源文件的标准(默认 c11)
-cflags       = ["-DFOO=1"]        # 额外 C 编译参数
-cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数(不要放 -std=...)
-ldflags      = ["-lfoo"]          # 额外链接参数
-defines      = ["BIZ=1", "QUX"]   # 作用于每个 TU 的预处理宏(脱糖为 -D;会进入模块扫描)
-cxx_runtime  = "self-contained"   # C++ 运行时契约(见下节);static_stdlib 是旧拼写
-macos_deployment_target = "14.0"   # macOS 产物的最低支持系统版本(仅 macOS 生效)
-dependency_linkage = "static"     # 依赖以何种形态进入:static(默认)| shared(见下文)
-cache        = "global"           # 依赖的全局构建缓存:global(默认)| local | off(见 §2.10)
-jobs         = "auto"             # 并发编译数:正整数,或 "auto"(见下节)
-bmi_schedule = "auto"             # 模块边调度:auto(= 关)| on | off(见下节)
+sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # Source globs (default: src/**/*.{cppm,cpp,cc,c,S,s,asm})
+module_extensions = [".ixx"]      # Extra extensions used by module INTERFACES (§ below)
+build_program_timeout = 1800      # Seconds a build.mcpp may run; 0 = no limit (§ below)
+include_dirs = ["include", "third_party/include"]  # Header search paths
+include_dirs_after = ["*"]         # Header dirs searched AFTER system dirs (-idirafter)
+private_include_dirs = ["vendor/src/include"]  # Of `include_dirs`, the ones a consumer must NOT get
+c_standard   = "c11"              # Standard for C source files (default c11)
+cflags       = ["-DFOO=1"]        # Extra C compile flags
+cxxflags     = ["-DBAR=2"]        # Extra C++ compile flags (do not put -std=... here)
+ldflags      = ["-lfoo"]          # Extra link flags
+defines      = ["BIZ=1", "QUX"]   # Preprocessor macros for every TU (desugars to -D; reaches module scans)
+cxx_runtime  = "self-contained"   # C++ runtime contract (§ below); static_stdlib is the old spelling
+target       = "x86_64-linux-musl" # Default build target when no --target is passed
+                                   # (≙ cargo build.target; e.g. "ship fully-static")
+macos_deployment_target = "14.0"   # Minimum supported OS version for macOS artifacts (macOS only)
+dependency_linkage = "static"     # How dependencies arrive: static (default) | shared (§ below)
+cache        = "global"           # Global dependency cache: global (default) | local | off (§2.10)
+jobs         = "auto"             # Concurrent compiles: a positive number, or "auto" (§ below)
+bmi_schedule = "auto"             # Module-edge scheduling: auto (= off) | on | off (§ below)
 ```
 
 #### 编译 flag 的写法 *(mcpp 2026.9.17.1+)*
 
-`cflags`、`cxxflags` 与 `asmflags` 的一个元素代表一个或多个编译器参数(下称「词」)。
-写法在每个宿主上相同,也不论列表写在哪里:`[build]`、`[targets.<name>]`、`flags` 的
-glob 条目、feature、`[target.<selector>.build]`、xpkg 描述符,以及构建程序的
+`cflags`、`cxxflags` 或 `asmflags` 里的一个元素代表一个或多个编译器
+参数（「词」）。这套语法在每个宿主上都相同，无论写在哪张表里：
+`[build]`、`[targets.<name>]`、`flags` glob 条目、feature、
+`[target.<selector>.build]` 小节、xpkg 描述符，以及构建程序的
 `mcpp:cflag=` / `mcpp:cxxflag=` 指令。
 
 | 写法 | 编译器收到的词 |
@@ -383,361 +433,411 @@ glob 条目、feature、`[target.<selector>.build]`、xpkg 描述符,以及构
 | `"-O2 -g"` | `-O2`、`-g` |
 | `"-include config.h"` | `-include`、`config.h` |
 | `"'-DNAME=a b'"` 或 `"-I\"my dir\""` | `-DNAME=a b`、`-Imy dir` |
-| `"-DNAME=long long"` | `-DNAME=long long`(见下) |
-| `"-DNAME=\\\"text\\\""` | `-DNAME="text"`(字符串字面量) |
+| `"-DNAME=long long"` | `-DNAME=long long`（见下） |
+| `"-DNAME=\\\"text\\\""` | `-DNAME="text"`（一个字符串字面量） |
 | `"-I/opt/my\\ dir/include"` | `-I/opt/my dir/include` |
 | `"-IC:\\sdk\\include"` | `-IC:\sdk\include` |
 | `"-DNAME=a$b"` | `-DNAME=a$b` |
 
-规则陈述在元素的文本上(TOML 或 Lua 先去掉它们自己的转义):
+以下规则施加于元素的文本上（TOML 或 Lua 已经去掉了它自己的转义之后）：
 
-- 未加引号的空格与制表符分隔词;
-- `'...'` 按字面取到下一个 `'`;
-- `"..."` 按字面取,只有 `\"` 与 `\\` 分别代表 `"` 与 `\`;
-- 引号之外,反斜杠后跟空格、制表符、`"`、`'` 或 `\` 时代表该字符,其余反斜杠按字面;
-- 相邻的带引号与不带引号的片段组成一个词;
-- `$`、`*`、`;`、`|` 等 shell 运算符没有特殊含义;
-- 以 `-D` 或 `/D` 开头且含空格的元素是一个词,按原样取,与此前各版本相同。
+- 不带引号的空格与制表符分隔词；
+- `'...'` 是字面量，直到下一个 `'`；
+- `"..."` 是字面量，只有 `\"` 与 `\\` 分别代表 `"` 与 `\`；
+- 在引号之外，反斜杠之后紧跟空格、制表符、`"`、`'` 或 `\`，代表那个
+  字符本身；其它反斜杠都是字面量；
+- 相邻接触的带引号与不带引号的片段合并成一个词；
+- `$`、`*`、`;`、`|` 以及其它 shell 操作符没有特殊含义；
+- 一个以 `-D` 或 `/D` 开头并含有空格的元素，视为一个词，按字面接受，
+  与以往每一个版本相同。
 
-`defines` 的一个条目是一个值,不按此写法读取:`defines = ["NAME=\"text\""]` 传入的是
-一个词 `-DNAME="text"`。`ldflags`、`dialect_cxxflags` 与 `std-module-flags` 不在本节范围内。
+一条 `defines` 条目是一个值，不受这套语法解析：`defines =
+["NAME=\"text\""]` 传出单独一个词 `-DNAME="text"`。`ldflags`、
+`dialect_cxxflags` 与 `std-module-flags` 不受本节约束。
 
-`compile_commands.json` 与 `mcpp emit build-database` 在 `arguments` 中列出同样的词,
-不经 shell 即可执行。
+`compile_commands.json` 与 `mcpp emit build-database` 在 `arguments`
+里列出同样的词，可以不经 shell 直接执行。
 
-一个工程的首次规划中,若某个元素的词与 2026.9.17.1 之前的版本在同一宿主上传入的参数不同,
-mcpp 以 `build/flag-words` 警告并给出两者。重复同一规划的构建不再重复该警告。
+在一个工程的首次 plan 时，若某个元素的词与 2026.9.17.1 之前的版本在
+同一宿主上传出的参数不同，mcpp 会在 `build/flag-words` 下发出警告，并
+点名两者。重复同一份 plan 的构建不会重复这条警告。
 
 #### `dependency_linkage` —— 静态还是动态由消费者决定
 
 ```toml
 [build]
-dependency_linkage = "shared"        # 全图默认;缺省即 "static"
+dependency_linkage = "shared"        # whole-graph default; "static" is the default default
 
 [profile.dev]
-dependency_linkage = "shared"        # 按 profile 覆盖
+dependency_linkage = "shared"        # per profile
 
 [dependencies]
-"compat.zlib" = { version = "1.3.2", linkage = "shared" }   # 单个包
+"compat.zlib" = { version = "1.3.2", linkage = "shared" }   # one package
 ```
 
-在 mcpp 2026.8.28.2 之前,一个依赖只有一种形态,而且由**包作者**定死:
-`kind = "lib"` 把它的对象并进每个消费者的链接,`kind = "shared"` 产出真正的
-共享库。这个决定放错了位置。一个库在运行期该不该是独立文件,是**被构建的那个
-程序**的性质 —— 它怎么分发、多久重链一次、进程里是不是已经有人提供了这个库。
+在 mcpp 2026.8.28.2 之前，一个依赖恰好只有一种形态，并且由**包作者**
+选择：`kind = "lib"` 把它的对象合并进每个消费者的链接，`kind = "shared"`
+产出一个真正的共享库。这个决定的归属者选错了。一个库在运行时是否应该
+是一个独立文件，是**正在被构建的那个程序**的属性——它怎样被发布、多久
+被重新链接一次、进程里是否已经有别的东西提供了这个库。
 
-- **`static`**(默认)—— 依赖的对象并进使用它的映像。与 mcpp 一直以来的行为
-  逐字节相同;不写这个键的工程构建结果不变。
-- **`shared`** —— mcpp 把依赖构建成产物旁边的共享库并链接它,由 `$ORIGIN`
-  (ELF)/ `@loader_path`(Mach-O)/ 可执行文件自身目录(PE)保证构建目录
-  移动后仍能找到它。
+- **`static`**（默认）——依赖的对象被合并进使用它的镜像。逐字节等同于
+  mcpp 一直以来的做法；不写这个键的工程，构建方式与以前完全一样。
+- **`shared`**——mcpp 把这个依赖构建成产物旁边的一个共享库并链接到它，
+  通过 `$ORIGIN`（ELF）/ `@loader_path`（Mach-O）/ 可执行文件自己所在
+  的目录（PE）在构建目录被移动之后仍能重新找到它。
 
-**这不是 `[target.<triple>].linkage`**(§2.7.1)。那个键回答的是听起来相同、
-实则关于 **C 库**的问题(musl 的 `-static`、MSVC 的 `/MT`)。两者并不独立,而且
-方向很重要:整链静态的映像没有解释器,根本装不下任何共享对象。因此在 C 库静态
-链接的目标上 —— 这是 **musl 的默认** —— `dependency_linkage = "shared"` 会被
-拒绝,并说明原因。
+**这不是 `[target.<triple>].linkage`**（§2.7.1）。那个键回答的是一个
+听起来相似、但关于 **C 库**的问题（musl 的 `-static` 链接、MSVC
+的 `/MT`）。这两者不是独立的，而且方向很重要：一个完全静态的镜像没有
+解释器，因此根本无法加载共享对象。在一个 C 库以静态方式链接的目标
+上——这是**musl 的默认行为**——`dependency_linkage = "shared"` 会被
+拒绝，并说明原因。
 
-**包可以声明它必须是某一种形态**,而且只在确有理由时:
+**一个包可以声明它必须是某一种形态**，但只能出于真实的理由：
 
-| 包写了 | mcpp 读作 |
+| 包写的内容 | mcpp 的解读 |
 |---|---|
-| `[targets.<n>] kind = "shared"` | *必须* shared —— 进程里会有别人 `dlopen` 它,因此只能有一份(X11、Vulkan loader) |
-| `[target.<sel>.targets.<n>] kind = "shared"` *(2026.9.14.2+)* | 在选择器命中的行上*必须* shared,其余行两种形态都可以([22 —— 目标侧](22-target-side.md)) |
-| `ldflags` 里含 `-L` | *必须* static —— 包携带了 mcpp 没有编译的预构建归档,放不进 mcpp 自己构建的共享对象 |
-| 分发包(`mcpp pack`) | 它实际随包的那些腿,取自 `[[runtime.artifacts]] role` |
-| 其他 | 两种形态都可以 |
+| `[targets.<n>] kind = "shared"` | **必须**是共享的——进程里另有别的东西会 `dlopen` 它，所以只能有一份拷贝（X11、Vulkan loader） |
+| `[target.<sel>.targets.<n>] kind = "shared"` *（2026.9.14.2+）* | 在选择器匹配的那些行上**必须**是共享的，在别处两种形态都可以（[22 —— 目标侧](22-target-side.md)） |
+| `ldflags` 中含 `-L` | **必须**是静态的——包发布了 mcpp 没有编译、也无法放进自己构建的共享对象里的预构建归档文件 |
+| 一个已打包的库（`mcpp pack`） | 它实际发布的那几条腿，来自 `[[runtime.artifacts]] role` |
+| 其它任何情况 | 两种形态都可以 |
 
-`kind = "lib"` **不是**约束:它是默认值,大多数包写下它并没有做任何选择。
-**没有陈述不等于一条陈述。**
+`kind = "lib"` **不是**一种约束：它是默认值，大多数包写它时并没有在做
+选择。没有陈述不等于一种陈述。
 
-**包还可以陈述一个默认值** *(2026.9.15.2+)*,它不是约束:
+**一个包也可以声明一个默认值**（2026.9.15.2+），这不是约束：
 
 ```toml
 [targets.fw]
 kind    = "lib"
-linkage = "shared"                   # 不写 linkage 的消费者得到的形态
+linkage = "shared"                   # the form a silent consumer receives
 
 [target.'cfg(env = "android")'.targets.fw]
-linkage = "shared"                   # 同上,只在选择器命中的行上
+linkage = "shared"                   # the same, on the rows the selector matches
 ```
 
-- 形态按陈述从具体到一般的顺序决定:根工程在该依赖边上的 `linkage`,根工程
-  写下的 `dependency_linkage`(`[build]` 或当前 profile),包的 `linkage`,
-  最后是 `static`。
-- 与包的默认值不同的显式陈述会被遵从。它不是降级,`--strict` 接受它,并由一条
-  信息行(`Linkage`)同时点名两条陈述。
-- 同一张表里同时写 `kind = "shared"` 与 `linkage` 会被拒绝,因为约束没有默认值可言;
-  一行只陈述 `kind` 与 `linkage` 之一,后命中的陈述替换先前的陈述,因此某行的
-  `linkage = "static"` 会把无条件表约束为 `shared` 的包恢复为由消费者选择的形态。
-- 目标无法遵从的默认值(完全静态的映像、freestanding 目标)静默回落,因为没有人
-  要求它。
-- 2026.9.15.2 之前的引擎把 `[targets.<n>] linkage` 报为不支持的键(对依赖静默)
-  并静态链接该包;2026.9.14.2 起的引擎拒绝不含 `kind` 的行表。依赖此键的包应陈述
-  这一引擎下限。
-
-根工程的构建程序通过 `mcpp::dep_linkage("name")` 读取每个依赖在本次构建中的形态
-([30 —— build.mcpp](30-build-mcpp.md)),生成的加载入口或导入声明因此跟随同一个决定。
-
-约束拒绝的请求按包允许的形态链接,并给出一条点名包的陈述的警告
-(`its manifest states [targets.fw] kind = "shared", ...`);`--strict` 下该警告
-成为错误。`mcpp why deps` 报告每个依赖的形态及其原因:`default`、
-`package-default`(2026.9.15.2+)、`requested`、`package-kind`、`row-kind`、
-`packaged`、`no-sources`、`prebuilt-inputs`、`no-loader` 或 `static-libc`(2026.9.14.2+)。
-
-依赖边上的 `linkage` 只在**根工程**的 `[dependencies]` 里生效。依赖图深处的包
-无权决定最终程序的布局;真正必须只有一份共享副本的包,应当在自己的 target 上
-声明。
+- 形态的决定按以下顺序、以最具体的陈述优先：根包在这条依赖边上写的
+  `linkage`，根包写出的 `dependency_linkage`（在 `[build]` 或当前生效
+  的 profile 里），包自己的 `linkage`，以及 `static`。
+- 一处与包默认值不同的显式陈述会被遵从。这不算一种降级，所以
+  `--strict` 接受它，并有一行信息（`Linkage`）点名两处陈述。
+- 在同一张表里同时写 `kind = "shared"` 与 `linkage` 会被拒绝，因为一个
+  约束不会留下默认值可陈述；一行只陈述 `kind` 与 `linkage` 二者之一，
+  后一条匹配的陈述会替换前一条，所以一行上的 `linkage = "static"`，
+  能把某张无条件的表约束为 `shared` 的包，交还给它的消费者去选择形态。
+- 一个目标无法满足的默认值（一个完全静态的镜像、一个 freestanding
+  目标）会无声地回落，因为根本没有人要求过它。
+- 早于 2026.9.15.2 的引擎会把 `[targets.<n>] linkage` 报告为不受支持
+  的键（对依赖是静默的），并把包按静态链接；从 2026.9.14.2 起的引擎会
+  拒绝一张没有 `kind` 的行表。依赖这个键的包应声明这个引擎下限。
+
+根工程的构建程序可以通过 `mcpp::dep_linkage("name")`
+（[30 —— build.mcpp](30-build-mcpp.md)）读到每个依赖在这次构建中采取的
+形态，使生成的 loader 条目或 import 声明遵循同一个决定。
+
+被约束拒绝的一个请求，会按包允许的形态链接，并给出一条点名包的陈述的
+警告（`its manifest states [targets.fw] kind = "shared", ...`）；
+`--strict` 把这条警告变成错误。`mcpp why deps` 报告每个依赖的形态及其
+原因：`default`、`package-default`（2026.9.15.2+）、`requested`、
+`package-kind`、`row-kind`、`packaged`、`no-sources`、
+`prebuilt-inputs`、`no-loader` 或 `static-libc`（2026.9.14.2+）。
+
+按依赖设置的 `linkage`，**只**在根工程自己的 `[dependencies]` 里被
+遵从。图深处的某个包无权决定最终程序如何布局；真正必须是单一共享拷贝
+的包，应该在自己的目标上这样声明。
 
 #### 共享库之下的静态包 *(mcpp 2026.9.16.1+)*
 
-共享库与它到达的静态包链接在一起。一次构建中的每个共享映像都有一个**静态闭包**:
-从它的包出发、不穿过另一个共享包所能到达的静态包。一个静态包若恰好只在一个闭包里,
-而根工程自己并不到达它,它就链接进那个映像,而不进程序。
+一个共享库与它所触达的静态包一起被链接。一次构建里，每一份共享镜像都
+有一个**静态闭包**：从它的包出发、不跨越另一个共享包所能到达的所有
+静态包。一个只处在**一个**闭包里、根工程自己又碰不到的静态包，会被
+链接进那份镜像，而不是进程序本身。
 
-2026.9.16.1 之前,这样的包进的是程序,共享库在运行期绑定到程序里的那份。这只在
-ELF 上、且只对那个程序成立:该库通不过 `-Wl,-z,defs`,没有链接这个包的宿主加载不了它
-(`undefined symbol`),Mach-O 与 PE 在链接期就解析每一个引用,Android 则先于任何能
-提供这个包的东西加载应用的共享库。
+在 2026.9.16.1 之前，这样的包会被链接进程序，库在运行时绑定的是程序里
+的那份拷贝。这只在 ELF 上有效，而且只对那一个程序有效：这个库会拒绝
+`-Wl,-z,defs`，一个没有链接该包的宿主无法加载它（`undefined symbol`），
+Mach-O 与 PE 在链接期就解析每一处引用，而 Android 会在任何能提供该包
+的东西之前先加载应用的共享库。
 
-被**多个**映像到达的静态包(两个共享库,或一个共享库加程序)没有唯一可放的映像:
+一个被**多份**镜像触达的静态包（两个共享库，或一个共享库加程序）没有
+单一的镜像可以栖身：
 
-- 在 Mach-O、PE 与 Android 应用行上,构建在编译之前被拒绝,原因为
-  `static-package-in-two-images`([50](50-machine-output.md));
-- 在其他 ELF 行上,这个包照旧留在程序里,构建会报告它(`build/static-placement`),
-  `--strict` 下为错误。
+- 在 Mach-O、PE 与 Android 应用这一行上，构建会在编译之前被拒绝，理由
+  是 `static-package-in-two-images`（[50](50-machine-output.md)）；
+- 在其它 ELF 行上，包仍像以前一样留在程序里，构建会报告这一点
+  （`build/static-placement`），`--strict` 把它变成错误。
 
-消息会写出这个包、到达它的映像,以及出路:让这个包取共享形态,使每个映像加载同一份。
+这条消息点名这个包、触达它的那些镜像，以及补救办法：给这个包共享的
+形态，让每份镜像各加载一份拷贝。
 
 ```toml
 [dependencies]
-x = { path = "../x", linkage = "shared" }   # 写在根工程的依赖边上
+x = { path = "../x", linkage = "shared" }   # on the root's edge
 
-# 或作为这个包自己的默认值,写在它的 manifest 里
+# or as the package's own default, in its manifest
 [targets.x]
 linkage = "shared"
 ```
 
-提供目标层的包(`provides = ["mcpp:..."]`,C 库或 C++ 运行时)不在这条规则之内:
-它的对象放在哪里由运行时契约决定([20](20-toolchains.md))。
+一个提供目标层（`provides = ["mcpp:..."]`、一个 C 库或一个 C++ 运行时）
+的包不受这条规则约束：它的对象去往何处，由运行时契约决定
+（[20](20-toolchains.md)）。
 
 #### library 目标上的 `soname`
 
-`soname`(§2.2)在 `kind = "lib"` 上同样可以声明。它是一个库被**找到**时用的
-名字,也是 mcpp 构建的那份与第三方携带的同一个库能解析到**同一个文件**的唯一
-途径 —— 而如果声明它就意味着这个包不能再作为静态库被消费,包就无法陈述这件事。
+`soname`（§2.2）也可以声明在 `kind = "lib"` 上，不只是
+`kind = "shared"`。它是一个库被**查找**时使用的名字，也是 mcpp 构建出
+的某个包与第三方的同一份库能解析到**同一个文件**而不是两个文件的
+唯一途径——如果声明它就意味着这个包不能再作为静态库被消费，包就没法
+陈述这一点。
 
-在非 shared 目标上写 `soname` 的描述符,**无法被 2026.8.28.2 之前的 mcpp 读取**
-—— 失败的是整份 manifest,不只是这个键。因此把它发布进索引要等下限抬上去。
+一份在非共享目标上写了 `soname` 的描述符，无法被 2026.8.28.2 之前的
+mcpp 发布版读取——整份 manifest 都会加载失败，而不只是这个键。因此把
+这样一份描述符发布到索引，要等到那个引擎下限被移动之后。
 
 #### 符号提供者检查
 
-链接之后,mcpp 会问:映像里的每个符号是不是**恰好有一个**提供者。在 ELF 上
-可执行文件排在最前,因此被静态并进程序的库,会在它与旁边加载的共享库共有的
-每个符号上获胜 —— 共享的那份永远不会被调用,而那个库里的代码跑在一份它并非
-针对其链接的构建上。链接器和加载器都不会为此报任何一句话。
-
-这项检查是**测量**而不是声明:读产物的动态符号表,去掉 copy relocation,只报告
-产物自身闭包里**也**有定义的那些。进程里只有一份副本的安排保持静默。有三类共同定义
-只计数、不报告 *(后两类自 2026.9.16.1 起)*:加载器按设计统一的 vague linkage
-(`STB_WEAK`,以及 GCC 用于内联实体静态数据的 `STB_GNU_UNIQUE`);构建从**同一个
-目标文件**链接进两个映像的定义,例如每个导入 `std` 的 C++ 映像里的 `std` 模块初始化
-函数;以及同一个初始化函数与工具链自身 C++ 运行时之间的重复,GCC 16 起该运行时也导出
-它。形状相同、定义在其他地方的名字仍然会被报告。判定记录在
-`target/<triple>/<fp>/resolution.json` 的 `runtime.symbol_provision` 下,带计数
-与分母,CI 不需要 `readelf` 就能读。
-
-默认是警告,`--strict` 下升级为错误。三条出路**有次序**,而次序是要紧的:
-
-1. **让其中一方不再提供这个库** —— 通常是那个携带了依赖图已经在构建的库的副本
-   的包。永远正确。
-2. **让两者解析到同一个文件**:在库的 target 上声明它真正的 `soname`。
-3. **`dependency_linkage`** 改变 mcpp 构建的形态。它会消掉**这一条**报告,但单
-   独用可能把一份变成**两份**:实测在一个暂存了 glib(其 `libgio` 需要
-   `libz.so.1`)、同时静态构建 `compat.zlib` 的图上,切换形态让可执行文件的 88
-   个导出符号归零,然后 `libzlib.so` 与 `libz.so.1` **两个都被加载**。只有在
-   (2) 同时成立时它才真的把两个提供者合成一个。
-
-`private_include_dirs` 指出 **`include_dirs` 中**在本包边界处停住的那些条目:
-本包用它们编译,消费者永远收不到。
-
-绝大多数包发布的就是它编译时用的那一套,所以长期以来只有 `include_dirs` 就够了。
-两者不同的形状只有一种 —— 一个包**内嵌了带内部头覆盖层的库**。musl 通过
-`src/include` 到达它自己的声明,而那些头定义了 `hidden`、`weak`、`weak_alias`,
-这些名字只对 musl 自己的源码有意义。把那个目录发布出去,等于把这些宏交给每一个
-消费者;而一个把 `hidden` 当普通标识符用的消费者会编不过,且看不出原因。
+链接之后，mcpp 会检查镜像里的每一个符号是否恰好只有**一个**提供者。
+在 ELF 上，可执行文件先被搜索，所以一个静态合并进程序的库，会在它与
+旁边加载的共享库共有的每一个符号上获胜——那份共享拷贝从未被真正
+调用，那个库内部的代码运行时面对的是一份它没有链接过的构建。对此，
+链接器与加载器都没有任何诊断。
+
+这项检查是一次测量，不是一条声明：它读取产出镜像的动态符号表，去掉
+属于拷贝重定位的条目，只报告产物自身闭包里**另有**某个库同样定义的
+那些符号。一份进程中只有一处拷贝的安排是无声的。三类共享定义会被计入
+但不报告（最后两类为 2026.9.16.1+）：vague linkage，加载器按设计统一
+处理这类符号（`STB_WEAK`，以及 GCC 用于内联实体静态数据的
+`STB_GNU_UNIQUE`）；构建从**一个对象**同时链接进两份镜像的定义，例如
+每一个 import `std` 的 C++ 镜像里 `std` 模块的初始化器；以及那同一个
+初始化器相对工具链自身 C++ 运行时的情形，GCC 16 起会导出它。任何其它
+地方定义的同名同形符号，仍算一处发现。判定结果被记录在
+`target/<triple>/<fp>/resolution.json` 的 `runtime.symbol_provision`
+下，带计数与分母，CI 无需 `readelf` 即可读取。
+
+它默认是警告，在 `--strict` 下是错误。解决办法按顺序排列，顺序很重要：
+
+1. **让其中一方停止提供它**——通常是某个包自带了图里已经在构建的某个
+   库的拷贝。总是正确的做法。
+2. **让两者解析到同一个文件**，做法是在那个库的目标上声明它真实的
+   `soname`。
+3. **`dependency_linkage`** 改变 mcpp 构建的是哪种形态。它会移除
+   **这一条**发现，但单独使用它可能留下**两份**已加载的拷贝而不是
+   一份：在一张同时摆放 glib（其 `libgio` 需要 `libz.so.1`）与一个
+   静态构建的 `compat.zlib` 的图上实测，切换形态后可执行文件的 88 个
+   导出符号消失，随后同时加载了 `libzlib.so` 与 `libz.so.1`。只有当
+   第（2）条也成立时，它才会把两个提供者统一成一个。
+
+`private_include_dirs` 命名的是 `include_dirs` 里那些止步于本包自身
+边界的条目：本包用它们编译，但消费者永远不会得到它们。
+
+几乎每个包发布的都恰好是它自己构建所用的那一整套，这正是为什么很长
+一段时间里单靠 `include_dirs` 就够用。二者出现分歧的情形，是一个包
+内嵌了带**内部头文件覆盖层**的库。musl 通过 `src/include` 到达自己的
+声明，那里的头文件定义了 `hidden`、`weak` 与 `weak_alias`——这些名字
+只对 musl 自己的源码有意义。发布那个目录会把这些宏交给每一个消费者，
+而一个把 `hidden` 当作普通标识符使用的消费者，会因为一个它无从看见的
+原因而无法编译。
 
 ```toml
 [build]
-# 两类目录的**相对顺序**是承重的:本包自己构建时,内部覆盖层必须排在公共头之前。
-# 这正是它被设计成 `include_dirs` 的**子集**而不是第二个列表的原因 ——
-# 两个数组表达不了一个顺序。
+# The relative ORDER of the two kinds is load-bearing: the internal overlay
+# must precede the public headers for this package's own build. That is why
+# this is a SUBSET of `include_dirs` rather than a second list — two arrays
+# cannot express one order.
 include_dirs         = ["port/include", "musl/src/include", "musl/include"]
 private_include_dirs = ["musl/src/include"]
 ```
 
-条目支持与 `include_dirs` 相同的 `*` glob 约定,并在**展开之后**比对 ——
-所以一个 glob 可以恰好指名它展开出的那些目录。若某条目不在本包的 `include_dirs`
-里,它什么也没扣下,mcpp 会把这件事说出来而不是让它悄悄通过。
-
-**旧引擎会忽略这个键,而不会因此失败。** 在 2026.8.26.2 上实测:出现在依赖的清单里
-时被静默接受;出现在根清单里时给一条警告 —— `[build] has unsupported key
-'private_include_dirs' (ignored)` —— 构建照常继续。所以一个包可以先用上这个键,
-不必等消费者升级;还在旧引擎上的消费者只是像以前一样继续收到那个目录。**唯一不成立
-的地方**是已发布的 `xim` 描述符的 `target_cfg` 块:那里不认识的子键是硬错误,会让
-整份清单加载失败 —— 在索引下限指向认识它的引擎之前,不要把这个键写进那里。
-
-`include_dirs_after`(#249)列出**排在工具链系统目录之后**搜索的头文件目录
-(GCC/Clang 发射为 `-idirafter`;MSVC 方言退化为排在末尾的 `/I`,NASM 汇编
-单元退化为普通 `-I`——两者都没有对应 flag,也都没有需要保护的系统头搜索链)。当目录是解压后的源码 tarball 根目录、且其中的文件名会与标准头冲突时,
-用它代替 `include_dirs` —— 例如 ffmpeg 根目录的 `VERSION` 文件在大小写不敏感
-的 macOS 文件系统上会把 libc++ 的 `<version>` 遮蔽(若该根目录挂在 `-I` 上)。
-使用 `include_dirs_after` 时系统头永远优先,而包自己的真实头文件
-(`<libavutil/frame.h>`)仍能找到。条目支持与 `include_dirs` 相同的 `*` glob
-约定,并沿相同的依赖边传播给消费者 —— 消费者收到的仍是 after 目录,
-永远不会被升级为 `-I`。
-
-`macos_deployment_target` 设定产物 Mach-O 头里的最低系统版本
-(`LC_BUILD_VERSION minos`),即二进制能运行的最老 macOS。优先级与各生态
-惯例一致:环境变量 `MACOSX_DEPLOYMENT_TARGET`(单次调用的显式覆盖,
-cargo/rustc、cc 等同样尊重该变量)> 本字段(项目默认,类似 SwiftPM 的
-`platforms:`)> **内建默认 `14.0`**(rustc 风格——每个 target 都有基线,
-14.0 即 LLVM 官方静态库自身的下限)。该值会进入 BMI 指纹——切换 target
-会自动重建模块缓存。
-
-### 构建并发(`jobs`)与模块调度(`bmi_schedule`)
+条目遵循与 `include_dirs` 相同的 `*` glob 约定，并且是在展开**之后**
+匹配的——所以一条 glob 可以正好命中它展开出的那些目录。一个不在这个
+包的 `include_dirs` 里的条目不会隐藏任何东西，并且会被如实报告，而
+不是悄悄放过。
+
+**在较旧的引擎上，这个键会被忽略，而不会致命。** 在 2026.8.26.2 上
+实测：在一个依赖的 manifest 里，它被静默接受；在一份根 manifest 里，
+它会警告——
+`[build] has unsupported key 'private_include_dirs' (ignored)`——
+而构建继续进行。所以一个包可以先采用这个键，不必等待
+它的消费者升级；那些还在旧引擎上的消费者，只会继续像以前一样拿到那个
+目录。唯一的例外，是一份已发布的 `xim` 描述符的 `target_cfg` 块——
+那里，一个无法识别的子键是硬错误，会让整份 manifest 加载失败——在
+索引下限点名一个认识这个键的引擎之前，不要把这个键放进那里。
+
+`include_dirs_after`（#249）列出在工具链的系统目录**之后**才被搜索的
+头文件目录（在 GCC/Clang 上渲染为 `-idirafter`，在 MSVC 方言下渲染为
+追加在末尾的 `/I`，在 NASM 汇编单元上渲染为普通的 `-I`——后两者都没有
+对应机制，也都没有需要保护的系统头文件链）。当某个目录是一个解出来的
+源码压缩包根目录、其中的文件名与标准头文件相撞时，用它代替
+`include_dirs`——例如，在大小写不敏感的 macOS 文件系统上，如果把
+ffmpeg 的压缩包根目录放上 `-I`，它顶层的 `VERSION` 文件会遮蔽 libc++
+的 `<version>`。用 `include_dirs_after`，系统头文件总是获胜，同时这个
+包真正的头文件（`<libavutil/frame.h>`）仍然可以被找到。条目支持与
+`include_dirs` 相同的 `*` glob 约定，并沿着相同的边向依赖它的包
+传播——消费者收到的是「之后」目录，永远不会被升级为 `-I`。
+
+`macos_deployment_target` 设定产物的 Mach-O 头（`LC_BUILD_VERSION
+minos`）里记录的最低系统版本，也就是这个二进制能运行的最旧 macOS
+版本。优先级遵循生态惯例：`MACOSX_DEPLOYMENT_TARGET` 环境变量（一次
+调用的显式覆盖，cargo/rustc、cc 等同样这样处理）> 这个字段（工程默认
+值，类似 SwiftPM 的 `platforms:`）> **内置默认值 `14.0`**（rustc
+风格——每个目标都有一个基线，而 14.0 正是 LLVM 官方静态库自身的下限）。
+这个值进入 BMI 指纹，所以切换目标会自动重建模块缓存。
+
+### 构建并发（`jobs`）与模块调度（`bmi_schedule`）
 
 ```toml
 [build]
-jobs         = "auto"    # 或正整数;--jobs / MCPP_JOBS 覆盖它
-bmi_schedule = "off"     # auto(默认,= 关)| on | off
+jobs         = "auto"    # or a positive number; --jobs / MCPP_JOBS override it
+bmi_schedule = "off"     # auto (default, = off) | on | off
 ```
 
-`jobs` 是同时跑几个编译。`"auto"` **在构建这台机器上现算**,绝不冻进 manifest:
-异构 CPU 上取物理核数(13900K 是 8 P-core + 16 E-core,它的 32 个线程不是 32 个
-等价的工人),再按可用内存夹一次 —— 单个模块接口编译峰值 0.5–1.0 GB。
-写错的值会被
-**明确报出来,绝不静默当成默认值** —— 一个悄悄退回默认的拼写错误,表现是
-「构建莫名其妙比我要求的慢」。
+`jobs` 是同时运行多少个编译。`"auto"` 是**相对正在执行构建的这台机器**
+解析的，绝不会被冻结进 manifest：它取一颗异构 CPU 的物理核心数（一颗
+13900K 是 8 个 P-core + 16 个 E-core，所以它的 32 个线程不是 32 个
+等价的工作者），并按空闲内存夹紧这个数字，因为单次模块接口编译峰值
+占用 0.5–1.0 GB。一个畸形的取值会**被报告，绝不会被静默当作默认值
+处理**——一个悄悄恢复默认值的拼写错误，会让构建比要求的更慢，却没有
+任何迹象说明原因。
 
-优先级,每一级描述的是不同的东西:
+优先级如下，每一层描述的是不同的东西：
 
-| 级别 | 作用域 |
+| 层级 | 作用域 |
 |---|---|
-| `--jobs` / `MCPP_JOBS` | 这一次调用 |
-| `[build] jobs`(这个键) | 这个工程 |
-| `~/.mcpp/config.toml` 里的 `[build] default_jobs` | **这台机器** |
-| 缺省,或 `0` | 什么都不说,交给后端自己的默认值 |
+| `--jobs` / `MCPP_JOBS` | 本次调用 |
+| `[build] jobs`（这个键） | 本工程 |
+| `~/.mcpp/config.toml` 里的 `[build] default_jobs` | **本机** |
+| 缺失，或 `0` | 什么都不说，交给后端自己的默认值 |
 
-三者里只有按机器的那个键能承载机器事实。`--jobs` 每次调用都要重说一遍;这个键
-是按包的,而 `[workspace.build]` 不继承它,所以一个七成员的 workspace 会把同一个
-数字写七遍,并把某位开发者的内存上限提交进仓库。`default_jobs = 0` 是 mcpp 写进
-新配置的值,含义是缺省。
+三者之中，只有按机器设置的那个键能承载一个机器事实。`--jobs` 必须在
+每次调用时重复传入；这个键是按包的，`[workspace.build]` 不会继承它，
+所以一个七个成员的 workspace 会把这个数字重复七遍，并把某个开发者
+自己的内存上限提交进仓库。`default_jobs = 0` 是 mcpp 写进一份全新
+配置文件时的取值，含义是「未设置」。
 
-`default_jobs` **同时约束 `mcpp test` 的并发**,而在那里缺省时的回落是整台机器
-而不是某个后端的默认值。十个并发测试进程与十个并发编译的内存形状一样,所以按机器
-设的数字对两者都生效。这句话写出来是因为:一个键有两种行为,必须明说。
+`default_jobs` **也约束 `mcpp test` 的并发度**，它缺失时的回落值是
+整台机器，而不是某个后端的默认值。一次十个并发进程的测试运行，与一次
+十个并发的编译，内存形状相同，所以一个按机器设置的数字对两者都适用。
+之所以写出这一点，是因为一个键有两种行为，就必须写清楚。
 
-`bmi_schedule` 决定**导入方什么时候被解锁**。
+`bmi_schedule` 决定 importer 何时被解除阻塞。
 
-| 值 | |
+| 取值 | |
 |---|---|
-| `"auto"` | **默认值,而它目前等于「关」** |
-| `"on"` | 拆开模块边:BMI 一发布导入方就能开始,而不是等编译器退出 |
-| `"off"` | 每个模块一条边 |
-
-只认这三种拼写。`"ON"`、`"true"`、`"yes"` 会被**拒绝并给出诊断**,而不是悄悄
-当成关 —— 而且它们不是无害的笔误:这个值会进构建指纹,所以一个被拒的拼写
-以前会选到**另一个构建目录**(即一次全量重建),同时对调度没有任何影响。
-
-**`auto` 为何等于关闭。** 模块接口编译中约 86% 是任何导入方都不会读取的代码生成,
-因此提前发布 BMI 收益显著 —— 在 mcpp 自身上实测:`cold` 86.7s → 35.7s、
-`edit-body` 80.9s → 29.8s。但调度错误的表现是静默失效:缺少一条依赖不会使构建
-报错,只会使某个目标不再重建。因此在所有平台完成 CI 验证前,该键保持 opt-in。
-
-**该键无效的场景。** mcpp 本来就跳过级联的地方(`touch-hub`、`edit-comment`)
-没有可以移出关键路径的必需工作,该键不产生收益。见
-[性能对比](../../README.zh-CN.md#性能对比)。
-
-**实现方式**按编译器确定,无需用户选择:gcc 用 `rename()` 发布 BMI,所以代码
-生成被分离出去、边在发布时就返回;clang 换成两条普通边 —— 它把 BMI 直接
-`O_TRUNC` 写到最终路径,读的人可能看到写了一半的文件。MSVC 不动:`/ifcOnly`
-的代价和 `.ifc` 是否原子发布都没测过,而这两件事猜错都是无声的。
-
-### 模块接口扩展名(`module_extensions`)
-
-mcpp 把 `.cppm` 视为模块接口单元。C++ 生态并没有收敛到一种拼法 —— Clang 还认
-`.ccm` 和 `.cxxm`,MSVC 用 `.ixx` —— 所以接口用别的扩展名的工程自己声明:
+| `"auto"` | **默认值，目前意味着关闭** |
+| `"on"` | 拆分这条模块边：importer 在 BMI 发布时就开始，而不是等编译器退出 |
+| `"off"` | 一个模块对应一条边 |
+
+只接受这三种拼法。`"ON"`、`"true"` 与 `"yes"` 会**带诊断信息被
+拒绝**，而不是被悄悄当作关闭——它们也不是无害的笔误：这个值会进入
+构建指纹，所以一个被拒绝的拼法，过去会选中一个不同的构建目录（一次
+完整重建），而调度本身却什么都没变。
+
+**为什么 `auto` 是关闭的。** 一次模块接口编译里，86% 的时间花在没有
+任何 importer 会读取的代码生成上，所以提前发布 BMI 很值——在 mcpp
+自身上实测，`cold` 从 86.7s 降到 35.7s，`edit-body` 从 80.9s 降到
+29.8s。但一次调度上的错误是**无声地**错的：一条被漏掉的依赖不会让
+构建失败，只会让某样东西不再被重建。它保持默认关闭，直到在每个平台的
+CI 上都跑通过。
+
+**它帮不上忙的地方。** 在 mcpp 已经跳过级联的地方——`touch-hub`、
+`edit-comment`——没有欠下的工作需要移出关键路径，这个键什么都买不到。
+见[基准测试](../../README.md#benchmark)。
+
+**机制**因编译器而异，并自动选择：gcc 用 `rename()` 发布它的 BMI，
+所以代码生成与之分离，这条边在发布时就返回；clang 得到的是两条普通的
+边，因为它以 `O_TRUNC` 把 BMI 写到最终路径，读者可能会看到一个写了
+一半的文件。MSVC 被留在一边不动——`/ifcOnly` 的开销与 `.ifc` 的
+原子性都未经测量，两者任何一个猜错都是无声的。
+
+### 模块接口扩展名（`module_extensions`）
+
+mcpp 把 `.cppm` 当作一个模块接口单元。C++ 生态还没有在这件事上收敛到
+一种拼法——Clang 还认得 `.ccm` 与 `.cxxm`，MSVC 用 `.ixx`——所以一个
+接口用了别的扩展名的工程需要声明它：
 
 ```toml
 [build]
 module_extensions = [".ixx", ".ccm"]
 ```
 
-这个列表是**追加**的:`.cppm` 永远是模块接口,不能删。要让某个文件不参与构建,
-用 `sources` 的 `!` 前缀 —— 那才是 `sources` 的职责。
+这份列表是**只增**的：`.cppm` 永远是模块接口，无法被移除。要阻止某个
+具体文件被构建，在 `sources` 里用 `!` 排除它；这正是 `sources` 的用途。
 
-声明一个扩展名会同时做三件事,这正是「一个键而不是几个键」的理由:
+声明一个扩展名会同时做三件事，这也是设一个键而不是设几个键的意义
+所在：
 
-1. `sources` 的约定默认值跟着变宽,文件才**能被找到**(`src/**/*.ixx` 自动进入默认 glob);
-2. 这些单元用**模块**规则编译 —— 产出 BMI,其 `.o` 无条件进入链接;
-3. 新鲜度快路径会扫描它们,所以给其中一个加 `import` 会让构建图作废,
-   而不是静默复用一张过期的图。
+1. `sources` 的约定默认值随之扩大，使这些文件能被**找到**
+   （`src/**/*.ixx` 加入默认 glob）；
+2. 这些单元按**模块**规则编译——它们发出 BMI，它们的对象无条件被
+   链接；
+3. 新鲜度快路径会盯住它们，所以给某个文件加一条 `import` 会让构建图
+   失效，而不是静默复用一份陈旧的图。
 
-**任何扩展名都接受**,唯独拒绝那些已经代表其他角色的
-(`.cpp` `.cc` `.cxx` `.c` `.m` `.mm` `.h` `.hpp` `.hh` `.hxx` `.S` `.s` `.asm`)——
-这是 manifest **错误**而不是警告,因为它会把(比如)C 文件送进 C++ 模块规则,
-最终失败在一个既不提文件也不提这个键的地方。
+除了那些已经命名了某种非模块角色的扩展名（`.cpp` `.cc` `.cxx` `.c`
+`.m` `.mm` `.h` `.hpp` `.hh` `.hxx` `.S` `.s` `.asm`）之外，任何扩展名
+都会被接受；声明其中之一是 manifest 错误而不是警告，因为那会把（比如
+说）C 文件路由进 C++ 模块规则，并在一个既不点名文件也不点名这个键的
+地方失败。
 
-扩展名**按字面匹配,不做大小写折叠** —— 在这个领域里 `.S` 和 `.s` 是两种不同的语言,
-所以大小写从不被忽略。
+扩展名是**按字面匹配、不做大小写折叠**的——`.S` 与 `.s` 在这个领域
+是两种不同的语言，大小写永远不会被忽略。
 
-mcpp 每次都会**显式告诉编译器**这个单元是模块接口(Clang 用 `-x c++-module`,
-GCC 用 `-x c++`,MSVC 用 `/interface /TP`),所以即使编译器驱动从没听说过这个扩展名
-也能工作。这也是为什么任何扩展名都被允许:mcpp 不需要编译器认识它。
+mcpp 总是明确告诉编译器某个模块接口单元就是模块接口单元（Clang 上是
+`-x c++-module`，GCC 上是 `-x c++`，MSVC 上是 `/interface /TP`），所以
+编译器驱动程序从未听说过的扩展名照样能工作。这正是任何扩展名都被
+允许的原因：mcpp 不需要编译器认识它。
 
-> **发布须知**:旧版 mcpp 不认识这个键 —— 它会警告、忽略,然后把那些文件当作普通
-> 翻译单元编译,得到一个**错误的构建**而不是一次干净的失败。发布一个用了
-> `module_extensions` 的包,请在它的索引描述符里声明 mcpp 版本下限。
+> **发布注意事项。** 较旧的 mcpp 不认识这个键：它会警告、忽略它，
+> 然后把那些文件当作普通翻译单元编译——这是一次错误的构建，而不是
+> 一次干净的失败。一个使用了 `module_extensions` 的已发布包，应在其
+> 索引描述符里声明一个 mcpp 版本下限。
 
-### 构建程序超时(`build_program_timeout`)
+### 构建程序超时（`build_program_timeout`）
 
-`build.mcpp` 默认有 **600 秒**,超时后 mcpp 杀掉它并让构建失败、点名是哪个包。
-构建程序确实需要跑更久的工程(大规模代码生成)自己抬高上限:
+一个 `build.mcpp` 默认获得 **600 秒**，超时后 mcpp 会杀掉它并使构建
+失败，同时点名这个包。一个构建程序确实需要更长时间运行的工程（比如
+一个大型的代码生成步骤），可以抬高自己的上限：
 
 ```toml
 [build]
-build_program_timeout = 1800   # 秒;0 = 不限
+build_program_timeout = 1800   # seconds; 0 = no limit
 ```
 
-这个值读的是**拥有该 `build.mcpp` 的那个包**的 manifest —— 依赖的生成器由依赖自己的
-声明来限制,因为只有它的作者知道要跑多久。优先级与 `macos_deployment_target` 同构:
+这个值取自**拥有这个 `build.mcpp` 的那个包自己的 manifest**——一个
+依赖的生成器，由依赖自己的声明约束，因为知道它要跑多久的是它的作者。
+优先级与 `macos_deployment_target` 遵循相同的形状：
 
 ```
-MCPP_BUILD_PROGRAM_TIMEOUT=<秒>   本次调用(最高)
-  > [build] build_program_timeout  该包自己的 manifest
-  > 600                            内置默认
+MCPP_BUILD_PROGRAM_TIMEOUT=<seconds>   (this invocation; highest)
+  > [build] build_program_timeout      (that package's manifest)
+  > 600                                (built-in default)
 ```
 
-**不写这个键**与**写 `0`** 不是一回事:不写表示「用默认上限」,`0` 表示「完全不设上限」。
+省略这个键与把它设为 `0` 不是一回事：不设置意味着「用默认上限」，`0`
+意味着「完全没有上限」。
 
-这个值刻意**不进构建指纹** —— 它不改变图里的任何一条边,而把它折进指纹会让
-「抬高超时」触发全量重建,这恰好与抬高超时的人想要的相反。
+这个值刻意**不是**构建指纹的一部分——它不改变图里的任何一条边，把它
+折进指纹会意味着抬高超时会重建整个工程，这与抬高超时的人想要的正好
+相反。
 
-只有构建**程序**受限,**编译**不受限。原因见
-[30-build-mcpp.md](30-build-mcpp.md)。
-### C++ 运行时契约(`cxx_runtime`)
+**编译**阶段不受这个上限约束，只有构建**程序**受约束。这种不对称是
+刻意为之，原因见 [30-build-mcpp.md](30-build-mcpp.md)。
 
-已移入 [20 —— 工具链管理](20-toolchains.md)。
+### C++ 运行时契约（`cxx_runtime`）
 
+已移至 [20 —— 工具链管理](20-toolchains.md)。
 
 ### 宿主代码页之外的文件名
 
-glob 是窄字符串,编译命令和 `build.ninja` 也是。在 Windows 上这些字符串由进程的
-**ANSI 代码页**产生,因此一个名字在该代码页里无法拼写的文件,既匹配不了 glob,也
-写不进编译命令或构建文件。
+glob 是窄字符串，编译命令与 `build.ninja` 也是。在 Windows 上，这些
+字符串以进程的 **ANSI 代码页**产生，所以一个文件名在那个代码页里没有
+拼法的文件，无法被 glob 匹配，无法出现在编译命令里，也无法写进构建
+文件。
 
-这类条目会被跳过,并按目录报告一次:
+这样的条目会被跳过，跳过信息按目录汇报一次：
 
 ```text
 warning: 'C:/.../pkg/test/www' contains names this system's active code page cannot represent
@@ -745,41 +845,48 @@ warning: 'C:/.../pkg/test/www' contains names this system's active code page can
   hint: Windows only: this is the process ANSI code page, which `chcp` does not change. ...
 ```
 
-报告里给的是**最近一个代码页拼得出的祖先目录**,用通用(`/`)写法。拼不出的那个名字本身
-永远不会被打印:渲染它会抛出这条消息正在报告的同一个异常。
+报出的路径是最近的、其名字**能**被该代码页拼出的祖先目录，采用通用
+（`/`）拼法。出问题的名字本身永远不会被打印：渲染它会抛出与这条消息
+正在报告的同一个异常。
 
-`chcp` 改的是**控制台**代码页,对此无效。若这些名字只是测试数据或文档,跳过是无害
-的——上游 tarball 里带一个日文夹具目录,在 en-US 宿主上照样构建。源文件则不然:需要
-改名,或换一台代码页覆盖得了的机器。
+`chcp` 设置的是**控制台**代码页，在这里没有作用。只是测试数据或文档
+的文件名是无害的——一个携带日语命名测试夹具目录的上游压缩包，在
+en-US 宿主上照常能构建。源文件则不然：它们需要改名，或者需要一个
+代码页能覆盖它们的宿主。
 
-Linux 与 macOS 不做这种转换,因此那里不会跳过任何名字。一个包在一边能构建、在另一
-边报 `internal: unhandled exception` 并指向代码页,就是 mcpp#516。
+Linux 与 macOS 不做这种转换，所以那里没有任何东西被跳过。一个能在
+其中一个上构建、在另一个上不能、并报出一条来自代码页消息的
+`internal: unhandled exception` 的包，就是 mcpp#516。
 
-### 2.3.1 `[build] accel` — 本次构建面向的加速器
+### 2.3.1 `[build] accel` —— 本次构建面向的加速器
 
 ```toml
 [build]
 accel = "cuda12.8+{sm_80,sm_90f} ptx>=90"
 ```
 
-本次构建为哪些设备后端与架构编译。单次构建可用 `--accel` 覆盖 ——
-这与 `--target` 对 `[toolchain]` 的关系相同;`--no-accel` 是显式请求「不要加速器」,
-也就是在一个同时发布了设备构建的包中选中 CPU-only 变体的方式。
+这次构建面向哪些设备后端与体系结构。可被 `--accel` 为单次构建覆盖，
+它与 `[toolchain]` 的关系和 `--target` 相同；`--no-accel` 显式请求不
+要任何加速器，这正是从一个同时发布设备构建的包中选出纯 CPU 变体的
+方式。
 
-该取值会与构建所消费的任何预建产物的 `accel` 字段比较,而请求为空的构建被任何产物满足。
-见 [42 — 异构硬件构建](42-heterogeneous-builds.md)。
+这个值会与所消费的任何预构建产物的 `accel` 字段比较，一次不要求任何
+加速器的构建，会被任何产物满足。见
+[42 —— 异构构建](42-heterogeneous-builds.md)。
 
-### 2.4 `[lib]` — 库根模块约定
+### 2.4 `[lib]` —— 库根模块约定
 
 ```toml
 [lib]
-path = "src/capi/lua.cppm"    # 覆盖默认的 lib-root 位置
+path = "src/capi/lua.cppm"    # Override the default lib-root location
 ```
 
-默认约定:`src/<包名最后一段>.cppm`(如包名 `mcpplibs.cmdline` → `src/cmdline.cppm`）。
+默认约定：`src/<包名的最后一段>.cppm`（例如包名 `mcpplibs.cmdline` →
+`src/cmdline.cppm`）。
+
 ### 2.5 `[dependencies]`、`[dev-dependencies]`、`[build-dependencies]`
 
-已移入 [05 —— 依赖与解析](05-dependencies.md)。
+已移至 [05 —— 依赖与解析](05-dependencies.md)。
 
 ### 2.7 `[toolchain]` —— 工具链配置
 
@@ -787,15 +894,15 @@ path = "src/capi/lua.cppm"    # 覆盖默认的 lib-root 位置
 [toolchain]
 default = "gcc@16.1.0"
 
-# 交叉编译目标覆盖
+# Cross-compilation target override
 [target.x86_64-linux-musl]
 toolchain = "gcc@16.1.0"
 linkage   = "static"
 ```
-### 2.7.1 `[target.*]` —— 平台条件依赖与 flag
 
-已移入 [22 —— 目标侧](22-target-side.md)。
+### 2.7.1 `[target.*]` —— 平台条件依赖与 flag
 
+已移至 [22 —— 目标侧](22-target-side.md)。
 
 ### 2.7.3 `min_api_level` —— 产物必须能跑在多老的 OS 上
 
@@ -804,74 +911,74 @@ linkage   = "static"
 min_api_level = 24
 ```
 
-Android 自己的用词是 **API level**,而这里要的是它的**最小值** —— NDK 的 CMake
-toolchain 把 `ANDROID_PLATFORM` 记载为「the minimum API level supported by the
-application or library」,并说明它对应 Gradle 的 `minSdk`。
+Android 自己的术语是 **API level**，这里指的是其中的最小值——NDK 的
+CMake 工具链文档里把 `ANDROID_PLATFORM` 记录为承载的那个量（「应用或
+库支持的最低 API level」），对应 Gradle 的 `minSdk`。
 
-**这是工程的决定,不是工具链的属性。** 一个 NDK 服务一个级别区间,所以写
-`android-ndk@<version>` 并不钉住某一个级别。
+**这是一个工程决定，不是工具链的属性。** 一个 NDK 服务于一段范围内的
+level，所以命名 `android-ndk@<version>` 并不能钉住其中一个。
 
-**它到达编译器,不进入身份。** 规范 triple 仍然是 `aarch64-linux-android` ——
-输出目录、`cfg(env = "android")` 和打包的 ABI tag 都由它命名;级别只拼进交给
-编译器的那个 triple:
+**它到达的是编译器，而不是身份。** 规范三元组始终是
+`aarch64-linux-android`，它命名输出目录、`cfg(env = "android")` 与
+打包后的 ABI 标签；level 被融合进传给编译器的那个三元组：
 
 | | |
 |---|---|
-| 规范 triple | `aarch64-linux-android` |
-| clang 实际收到 | `aarch64-unknown-linux-android24` |
-| 构建指纹 | 含级别 |
+| 规范三元组 | `aarch64-linux-android` |
+| clang 收到的 | `aarch64-unknown-linux-android24` |
+| 构建指纹 | 携带这个 level |
 
-指纹不是可选项:级别决定哪些 bionic 符号可见,所以两个级别就是两个 ABI,绝不可
-共用一个构建目录。
+指纹里带上它不是可选的：level 决定哪些 bionic 符号可见，所以两个
+level 是两种 ABI，绝不能共享一个构建目录。
 
-不设也合法,含义是 NDK 自己的默认级别 —— 那正是
-`clang -target aarch64-linux-android` 规范化出的形式。
+不设置是合法的，意味着使用 NDK 自己的默认值，也就是 `clang -target
+aarch64-linux-android` 归一化后得到的那个值。
 
-这与 `macos_deployment_target`(见上文)是同一套机制,而两者都用各自平台的词汇
-命名,而不是一个共享抽象。它们回答同一个问题:产物必须能跑在多老的 OS 发布版上。
+这与 `macos_deployment_target`（见上文）用的是同一套机制，两者各自用
+自己平台的说法命名，而不是共用一个抽象。两者回答的是同一个问题：产物
+必须能运行的最旧 OS 版本是哪个。
 
+### 2.7.2 裸机（`os = none`）—— freestanding 目标
 
-### 2.7.2 裸机(`os = none`)—— freestanding target
+`riscv64-none-elf` 与 `riscv32-none-elf` 是底下没有操作系统的目标。
+它们不需要按宿主区分的交叉工具链：clang 与 lld 本就是交叉编译器，所以
+任何能安装 llvm 载荷的宿主都能产出它们。
 
-`riscv64-none-elf` 与 `riscv32-none-elf` 是底下没有操作系统的 target。它们不需要
-逐宿主的交叉工具链:clang 与 lld 天生是交叉编译器,任何能装 llvm 载荷的宿主都能
-产出它们。
-
-本节是清单参考。示例部分 —— 生成工程、运行、在目标上测试、freestanding 标准库
-子集,以及编写板级支持包 —— 在
-[40 — 裸机与 freestanding 目标](40-baremetal.md)。
+本节是 manifest 参考。实战示例——脚手架搭建、运行、在目标上测试、
+freestanding 标准库子集，以及编写一个板级支持包——都在
+[40 —— 裸机与 freestanding 目标](40-baremetal.md)里。
 
 ```bash
 mcpp build --target riscv64-none-elf
-mcpp run   --target riscv64-none-elf     # 经 [target.<triple>].runner
+mcpp run   --target riscv64-none-elf     # via [target.<triple>].runner
 ```
 
-**从板级支持包起步**
+**从一个板子包开始**
 
-下面这些几乎都不需要手写。板级支持包(BSP)自带 C 库、启动代码、内存布局和模拟器,
-所以跑起一个镜像的最短路径是:
+下面这些内容几乎不需要手写。一个板级支持包携带了 C 库、启动代码、
+内存布局与模拟器，所以到达一个能启动的镜像的最短路径是：
 
 ```bash
 mcpp new blinky --template riscv-virt-rt
 cd blinky && mcpp run
 ```
 
-生成的 manifest 里没有链接脚本、没有加载地址、没有 libc、没有模拟器 —— 连
-`[target.*]` 段都没有。本节余下的内容讲的是**这样一个包提供了什么**,也就是要给
-一块还没有 BSP 的板子写一个时该照着做什么。
+生成的 manifest 不命名任何链接脚本、加载地址、libc 或模拟器——它完全
+没有 `[target.*]` 小节。本节剩下的部分描述这样一个包供给了什么，这
+正是在为一块没有这些的板子编写包时应当参照的内容。
 
-**freestanding target 上有什么不同**
+**freestanding 目标上有哪些不同**
 
 | | |
 |---|---|
-| 链接线 | `-nostdlib -nostartfiles -static`,且不带任何 hosted 的东西 —— 没有 crt 文件、没有动态链接器、没有 C++ 运行时。链接器用**绝对路径**寻址(`-fuse-ld=<载荷>/bin/ld.lld`),因为 `-fuse-ld=lld` 走 `PATH` 解析,在任何 binutils 排前面的机器上都会找到 GNU ld。 |
-| ISA flag | `-march` / `-mabi` / `-mcmodel` 来自 target 表,所以只写 `--target <triple>` 就足以产出正确的目标文件。 |
-| C 库 | **属于 target**,由 mcpp 从目标自己那一行解析,和解析编译器同理 —— 裸机工程不声明 libc,正如宿主工程不声明 glibc。它的头进入每一个翻译单元,它的目录进入链接搜索路径,所以板级包用**裸名**选库(`-lc`、`-lcrt0-semihost`)。**选哪个**启动对象、**用哪份**链接脚本仍然是板级决定。 |
-| 异常与 RTTI | **关闭**,作用于每一个翻译单元,依赖的也不例外。没有 unwinder、没有 `libc++abi`,谁都抛不了;否则光是 `std::optional::value()` 就会拉进 `__cxa_throw` 等四个未定义符号。它属于 **target** 而不是工程的 `cxxflags`,因为 **BMI 会记录这个配置** —— 带异常编出来的依赖,不带异常的单元 import 不进来。 |
-| `import std` | **不可用。** `std` 是覆盖整个库的一个模块 —— 线程、文件系统、iostreams 全在内 —— 没有 OS 就没有它的子集可编。取代它的是两个普通依赖:**板级包**包住目标的 C 库,**`std-freestanding`** 提供标准库里不需要 OS 的那部分(实测 libc++ 110 个头里的 103 个)。 |
-| 入口点 | **只要有人提供 `crt0`,`int main()` 就能用** —— 板级支持包通常就提供它,于是固件的入口就是普通的 `main`,它的返回值经 semihosting 传回宿主。**只有零 libc 的板子**才需要显式声明 target 并把 `main` 指向携带 `_start` 的那个文件。 |
+| 链接行 | `-nostdlib -nostartfiles -static`，不含任何 hosted 的东西——没有 crt 文件、没有动态链接器、没有 C++ 运行时。链接器以**绝对路径**寻址（`-fuse-ld=<payload>/bin/ld.lld`），因为 `-fuse-ld=lld` 经 `PATH` 解析，在任何前面装了 binutils 的机器上都会找到 GNU ld。 |
+| ISA 旗标 | `-march` / `-mabi` / `-mcmodel` 取自目标表，所以仅凭 `--target <triple>` 就足以产出正确的对象文件。 |
+| C 库 | **目标自己的那一份**，由 mcpp 从目标自己的行解析，方式与解析编译器完全相同——一个裸机工程不声明任何 libc，正如一个 hosted 工程不声明 glibc。它的头文件到达每一个翻译单元，它的目录在链接搜索路径上，所以一个板子包用裸名字（`-lc`、`-lcrt0-semihost`）从中选取。**哪些**对象、**哪份**链接脚本，仍是板子自己的决定。 |
+| 异常与 RTTI | **关闭**，在包括依赖在内的每一个翻译单元上。这里没有展开器，也没有 `libc++abi`，所以没有任何东西能抛出；否则单是 `std::optional::value()` 就会拉进 `__cxa_throw` 以及另外三个未定义符号。它属于目标而不是工程的 `cxxflags`，因为 BMI 会记录它——一个带异常编译的依赖，无法被一个不带异常的单元 import。 |
+| `import std` | **不可用。** `std` 是覆盖整个标准库的一个模块——包括线程、文件系统与 iostreams——所以没有一个子集能在没有操作系统的情况下构建出来。两个普通依赖取代了它：**板子包**包装目标的 C 库，**`std-freestanding`** 携带标准库里不需要操作系统的那些部分（实测为 libc++ 110 个头文件中的 103 个）。 |
+| 入口点 | 只要有东西提供了 `crt0`，`int main()` 就能工作——一个板子包通常提供，这样固件的入口点就是一个普通的 `main`，它的返回值经由 semihosting 到达宿主。只有零 libc 的板子才需要一个显式目标，其 `main` 指向携带 `_start` 的文件。 |
 
-**一个最小固件**
+**一份最小固件**
 
 ```toml
 [package]
@@ -883,70 +990,79 @@ ldflags = ["-T", "/abs/path/to/link.ld"]
 
 [targets.firmware]
 kind = "bin"
-main = "src/start.S"          # 入口在汇编里,不在 main()
+main = "src/start.S"          # the entry lives in assembly, not in main()
 
 [target.riscv64-none-elf]
 runner = ["qemu-system-riscv64", "-machine", "virt", "-nographic",
           "-no-reboot", "-bios", "default", "-kernel"]
 ```
 
-**`runner` —— `mcpp run` 如何执行本机跑不了的东西**
+**`runner`——`mcpp run` 如何执行一个这台机器本身跑不了的东西**
 
-裸机镜像的 ISA 不对、没有 loader、且期望独占整个地址空间;直接 exec 它得到的是
-"Exec format error"。`runner` 就是挡在它前面的 argv 模板。产物路径会被**追加**,
-或者在模板含 `{}` 时替换进去。
+一个裸机镜像的 ISA 不对，没有加载器，并期望独占整个地址空间；直接
+执行它会得到「Exec format error」。`runner` 是站在它前面的那份 argv
+模板。产物路径会被**追加**在后面，或者在模板包含 `{}` 时替换掉它。
 
-mcpp **刻意不提供默认 runner**。用哪个模拟器、哪个机器型号、哪种固件模式都是板级
-事实 —— 同一 ISA 的两块板需要不同 argv(OpenSBI 启动用 `-bios default`,picolibc
-镜像用 `-bios none -semihosting`)—— 引擎一旦猜一个,另一块板就得跟它打架。板级
-支持包通常会提供它。
+mcpp 刻意**不附带任何默认 runner**。用哪个模拟器、哪个机器型号、哪种
+固件模式，都是板子自己的事实——同一 ISA 上的两块板子可能需要不同的
+argv（OpenSBI 启动用 `-bios default`，picolibc 镜像用 `-bios none
+-semihosting`）——一个替某一块板子猜一个值的引擎，就是另一块板子必须
+与之对抗的引擎。一个板级支持包通常会提供它。
 
-### 2.7.3 hosted 目标上的 `runner`(2026.9.2.1+)
+### 2.7.3 hosted 目标上的 `runner`（2026.9.2.1+）
 
-`[target.<triple>].runner` 对每一个精确三元组生效,不限于裸机。一个 hosted 交叉产物
-—— 在 x86_64 机器上构建的 `aarch64-linux-musl` —— 有的宿主能直接执行(binfmt_misc
-注册了 qemu-user),有的宿主以 `Exec format error` 拒绝;属于哪一种是机器的性质,不是
-三元组的性质。mcpp 不预测它:要么通过工程声明的 runner 执行产物,要么尝试直接执行并
-报告内核的回答。
+`[target.<triple>].runner` 适用于每一个精确三元组，不只是裸机。一个
+hosted 的交叉产物——在 x86_64 机器上构建的 `aarch64-linux-musl`——在
+一些宿主上可执行（注册了 qemu-user 的 binfmt_misc），在另一些宿主上会
+被拒绝并报 `Exec format error`，这两者哪个成立是机器的属性，不是
+三元组的属性。mcpp 不预测它。它要么通过工程声明的 runner 执行产物，
+要么尝试直接执行，并报告内核给出的答案。
 
 ```toml
 [target.aarch64-linux-musl]
 runner = ["qemu-aarch64-static"]
 ```
 
-规则对 `mcpp run` 与 `mcpp test` 相同:
-
-- **声明了 runner 就使用它。** 其第一个元素由 mcpp 定位:先在 `[xlings.workspace]`(§2.13)
-  声明的每个载荷的 `bin/` 目录里找,再找 `PATH`。`PATH` 上的裸名会命中 xvm shim,而
-  shim 按当前 SubOS 而非按包作答;先查载荷,runner 才能直接写工程声明过的程序名。
-- **声明的 runner 找不到或启动不了是错误**,错误里带程序名、搜索过的目录和 errno。
-  不回落到直接执行:让产物在另一个解释器下带着另一组参数运行,正是这个键要防止的
-  失败。
-- **没有 runner 且内核拒绝产物:** `mcpp run` 报告拒绝原因与应当写的键,退出码 2。
-  `mcpp test` 把每个测试报告为未运行,原因只打印一次,退出码 2(§2.7.3.1)。
-- **`--no-runner`** 直接执行产物并忽略声明的 runner。它陈述的是关于本机的事实 ——
-  这个三元组在本机是原生的 —— 清单没有承载它的轴;为 x86_64 开发者写的 runner 在
-  aarch64 机器上仍可用。
-
-通过 `[xlings.workspace]` 装模拟器是 CI 任务或单一宿主类别工程的形态。索引里的
-`qemu-user-aarch64` 只为 x86_64 Linux 构建,而这张表在每台构建本工程的宿主上都会
-provisioning,所以条目按平台写(§2.13):
+对 `mcpp run` 与 `mcpp test` 都适用的规则：
+
+- **一个已声明的 runner 会被使用。** 它的第一个元素由 mcpp 定位：先在
+  `[xlings.workspace]`（§2.13）下每个已声明载荷的 `bin/` 目录里找，再
+  到 `PATH` 上找。`PATH` 上的一个裸名字会解析到一个 xvm shim，它回答
+  的是当前 SubOS，而不是这个包；正是载荷查找，让一个 runner 能够命名
+  工程自己声明的程序。
+- **一个已声明但找不到或启动不了的 runner 是一个错误**，报告程序、
+  搜索过的目录与 errno。这里没有回落到直接执行：用不同的解释器、不同
+  的参数去运行这个产物，正是这个键存在要防止的那种失败。
+- **没有 runner，内核拒绝这个产物：** `mcpp run` 报告这次拒绝与需要
+  写的那个键，退出码 2。`mcpp test` 把每个测试都报告为未运行，理由
+  只报一次，退出码 2（§2.7.3.1）。
+- **`--no-runner`** 直接执行产物，忽略已声明的 runner。它陈述的是
+  关于这台宿主的一个事实——这个三元组在这里是原生的——而 manifest
+  没有轴可以承载这一点；一个 runner 为 x86_64 开发者写的工程，在
+  aarch64 机器上依然可读。
+
+通过 `[xlings.workspace]` 配置模拟器，是给 CI 作业、或构建在单一宿主
+类别上的工程用的形式。索引里的 `qemu-user-aarch64` 只为 x86_64
+Linux 构建，而这张表会在每个构建这个工程的宿主上配置，所以这个条目
+要按平台分别写（§2.13）：
 
 ```toml
 [xlings.workspace]
-"xim:qemu-user-aarch64" = { linux = "" }   # Linux 上存在即可,版本不限
+"xim:qemu-user-aarch64" = { linux = "" }   # present on Linux, any version
 
 [target.aarch64-linux-musl]
 runner = ["qemu-aarch64-static"]
 ```
 
-宿主装不了的包是硬构建错误,所以不带平台形式的条目会让工程在 macOS 与 Windows 上
-无法构建。同样没有这个包的 Linux/aarch64 宿主传 `--no-runner`。
+一个宿主装不上的包是一个硬构建错误，所以一个没有按平台区分的条目，
+会让这个工程在 macOS 与 Windows 上完全无法构建。而在这个包同样不
+存在的 Linux/aarch64 宿主上，要传 `--no-runner`。
 
 #### 2.7.3.1 `mcpp test` 与未运行的测试
 
-产物在本机无法执行的测试既没有通过也没有失败。`mcpp test` 把它报告为**未运行**,
-在确立原因时打印一次,在汇总里重复原因的第一行,退出码 2:
+一个这台宿主无法执行其产物的测试，既没有通过，也没有失败。`mcpp
+test` 把它报告为**未运行**，在原因确定时打印一次，在摘要里重复原因
+的第一行，退出码 2：
 
 ```
 warning: this host cannot execute aarch64-linux-musl artifacts: Exec format error (error 8); declare [target.aarch64-linux-musl].runner, or pass --no-runner on a host that can
@@ -954,37 +1070,39 @@ smoke ... not run
 error: test result: NOT RUN. 0 passed; 0 failed; 1 not run (this host cannot execute aarch64-linux-musl artifacts: Exec format error (error 8); ...); finished in 0.41s (build 0.39s + run 0.00s)
 ```
 
-退出码 1 含义不变 —— 有测试运行并失败;0 表示每个测试都运行并通过。
-`--message-format json` 在每条记录上带 `"status":"not_run"` 与 `reason`,在汇总记录上
-带 `not_run` / `not_run_reason`(见 [50 —— 机器可读输出](50-machine-output.md))。
-### 2.8 `[features]` —— Feature
+退出码 1 保留原有含义——一个测试运行过并失败；0 意味着每个测试都
+运行过并通过。`--message-format json` 在每条记录上携带
+`"status":"not_run"` 与一个 `reason`，摘要记录上则是 `not_run` /
+`not_run_reason`（见[50 —— 机器可读输出](50-machine-output.md)）。
 
-已移入 [06 —— Feature 与能力](06-features-and-capabilities.md),
-连同 `provides` / `requires` 与 `[feature-deps.<name>]`。
+### 2.8 `[features]` —— Feature
 
+已移至 [06 —— Feature 与能力](06-features-and-capabilities.md)，连同
+`provides` / `requires` 与 `[feature-deps.<name>]`。
 
 ### 2.8.3 `[scan_overrides."<glob>"]` —— 作者断言的扫描结果
 
-默认的模块扫描器是文本级的一遍扫描,它(刻意地)拒绝条件预处理块内部的 `import`
-语句。有些合法的模块单元带着这种写法 —— 例如 fmt 官方的 `src/fmt.cc` 把
-`import std;` 收在 `#ifdef FMT_IMPORT_STD` 之后。当该文件的 import 集合已知且稳定时,
-用声明取代扫描:
+默认的模块扫描器是一趟文本层面的处理，它（刻意）拒绝条件预处理块内的
+`import` 语句。有些合法的模块单元里确实有这种写法——例如 fmt 官方的
+`src/fmt.cc` 把 `import std;` 保护在 `#ifdef FMT_IMPORT_STD` 之内。
+当一个文件的 import 集合已知且稳定时，声明它，而不是去扫描它：
 
 ```toml
 [modules]
 sources = ["src/**/*.cppm", "vendor/fmt.cc"]
 
 [scan_overrides."vendor/fmt.cc"]
-provides = ["fmt"]      # 每个单元至多提供一个模块
+provides = ["fmt"]      # at most one provided module per unit
 imports  = ["std"]
 ```
 
-被 glob 命中的文件跳过文本扫描,声明的单元直接进入模块图。该声明**每次构建都被审计**:
-编译器自己对该文件的 P1689 扫描结果(`.ddi` dyndep 输入)会与之比对,任何分歧都会让
-那条编译边失败并打印双方 —— 陈旧的声明无法静默污染模块图。未命中任何源文件的
-override glob 是错误。
+被这条 glob 匹配到的文件会跳过文本扫描；声明的单元直接进入模块图。
+这条声明会在**每次构建时被审计**：编译器自己对这个文件做的 P1689
+扫描（`.ddi` dyndep 输入）会与它比对，任何分歧都会让那条编译边失败，
+并同时打印双方的结果——一条陈旧的声明无法悄悄污染这张图。一条不匹配
+任何源文件的 override glob 是一个错误。
 
-同一个键在 xpkg 描述符(索引包)中同样存在:
+xpkg 描述符（索引包）里也有同一个键：
 
 ```lua
 mcpp = {
@@ -996,119 +1114,135 @@ mcpp = {
 }
 ```
 
-要把 plan 与 ddi 的比对审计扩展到**每一个**模块单元(而不只是 override),
-在生成构建时设置 `MCPP_VERIFY_MODGRAPH=1`。
+要把这套「plan 与 ddi 对照」的审计扩展到**每一个**模块单元（不只是
+override），在生成构建时设置 `MCPP_VERIFY_MODGRAPH=1`。
 
 ### 2.8.4 默认扫描器读到的东西
 
-扫描器对每个文件只回答两个问题 —— 这个单元提供什么、需要什么 —— 并且没有别的
-东西决定它们。
+扫描器为每个文件回答两个问题——这个单元提供什么、这个单元需要
+什么——没有别的东西决定这两个答案。
 
-**三种模块声明,它们是不同的产生式。**
+**三种模块声明，它们是不同的产生式。**
 
 ```cpp
-module M;          // 实现单元:    需要 M,不提供任何东西
-module M:part;     // 实现分区:    提供 M:part
-module : private;  // 私有模块片段:两者都不声明
+module M;          // implementation unit:      requires M, provides nothing
+module M:part;     // implementation partition: provides M:part
+module : private;  // private module fragment:  declares neither
 ```
 
-第三种不是一个名字以冒号开头的分区。它在两个方向上都不产生边,其后的内容仍属于
-同一个单元。编译器是否实现它由编译器回答:GCC 16.1 报
-`sorry, unimplemented: private module fragment`,mcpp 不在其上追加任何说法。
+第三种不是一个名字以冒号开头的分区。它在任何方向上都不贡献边，它之后
+的内容仍然属于同一个单元。编译器是否实现了它，答案由编译器给出：
+GCC 16.1 报告 `sorry, unimplemented: private module fragment`，mcpp
+对此不做任何额外处理。
 
-**模块扩展名的文件不必提供模块。** 实现单元是 `.cppm` 的合法居民,而
-`module_extensions` 说的是**扫描**哪些文件,不是每个文件**是**什么。编译方式跟随
-扫描结果:提供模块的单元按接口编译并获得写 BMI 的位置;不提供的按普通翻译单元
-编译。因此两个编译器对同一个文件收到相同的指令 —— 在 mcpp 2026.9.9.1 之前并非
-如此:Clang 从扩展名推断出 `c++-module` 并拒绝该文件,而 GCC 能构建它。
+**一个模块扩展名文件不必提供一个模块。** 一个实现单元是 `.cppm` 里
+合法的居民，`module_extensions` 说的是要**扫描**哪些文件，而不是每个
+文件**是**什么。编译模式跟随扫描结果：一个提供模块的单元被当作接口
+编译，并给它一个写出 BMI 的地方；一个不提供模块的单元被当作普通翻译
+单元编译。因此两个编译器对同一个文件收到的是同一条指令——这在 mcpp
+2026.9.9.1 之前并非如此：Clang 会从扩展名推断出 `c++-module` 并拒绝
+这个文件，而 GCC 则会构建它。
 
-**源码按 UTF-8 读取。** UTF-8 字节序标记会被消耗,不属于正文 —— 这正是每个编译器
-对它的处理,也是 MSVC 默认写出的东西。UTF-16 或 UTF-32 标记会被具名拒绝,而不是
-被误读。同一规则适用于 `mcpp.toml`。
+**源码按 UTF-8 读取。** 一个 UTF-8 字节顺序标记会被消费掉，不算作
+正文的一部分，这与每个编译器的处理方式相同，也是 MSVC 默认写出的
+形式。一个 UTF-16 或 UTF-32 标记会被点名拒绝，而不是被误读。同一条
+规则也适用于 `mcpp.toml`。
 
-**任何源码都不可能声明出来的名字会被拒绝。** 模块身份是以点分隔的标识符序列,
-其后可选地跟一个 `:` 和另一个这样的序列。此外的形式在扫描阶段失败,而不是进入
-构建图 —— 在那里它会变成一条没有任何东西会报告的 BMI 路径。
+**一个源码不可能声明出来的名字会被拒绝。** 一个模块身份是一串由点
+分隔的标识符，后面可以再跟一个 `:` 与另一串这样的序列。任何其它形式
+都会在扫描阶段失败，而不会进入构建图——否则它会变成一个没有任何
+东西会报告的 BMI 路径。
 
-### 2.9 `[profile.<name>]` — 构建档案
+### 2.9 `[profile.<name>]` —— 构建档案
 
 ```toml
 [profile.dist]
-opt      = 3              # -O 级别(数字或 "s"/"z" 字符串)
+opt      = 3              # -O level (a number, or the string "s"/"z")
 debug    = false          # -g
-lto      = true           # -flto(注意:部分打包 gcc 未启用 LTO 插件)
-strip    = true           # 链接期 -s
-# passthrough 逃生口(固定键、开放值):
+lto      = true           # -flto (note: some packaged gcc builds ship without the LTO plugin)
+strip    = true           # -s at link time
+# passthrough escape hatch (fixed keys, open values):
 cflags   = ["-fno-plt"]
 cxxflags = ["-fno-plt"]
 ldflags  = []
 ```
 
-- 选择与默认:裸 `mcpp build` 走 **`dev`** 档(`-O0 -g`)——主流惯例(参照
-  Cargo/Meson/CMake/Zig/Bazel)。**release 为 opt-in:** `mcpp build --release`(短写)或
-  `--profile release`;`--dev` 是 dev 的显式短写。`mcpp test --profile <name>` 同理
-  (被测代码与测试二进制都在该 profile 下编译)。
-- **项目级默认** —— `[build].default-profile = "<name>"`(别名 `profile`)设置该项目在不带
-  flag 时的默认。典型用途是"以发布优化为常态"的工具/库:`[build] default-profile = "release"`。
-  优先级:`--profile`/`--release`/`--dev` flag **>** `[build].default-profile` **>** 全局 `dev`。
-  (默认 dev 的项目在产出可分发物时应显式 `--release`。)
-- 内置档案:`release`(-O2)/ `dev`、`debug`(-O0 -g)/ `dist`(-O3 + strip;
-  **不默认开 lto**)。`[profile.<内置名>]` 可整体覆盖内置定义。
-- **每个 profile 各占一个构建目录。** 解析后的 profile 开关参与指纹,所以
-  `target/<triple>/` 下每个 profile 一个哈希目录,来回切换是增量而不是全量重编;
-  代价是磁盘占用随实际使用的 profile 数量增长。
-
-### 2.10 `[build] cache` — 依赖的全局构建缓存
-
-从索引获取的依赖,其编译产物按包缓存在 `$MCPP_HOME/build-cache/v1/` 下,跨工程共享。
-依赖的产物与"谁在消费它"无关,所以工具链、profile、依赖版本相同的两个工程复用同一条目。
+- 选择与默认值：一条裸的 `mcpp build` 使用 **`dev`** profile
+  （`-O0 -g`）——这是主流约定（参见 Cargo/Meson/CMake/Zig/Bazel）。
+  **Release 需要显式选择：**`mcpp build --release`（简写）或
+  `--profile release`。`--dev` 是 dev 的显式简写。`mcpp test
+  --profile <name>` 同样适用（在该 profile 下构建被测代码及测试
+  二进制）。
+- **按工程的默认值**——`[build].default-profile = "<name>"`（别名：
+  `profile`）在没有传入旗标时设置这个工程自己的默认值。典型用法是一个
+  默认就该优化构建的工具或库：`[build] default-profile = "release"`。
+  优先级：`--profile`/`--release`/`--dev` 旗标 **>**
+  `[build].default-profile` **>** 全局默认 `dev`。（一个默认走 dev
+  的工程，在产出可分发物时应传 `--release`。）
+- 内置 profile：`release`（-O2）/ `dev`、`debug`（-O0 -g）/ `dist`
+  （-O3 + strip；**默认不启用 LTO**）。`[profile.<内置名>]` 可以整体
+  覆盖一个内置定义。
+- **每个 profile 拥有自己的构建目录。** 解析出的 profile 旋钮参与
+  指纹，所以 `target/<triple>/` 下每个 profile 各有一个哈希目录，在
+  它们之间切换是增量的，不是一次完整重建。这也意味着磁盘开销随实际
+  用到的 profile 数量而增长。
+
+### 2.10 `[build] cache` —— 依赖的全局构建缓存
+
+从索引取得的依赖，其编译产物会跨工程缓存在
+`$MCPP_HOME/build-cache/v1/` 下。一个依赖的产物不依赖于谁在消费它，
+所以两个工具链、profile 与依赖版本都相同的工程会复用同一个条目。
 
 ```toml
 [build]
-cache = "global"   # "global"(默认)| "local" | "off"
+cache = "global"   # "global" (default) | "local" | "off"
 ```
 
-| 模式 | 读缓存 | 写缓存 | 先清构建目录 |
+| 模式 | 读缓存 | 写缓存 | 先清空构建目录 |
 |---|---|---|---|
-| `global`(默认) | 是 | 是 | 否 |
+| `global`（默认） | 是 | 是 | 否 |
 | `local` | 否 | 否 | 否 |
 | `off` | 否 | 否 | 是 |
 
-`local` 把所有依赖都编在本工程 `target/` 内 —— 排障时一次性排除"是不是缓存的问题",
-也给 CI 一个无共享的可复现基线。`off` 额外清掉本次的 `target/<triple>/<fp>/` 做冷构建;
-`--no-cache` 是它的兼容别名。
+`local` 让每个依赖都在这个工程自己的 `target/` 里构建——用于在排查
+某个问题时排除缓存因素，也用于给 CI 一条不共享的基线。`off` 还会额外
+清空这次构建的 `target/<triple>/<fp>/` 以获得一次冷构建；
+`--no-cache` 是它的一个已废弃别名。
 
-优先级:`--cache <mode>` **>** `MCPP_BUILD_CACHE` **>** `[build] cache` **>** `global`。
-无法识别的值会被报出来(`--strict` 下为错误),而不是静默回落到 `global`。
+优先级：`--cache <mode>` **>** `MCPP_BUILD_CACHE` **>**
+`[build] cache` **>** `global`。一个无法识别的取值会被报告（`--strict`
+下是错误），而不是静默回落到 `global`。
 
-**不进缓存的**:`path` 与 `git` 依赖(任意深度)以及 workspace 成员。它们的源码可以在
-`name@version` 不变的情况下改变,任何基于该身份的键都看不见这种变化。
+**不会**被缓存的：`path` 与 `git` 依赖，不论层级多深，以及
+workspace 成员。它们的源码可以在 `name@version` 不变的情况下改变，
+所以没有任何基于那个身份的键能察觉到变化。
 
-查看与回收:
+查看与回收：
 
 ```
-mcpp cache dir                      # 缓存在哪
-mcpp cache list [--json]            # 条目、体积、最后使用时间
-mcpp cache info <pkg>@<ver>         # 单条目详情,含它是用什么键输入编出来的
-mcpp cache verify                   # 逐条目校验清单与磁盘
-mcpp cache gc --max-size 5GiB       # 按 LRU 收到容量预算内
-mcpp cache gc --older-than 30d      # 或按"多久没用过"回收
+mcpp cache dir                      # where the cache lives
+mcpp cache list [--json]            # entries, sizes, last use
+mcpp cache info <pkg>@<ver>         # one entry, including the key inputs it was built with
+mcpp cache verify                   # every entry's file list against the disk
+mcpp cache gc --max-size 5GiB       # LRU-collect package entries to a budget
+mcpp cache gc --older-than 30d      # ...or by how long since they were last used
 mcpp cache clean [--deps|--std|--all|--legacy]
 ```
 
-条目的磁盘布局是带版本的。改动布局的 mcpp 版本会**一次性作废全部旧条目**,
-所以升级后的第一次构建会重编依赖并重新填充 —— 不需要手工清理。
-2026.8.3.4 就是这样一次:条目里对象的地址现在相对**包**自身,
-而不再相对"最先填充这个条目的那个工程"的构建目录。
-`mcpp cache verify` 另外会报告任何逃出条目的记录地址,
-使这条不变量可以离线审计。
+磁盘上的条目布局是版本化的。一个改变了它的 mcpp 发布版，会一次性
+淘汰每一个旧条目，所以这样一次升级之后的第一次构建，会重建它的依赖
+并重新填充缓存——不需要手动清理任何东西。2026.8.3.4 做的正是这件事：
+一个条目的对象路径现在相对**包**寻址，而不再相对最先填充这个条目的
+那个工程的构建目录。`mcpp cache verify` 还会额外报告任何记录的地址
+逃出了自身范围的条目，使这类复发情况可以离线审计。
 
-### 2.11 `[runtime]` — provider-neutral 运行时契约
+### 2.11 `[runtime]` —— provider-neutral 运行时契约
 
 ```toml
 [runtime]
 requirements = [
-  { kind = "capability", value = "display.present", phase = "run", required = true },
+  { kind = "capability", value = "display.present", phase = "run", required = true,
+    discovery = "rpath-of-dispatch" },
   { kind = "soname", value = "libwidget.so.1", phase = "link", required = false },
 ]
 provides = ["display.present"]
@@ -1116,7 +1250,7 @@ artifacts = [
   { role = "library", path = "runtime/libwidget.so.1", provenance = "payload", abi = "elf-x86_64", digest = "sha256:...", host_fingerprint = "host-1" },
 ]
 
-# 平台无关 LinkIntent;路径相对本包根目录。
+# Platform-neutral LinkIntent. Paths are relative to this package root.
 libraries                = ["widget"]
 link_library_dirs        = ["lib"]
 transitive_needed_dirs   = ["runtime/closure"]
@@ -1125,19 +1259,19 @@ frameworks               = ["WindowKit"]
 deploy_files             = ["bin/widget.dll"]
 deploy                   = [ { from = "share/vulkan/icd.d/widget_icd.json", to = "vulkan/icd.d" } ]
 
-# 多 provider 时使用精确 canonical identity。
+# Use an exact canonical identity when multiple providers exist.
 [runtime."display.present"]
 provider = "acme.widget-runtime@2.0.0"
 ```
 
-本表中不受支持的键会被**报出并忽略**,消息里列出它比对用的那份键表。
-`[runtime.<capability>]` 子表是 provider 覆盖而不是键,因此不在清扫范围内。
-同一规则适用于 `[target.<predicate>.runtime]`,其词汇表是 `libraries`、
-`link_library_dirs` 与 `frameworks`(mcpp 2026.9.12.3+)
-(见[22 —— 目标侧](22-target-side.md))。该表上的 `frameworks` 追加在顶层列表
-之后,只在 Mach-O 各行渲染为 `-framework <name>`,其余各行不产生任何标志——
-当某个 framework 存在于 iOS 而不存在于 macOS(或相反)时,manifest 用这个键
-表达:
+这张表里一个不受支持的键会**被报告并被忽略**，消息会列出它核对过的
+那些键。一个 `[runtime.<capability>]` 子表是一处提供者覆盖，不是一个
+键，所以不会被扫入。同样的规则适用于 `[target.<predicate>.runtime]`，
+它的词汇是 `libraries`、`link_library_dirs` 与 `frameworks`
+（mcpp 2026.9.12.3+）（[22 —— 目标侧](22-target-side.md)）。那张表上的
+`frameworks` 会追加在顶层列表之后，只在 Mach-O 各行上渲染
+`-framework <name>`，在其它行上什么都不渲染——这是一份 manifest 在
+某个 framework 只存在于 iOS 而不存在于 macOS（或反过来）时要用的键：
 
 ```toml
 [runtime]
@@ -1150,158 +1284,187 @@ frameworks = ["AppKit"]
 frameworks = ["UIKit"]
 ```
 
-`requirements` 记录非空 `kind`/`value`、`link` 或 `run` 阶段,以及是否强制
-(`required` 默认 `true`)。`artifacts` 必须含 `role`、`path`、`provenance`;
-可选 requirement 仍保留为 provenance,但不会进入硬 ABI/doctor 输入。
-`libraries` 中显式的相对文件路径按声明包根目录解析;裸逻辑名仍按目标平台拼成库名。
-`abi`、`digest`、`host_fingerprint` 是可选证据。requester/provider 身份不由描述符
-填写:resolver 会用含 namespace、version、source/index provenance 的精确 PackageId
-给 requirement 和 artifact 盖章。因此描述符不能冒充别的包,
-`alpha.backend` 也不会与 `beta.backend` 混同。
-
-只有 `provides` 会创建描述符侧 provider fact;需要某能力绝不会让 requester 自动
-成为 provider。显式 `[runtime.<capability>] provider=` 接受 canonical
-`namespace.name@version`(或唯一无歧义的兼容拼写);不存在或同短名歧义都会 hard error。
-xlings SubOS 已选择的 provider/artifact fact 排在描述符 fallback 前。图形栈、driver、
-ICD、WSL 与 host provenance 选择由 xlings/xim 负责;mcpp 只记录、消费通用结果,
-不探测 GPU 硬件。
-
-LinkIntent 把不同发现阶段分开:
+`requirements` 记录一个非空的 `kind`/`value`，一个 `link` 或 `run`
+阶段，以及这条要求是否强制（`required` 默认 `true`）。
+
+`discovery` 是可选的，说明**加载器如何找到**满足这条要求的东西——
+例如 `rpath-of-dispatch`、`json-dir`、`glvnd-dispatch`。它是**被
+声明的，从不被推断**：一个能力用哪种机制是提供者的属性，会在 mcpp
+不知情的情况下改变，所以 mcpp 只是携带这个值，把一个未声明的情形
+报告为 `unknown`，而不是去猜。之所以专门设一个字段，是因为这些机制
+彼此不可互换——一种可能是烘焙进某个 dispatch 库里的搜索路径，另一种
+可能是一个持有*绝对*路径的 JSON 文件，「把这个目录整体拷过去」能
+满足一种，满足不了另一种。`mcpp pack` 把它写进 bundle 的
+`HOST-REQUIREMENTS`，`mcpp publish` 把它投影进描述符，两者出自同一份
+推导。可选要求仍然保留可见的来历信息，但不会成为硬性的 ABI 或 doctor
+输入。一条显式写成相对文件路径的 `libraries` 条目，相对声明它的包根
+目录解析；一个裸的逻辑名字仍然是一个按平台拼写的库名。`artifacts`
+要求 `role`、`path` 与 `provenance`；`abi`、`digest` 与
+`host_fingerprint` 是可选的佐证。是解析器而不是描述符，给每一条要求
+打上确切的请求方 PackageId，给每一个产物打上确切的声明提供方
+PackageId，包括命名空间、版本与来源/索引出处。因此一份描述符无法
+冒充另一个包，`alpha.backend` 永远不会被折叠进 `beta.backend`。
+
+只有 `provides` 会创建一个由描述符拥有的提供者事实。仅仅要求一项
+能力，永远不会让请求方成为它自己的提供者。一个显式的
+`[runtime.<capability>] provider=` 覆盖接受一个规范的
+`namespace.name@version`（或一个无歧义的兼容拼法）；缺失、或短名字
+有歧义的提供者是硬错误。已被 xlings SubOS 选定的提供者/产物事实，
+优先于描述符的回落值。xlings/xim 拥有图形栈、驱动、ICD、WSL 与宿主
+出处的选择权；mcpp 只记录并消费那个通用结果，从不探测 GPU 硬件。
+
+Link intent 把各个发现阶段分开处理：
 
 | 字段 | ELF | Mach-O | PE/Windows |
 |---|---|---|---|
 | `link_library_dirs` | `-L` | `-L` | `-L` 或 `/LIBPATH:` |
-| `transitive_needed_dirs` | `-Wl,-rpath-link` | 无 flag | 无 flag |
-| `runtime_search_dirs` | 只进 RUNPATH/rpath,绝不进 `-L` | 只进 rpath | 无 flag |
-| `frameworks` | 无 flag | `-framework` | 无 flag |
-| `deploy_files` | copy edge | copy edge | 复制到产物旁,绝不成为 linker flag |
-| `deploy` *(2026.9.12.2+)* | copy edge,复制到 `bin/<to>/` | copy edge,复制到 `bin/<to>/` | copy edge,复制到 `bin/<to>/`;绝不成为 linker flag |
-
-`deploy` 把文件放进相对可执行文件的目录;`deploy_files` 表达不了这一点,因为它把每一项都放在可执行
-文件旁。读取固定子目录的加载器需要它:macOS 上的 Vulkan loader 从 `<可执行文件目录>/vulkan/icd.d`
-读取驱动清单。每一项是恰好含两个字符串的表:`from` 相对声明它的包的根目录,`to` 相对可执行文件所在
-目录,`"."` 表示该目录本身。两者在所有宿主上都以 `/` 分隔,不得是绝对路径、不得指定盘符,也不得含
-空分量、`.` 或 `..` 分量;违反的项被拒绝,拒绝信息指出该项的序号。同一目标位置的两个来源被拒绝并指出
-目标位置,同名文件放进两个不同目录则不构成冲突。`deploy` 是独立的键而不是 `deploy_files` 的表形式:
-早于它的描述文件读取器在 `deploy_files` 中遇到 `{` 时不会终止,而对不认识的 `runtime` 键会跳过。`mcpp pack`
-把两个键的文件放到打包后可执行文件旁的同一相对位置。
-
-一个兼容发布周期内仍读取旧字段:`library_dirs` 只映射到运行期搜索;
-`dlopen_libs` 映射为必需的 run-phase soname requirement;`capabilities` 映射为必需的
-run-phase capability requirement。这些旧字段都不会创建 provider。
-
-`target/<triple>/<fp>/resolution.json` schema 2 持久化 RuntimeBinding、canonical
-requirements/providers/artifacts、LinkIntent、平台搜索机制与链接后 verdict。
-`mcpp why runtime` 只是最新存储文件的纯解释器:不重新解析 manifest,也不启动图形/
-硬件 probe。需要重新诊断所选 host provider 时使用 `xlings doctor`。
-
-每个 artifact 还带一个仅由路径算出的 `identity` 判定:
+| `transitive_needed_dirs` | `-Wl,-rpath-link` | 无旗标 | 无旗标 |
+| `runtime_search_dirs` | 仅 RUNPATH/rpath，从不是 `-L` | 仅 rpath | 无旗标 |
+| `frameworks` | 无旗标 | `-framework` | 无旗标 |
+| `deploy_files` | 拷贝边 | 拷贝边 | 拷贝到输出旁边；从不是链接器旗标 |
+| `deploy` *（2026.9.12.2+）* | 拷贝边，进 `bin/<to>/` | 拷贝边，进 `bin/<to>/` | 拷贝边，进 `bin/<to>/`；从不是链接器旗标 |
+
+`deploy` 把一个文件放进相对可执行文件的某个目录，而 `deploy_files`
+表达不了这一点，因为它把每一条都放在可执行文件旁边。一个读取固定
+子目录的加载器需要它：macOS 上的 Vulkan loader 从
+`<可执行文件目录>/vulkan/icd.d` 读取驱动 manifest。每一条都是恰好
+两个字符串组成的表。`from` 相对声明它的包根目录，`to` 相对可执行
+文件所在目录，`"."` 意味着那个目录本身。两者在每个宿主上都以 `/`
+分隔，都不能是绝对路径、不能命名一个驱动器、不能含有空、`.` 或 `..`
+组成部分；不满足的条目会被拒绝，拒绝信息点名它的索引。两个来源指向
+同一个目的地会被拒绝并点名那个目的地，而一个文件名出现在两个不同
+目录下不算冲突。`deploy` 是一个独立的键，而不是 `deploy_files` 的
+表格形式，因为一个早于它出现的描述符读取器，遇到 `deploy_files` 里的
+`{` 会无法终止，而它会跳过一个不认识的 `runtime` 键。`mcpp pack` 把
+这两个键指向的文件，以打包出的可执行文件为参照，拷贝到同样的相对
+路径。
+
+对于一批兼容性字段，`library_dirs` 只映射到运行时搜索，`dlopen_libs`
+映射到必需的运行期 soname 要求，`capabilities` 映射到必需的运行期
+能力要求。这些遗留字段都不创建提供者。
+
+`target/<triple>/<fp>/resolution.json` schema 2 存储 RuntimeBinding、
+规范化后的要求/提供者/产物、LinkIntent、平台发现机制与链接后判定。
+`mcpp why runtime` 是对最新存储文件的一个纯粹解读器：它既不会重新
+解析 manifest，也不会启动一次图形/硬件探测。当被选中的宿主提供者
+自身需要重新诊断时，用 `xlings doctor`。
+
+每个产物还携带一个仅从路径计算出的 `identity` 判定：
 
 | `identity` | 含义 |
 |---|---|
-| `ok` | 声明的路径(穿过符号链接后)落在声明的那个版本里 |
-| `mismatch` | 它解析到了别处 —— **该 binding 已陈旧**,后来的某次安装把它重新指向了别的地方 |
-| `missing` | 声明了,但那个路径上什么都没有 |
-| `unverified` | 声明时没有可供比对的版本 |
+| `ok` | 声明的路径（经符号链接）解析到声明的版本 |
+| `mismatch` | 它解析到了别处——**绑定已过期**，某次更晚的安装重新指向了它 |
+| `missing` | 已声明，但那个路径上什么都没有 |
+| `unverified` | 声明时没有给出可供核对的版本 |
 
-这就是 mcpp 早已施加于私有 libc 的那条规则的推广(`glibc@2.44` 解析到那一份载荷;
-陈旧或缺失是错误,而绝不是「已安装版本里哪个看起来能用就用哪个」)。它不需要知道
-该 artifact 做什么。`unverified` **有意**不等于 `ok`:一个解析到了却没有 artifact
-在其背后的 provider 并未被核验过,因此 `mcpp why runtime` 打印
-`(not declared by the environment — nothing to verify)` 而不是 `(none)`。
+这正是 mcpp 已经在对私有 libc 应用的那条规则（`glibc@2.44` 解析到
+那一份载荷；过期或缺失是错误，绝不是「随便一个装着的、看起来能用的
+版本」）的推广。它不需要知道这个产物是做什么的。`unverified` 刻意
+不等于 `ok`：一个已解析、背后却没有产物的提供者尚未被核对过，
+`mcpp why runtime` 会说
+`(not declared by the environment — nothing to verify)`，
+而不是 `(none)`。
 
-能力名使用分层小写 `domain.sub.role`(如 `display.present`)和前缀类
-`abi:<name>`(如 `abi:glibc`,参与工具链 ABI 强制)。
+能力名使用分层的小写 `domain.sub.role`（例如 `display.present`）与
+前缀式的 `abi:<name>`（例如参与工具链 ABI 强制检查的 `abi:glibc`）。
 
-### 2.12 `[package] platforms` — 平台声明
+### 2.12 `[package] platforms` —— 平台声明
 
 ```toml
 [package]
 platforms = ["linux", "macos", "windows", "ios", "android", "emscripten"]
 ```
 
-声明包支持的平台(CI 矩阵提示,经 `mcpp why` 展示)。词表由 mcpp 固定
-(它拥有 target/triple 体系):`linux | macos | windows | ios | android |
-emscripten`(mcpp 2026.9.12.3+;`ios`、`android`、`emscripten` 是新加入的——
-此前的词表是 `linux | macos | windows`);未知值 warning,`--strict` 下报错。
+声明这个包支持的平台（一条 CI 矩阵提示，经 `mcpp why` 展示）。词汇由
+mcpp（拥有 target/triple 体系的一方）固定：
+`linux | macos | windows | ios | android | emscripten`
+（mcpp 2026.9.12.3+；`ios`、`android` 与 `emscripten` 是这套此前只有
+`linux | macos | windows` 的词汇新增的成员）；未知取值会产生警告，
+`--strict` 下是错误。
 
-一个平台名就是目标三元组的 `os`,除非某个 `env` 自己命名了一个平台。Android
-各行的 `os = "linux"`、`env = "android"`,所以这份列表里的 `linux` 不覆盖
-它们——服务 Android 的包要另写 `android`。Web 行保留自己的 `os` 单词
-`emscripten`,与 `cfg(...)` 选择器语法用的是同一个词;不存在 `web` 这种拼法。
+一个平台名就是目标三元组的 `os`，除非一个自己命名了平台的 `env`
+优先。Android 各行的 `os = "linux"`、`env = "android"`，所以这份
+列表里的 `linux` 不覆盖它们——一个服务 Android 的包要额外写出
+`android`。Web 这一行保留自己的 `os` 单词 `emscripten`，与
+`cfg(...)` 选择器语法用的是同一个词；没有 `web` 这种拼法。
 
-对库目标执行 `mcpp pack` 时,会拿这条声明与**实际产出的腿**核对 —— 那是第一个
-有证据可核的时刻:
+`mcpp pack` 在一个库目标上，会拿这条声明与它实际产出的那些腿核对，
+因为这是第一个有证据可供核对的时刻：
 
-| 情况 | 结果 |
+| 情形 | 结果 |
 |---|---|
-| 某条腿的平台不在此列 | warning —— manifest 否认了一个包明明能服务的平台 |
-| 声明了某平台却没有对应的腿,**且本宿主本来就能构建它** | warning —— 该平台的消费者会解析到这个包却找不到产物 |
-| 声明了某平台却没有对应的腿,而本宿主根本构建不了它 | **不说话** |
+| 某条腿为一个这里没列出的平台打了包 | 警告——manifest 否认了一个这个包明显在服务的平台 |
+| 一个列出的平台没有对应的腿，**并且这台宿主本可以构建出一份** | 警告——那里的消费者会解析到这个包，却找不到产物 |
+| 一个列出的平台没有对应的腿，但这台宿主构建不出那个平台的产物 | **无声** |
 
-第三行才是这个检查可用的原因。正常的发布流程是 CI 上每平台各跑一次
-`mcpp pack`,于是 Linux runner 永远不会产出 macOS 腿 —— 为此告警会在每个跨平台
-包的每一次运行中触发,而**永远触发的告警会把真正该看的那条盖掉**。「本宿主能不能
-构建」与 `--target` 回答的是同一个问题(docs/08 §7.4)。
+第三行正是这项检查之所以可用的原因。正常的发布流程是在 CI 里为每个
+平台各跑一次 `mcpp pack`，所以一台 Linux runner 从不会产出一条
+macOS 的腿——如果对此发出警告，会在每个跨平台包的每一次运行上触发，
+而一条总是触发的警告会掩盖真正要紧的那一条。「这台宿主本可以构建」
+指的是与 `--target` 回答的同一个问题（docs/08 §7.4）。
 
-两者都只是 warning,绝不报错:覆盖度属于发布纪律,而能作判断的人看的是发布,
-不是这一次构建。
+两者都只是警告，从不是错误：覆盖度是发布纪律的一部分，能判断它的人
+是在看发布本身，而不是在看这一次构建。
 
-### 2.12b `[package] accelerators` — 加速器声明
+### 2.12b `[package] accelerators` —— 加速器声明
 
 ```toml
 [package]
 accelerators = ["cuda", "rocm"]
 ```
 
-声明该包支持的加速器后端。与 `platforms` 同形:一个意图声明与 CI 矩阵提示,
-由 `mcpp why` 展示,**不是门**。
+声明这个包支持的加速器后端。与 `platforms` 对称：一条意图陈述与一条
+CI 矩阵提示，经 `mcpp why` 展示，从不是一道闸。
+
+它与产物的 `accel` 字段刻意区分开。声明是手写的，可以是愿景；`accel`
+是从产出某个二进制的那次构建里实测得到的，也是消费者被拒绝时所对照
+的那个值。见[42 —— 异构构建](42-heterogeneous-builds.md)。
 
-与产物的 `accel` 字段刻意不同。声明由人手写、可以是期望值;`accel` 是从产生该二进制的
-那次构建测量出来的,并且是消费者被拒绝时所依据的东西。见
-[42 — 异构硬件构建](42-heterogeneous-builds.md)。
 ### 2.13 `[xlings]` —— 工程的环境
 
-已移入 [23 —— 项目环境](23-the-project-environment.md)。
+已移至 [23 —— 工程的环境](23-the-project-environment.md)。
 
 ### 2.14 依赖产出的 host 工具
 
-已移入 [30 —— build.mcpp](30-build-mcpp.md)。
-
+已移至 [30 —— build.mcpp](30-build-mcpp.md)。
 
-### 2.15 `[resources]` —— 编译进产物的元数据与资产(2026.8.7.1+)
+### 2.15 `[resources]` —— 编译进产物的元数据与资产（2026.8.7.1+）
 
-exe 图标,以及 Windows 在文件「属性」里显示的版本信息,就是 `mcpp.toml` 里的一个路径:
+一个 exe 图标，以及 Windows 在文件属性对话框里展示的版本元数据，在
+`mcpp.toml` 里不过是一条路径，别无其它：
 
 ```toml
 [resources]
 icon = "assets/app.ico"
 ```
 
-常见场景到此为止。`FILEVERSION`、`ProductName`、`FileDescription`、`CompanyName`、
-`LegalCopyright` 全部从 `[package]` 取默认值,资源脚本由 mcpp 生成。
+这就是常见情形的全部。`FILEVERSION`、`ProductName`、
+`FileDescription`、`CompanyName` 与 `LegalCopyright` 全都从
+`[package]` 取默认值，资源脚本由 mcpp 自动生成。
 
 | 键 | 类型 | 含义 |
 |---|---|---|
-| `icon` | 路径 | 作为应用图标嵌入(资源序号 1) |
-| `files` | 路径列表 | 工程自带的 `.rc` 脚本,mcpp 编译并**跟踪**为构建输入 |
-| `extra-inputs` | 路径列表 | `.rc` 扫描器看不见的输入(见下) |
-| `version-info` | 布尔 | `false` 表示不要生成版本资源 |
+| `icon` | 路径 | 作为应用图标嵌入（资源序号 1） |
+| `files` | 路径列表 | 自行编写的 `.rc` 脚本，会被编译并**追踪**为构建输入 |
+| `extra-inputs` | 路径列表 | `.rc` 扫描器看不见的输入（见下） |
+| `version-info` | 布尔值 | `false` 退出自动生成版本资源 |
 | `[resources.version-info]` | 表 | `company`、`product`、`description`、`copyright`、`original-filename`、`internal-name` |
 
-**只有 PE 目标会*编译*这一节。** 在 Linux/macOS 上它**不适用**:不产资源单元、
-不出诊断、构建逐字节不变。**无需**(也不能)加 `cfg(windows)` 谓词 ——
-无条件写一次即可。
+**只有 PE 目标会*编译*它。** 在 Linux 与 macOS 上，这一节*不适用*：
+没有资源单元、没有诊断、构建逐字节相同。**不需要**（也不能用）一个
+`cfg(windows)` 谓词——写一次，无条件生效即可。
 
-**声明了却不存在的文件会让构建失败 —— 在每个目标上都是。** 资源和源码一样是
-构建输入;mcpp 不会悄悄产出一个缺了它的二进制。校验刻意**不**按 PE 设门:
-路径是否存在是关于工作树的事实,不是关于目标的事实,所以 `icon = "assets/app.ico"`
-里的拼写错误由 Linux/macOS 构建(以及对应的 CI job)当场抓住,而不是等
-Windows 那条。不想要图标,把那一行删掉。
+**一个声明了却不存在的文件会让构建失败——在每一个目标上都一样。**
+一份资源和一个源文件一样是构建输入；mcpp 不会悄悄发布一个缺了它的
+二进制。校验刻意**不**只针对 PE：一个路径是否存在，是工作树的一个
+事实，与目标无关，所以 `icon = "assets/app.ico"` 里的一个笔误，会被
+Linux 或 macOS 的构建（以及它们的 CI 作业）捕获，而不必等到 Windows
+那一份。要省略图标，删掉这一行即可。
 
-**版本字段。** `FILEVERSION` 取 `[package].version` 的四段数值,每段必须放得进
-16 位;字符串字段保留版本原文,所以数值字段装不下的形态(`1.0.0-rc1`)在属性
-对话框里照样看得到。
+**版本字段。** `FILEVERSION` 取 `[package].version` 的四个数字段，
+每一段都必须落在 16 位以内；字符串字段按原样保留版本号，所以一个
+数字字段容纳不了的形式（`1.0.0-rc1`），仍然会原样出现在属性对话框里。
 
 #### 自写 `.rc`
 
@@ -1310,37 +1473,41 @@ Windows 那条。不想要图标,把那一行删掉。
 files = ["res/app.rc"]
 ```
 
-写了 `files`,mcpp 就不再生成版本资源 —— 资源 ID 空间由工程自行支配。两者都需要时同时写
-`version-info = true`(注意冲突:序号 1 的 `RT_VERSION` 只能有一个)。
+设置了 `files` 之后，mcpp 停止生成版本资源，资源 ID 空间归工程所有。
+若两者都要，连同它一起设 `version-info = true`（注意会相撞：序号 1
+上只能有一个 `RT_VERSION`）。
 
-想从生成的脚本起步而不是从空文件起步:把它从构建目录里拷出来
-(`target/<triple>/<fp>/res/<target>.mcpp.rc`)填进 `files`。结果**字节相同**,
-所以从「生成」走到「手写」不会改变产物。
+要从生成的脚本出发，而不是从一个空文件开始，把它从构建目录里拷出来
+（`target/<triple>/<fp>/res/<target>.mcpp.rc`）并列进 `files`。结果
+逐字节相同，所以从生成切换到手写，不会改变实际发布的内容。
 
-> **`VS_VERSION_INFO` 需要 `<windows.h>`。** 手写脚本里如果写
-> `VS_VERSION_INFO VERSIONINFO` 而没有 `#include <windows.h>`,版本资源会被存成
-> **字符串名**而不是序号 1。所有工具依然报告 `Type: VERSIONINFO`,但
-> `GetFileVersionInfo` 查的是序号,于是 PowerShell 的 `FileVersionInfo` 里每个字段
-> 都是空的。要么 include `<windows.h>`,要么直接写 `1 VERSIONINFO`。mcpp 见到这个
-> 形状会警告;它自己生成的脚本用的是字面 `1`。
+> **`VS_VERSION_INFO` 需要 `<windows.h>`。** 在一份手写脚本里，
+> `VS_VERSION_INFO VERSIONINFO` 若没有 `#include <windows.h>`，会把
+> 版本资源归档到一个*字符串*名字下，而不是序号 1。每个工具仍会报告
+> `Type: VERSIONINFO`，但 `GetFileVersionInfo` 查的是序号，所以
+> PowerShell 的 `FileVersionInfo` 会显示每个字段都是空的。要么包含
+> `<windows.h>`，要么写 `1 VERSIONINFO`。mcpp 看到这种写法时会警告；
+> 它自己生成的脚本用的是字面量 `1`。
 
 #### 被跟踪的输入
 
-mcpp 会读 `.rc`,把引号形式的 `#include` 和资源语句(`ICON`、`RCDATA`、
-`MANIFEST` …)点名的文件都变成构建输入,所以改图标会重链。尖括号形式
-(`<windows.h>`)属于工具链,由工具链 fingerprint 覆盖。
+mcpp 读取 `.rc` 里带引号的 `#include`，以及资源语句（`ICON`、
+`RCDATA`、`MANIFEST` 等）命名的文件，并把它们变成构建输入，所以修改
+图标会触发重新链接。尖括号 include（`<windows.h>`）属于工具链，由
+工具链指纹覆盖，而不是这项扫描。
 
-通过宏间接引用的文件名(`1 ICON APP_ICON`)扫描看不见。mcpp 会**指名**它没能解析
-的东西,并要求显式声明:
+一个经由宏到达的文件名（`1 ICON APP_ICON`）对这项扫描是不可见的。
+mcpp 会点名它无法解析的部分，并要求显式声明：
 
 ```toml
 extra-inputs = ["assets/app.ico"]
 ```
 
-#### 其余一切:`role = "object"`
+#### 其余一切：`role = "object"`
 
-不是资源脚本的输入 —— `objcopy` 嵌入的 blob、生成的 `.def`、预编译对象 ——
-可以由构建程序声明一个产出接到链接的图节点:
+对于不是资源脚本的输入——一段用 `objcopy` 嵌入的二进制数据、一份
+生成的 `.def`、一个预构建的对象文件——构建程序可以声明一个构建图
+节点，把它的输出并入链接：
 
 ```cpp
 mcpp::action o;
@@ -1348,46 +1515,49 @@ o.id = "blob"; o.role = "object";
 o.arg("./mkblob.sh").arg("blob.bin").arg("${mcpp.out_dir}/blob.o")
  .input("blob.bin")
  .output("${mcpp.out_dir}/blob.o")
- .target("myapp")        // 省略:接到每个镜像,含测试二进制
+ .target("myapp")        // omit: every image, test binaries included
  .submit();
 ```
 
-见 [30 — build.mcpp](30-build-mcpp.md)。把这类文件写进 `[build].ldflags` 也「能用」,
-但 ldflags 是链接命令里的一串字符:没有任何东西跟踪它,改了它得到的是
+见 [30 —— build.mcpp](30-build-mcpp.md)。把这样一个文件名写进
+`[build].ldflags` 也「能用」，但 ldflags 在链接命令里是一段扁平
+字符串：没有任何东西追踪它，修改这个文件会得到
 `ninja: no work to do`。
+
 ### 2.16 `[hooks]` —— 项目构建生命周期命令
 
-已移入 [09 —— 按场景选命令](09-commands-by-scenario.md)。
+已移至 [09 —— 按场景选命令](09-commands-by-scenario.md)。
 
 ### 2.17 `[test]` —— 测试程序的位置
 
 ```toml
 [test]
-discover = ["tests/**/*.cpp"]    # 默认值
+discover = ["tests/**/*.cpp"]    # the default
 ```
 
 | 键 | 类型 | 含义 |
 |---|---|---|
-| `discover` | glob 数组 | glob 匹配到的每个文件都是一个测试程序;以 `!` 开头的 glob 去掉它匹配到的文件;`[]` 不发现任何测试 |
-
-glob 使用 `[build] sources` 的词汇。测试的名字是它相对于第一个匹配它的 glob 的固定
-目录的路径,去掉扩展名。同名的两个文件会被拒绝,并点名两者。值不是非空字符串数组时
-报错;`[test]` 中的其他键给出警告,在 `--strict` 下为错误。测试模型见
-[08 —— 测试](08-testing.md)。
+| `discover` | glob 数组 | 每个被某条 glob 匹配到的文件都是一个测试程序；以 `!` 开头的 glob 会移除它匹配到的文件；`[]` 不发现任何测试 |
 
+这些 glob 使用与 `[build] sources` 相同的词汇。一个测试的名字，是它
+相对第一条匹配到它的 glob 所在的固定目录的路径，去掉扩展名。两个
+同名文件会被拒绝，并点名两者。一个不是「非空字符串数组」的取值是
+一个错误；`[test]` 里的其它任何键都是警告，`--strict` 下是错误。
+测试模型见[08 —— 测试](08-testing.md)。
 
 ## 3. 实战示例
 
-其中四个是**可运行的工程**而不是片段,而工程是更好的答案:它能构建,而且由 CI 检查。
+其中四个是可运行的工程，而不是片段，工程是更好的答案：它能构建，并且
+由 CI 检查。
 
 | 形态 | 运行 |
 |---|---|
 | 一个 hello world | [`examples/01-hello`](../../examples/01-hello/) |
-| 带测试的模块化库 | [`examples/11-features`](../../examples/11-features/) |
-| 带依赖的应用 | [`examples/02-with-deps`](../../examples/02-with-deps/) |
-| 交叉编译的静态发布 | [`examples/03-pack-static`](../../examples/03-pack-static/) |
+| 一个带测试的模块库 | [`examples/11-features`](../../examples/11-features/) |
+| 一个带依赖的应用 | [`examples/02-with-deps`](../../examples/02-with-deps/) |
+| 一次交叉编译的静态发布 | [`examples/03-pack-static`](../../examples/03-pack-static/) |
 
-还有两种形态暂时没有对应示例,以 manifest 的形式留在这里。
+有两种形态目前还没有示例，以 manifest 的形式留在这里。
 
 ### 3.4 纯 C 库
 
@@ -1405,7 +1575,7 @@ sources      = ["src/**/*.c"]
 kind = "lib"
 ```
 
-### 3.5 混合 C / C++23 模块项目
+### 3.5 混合 C / C++23 模块工程
 
 ```toml
 [package]
@@ -1417,34 +1587,34 @@ include_dirs = ["include"]
 c_standard   = "c11"
 
 [dependencies]
-lua = "5.4.7"     # 纯 C 库,mcpp 自动用 C 编译器编译 .c 文件
+lua = "5.4.7"     # Pure C library; mcpp compiles .c files with the C compiler automatically
 
 [targets.hybrid]
 kind = "bin"
 ```
 
-
 ## 4. 约定与默认值速查
 
-| 项目 | 默认值 | 说明 |
+| 项 | 默认值 | 说明 |
 |---|---|---|
 | 源文件 | `src/**/*.{cppm,cpp,cc,c,S,s,asm}` | 自动递归扫描 |
-| 入口 | `src/main.cpp` | 有这个文件就推断为 `bin` 目标 |
-| 库根 | `src/<pkg-tail>.cppm` | 可用 `[lib].path` 覆盖 |
-| C++ 标准 | `c++23` | 用 `[package].standard` 配置; 支持 `c++20` / `c++26` / `c++2a` / `c++2c` / `gnu++NN` / `c++latest` / `c++fly`(实验试验场) |
-| C 标准 | `c11` | `.c` 文件自动走 C 编译器 |
-| 静态 stdlib | `true` | 便携二进制 |
-| 头文件 | `include/`(如果存在） | 自动加到 `-I` |
-| 测试 | `tests/**/*.cpp` | `mcpp test` 自动发现;`[test] discover` 替换这个集合 |
-| 依赖命名空间 | `mcpplibs`(默认) | 裸 selector 只表示该精确 ns |
+| 入口点 | `src/main.cpp` | 这个文件存在时，会推断出一个 `bin` 目标 |
+| 库根 | `src/<包名的最后一段>.cppm` | 用 `[lib].path` 覆盖 |
+| C++ 标准 | `c++23` | 用 `[package].standard` 配置；支持 `c++20` / `c++26` / `c++2a` / `c++2c` / `gnu++NN` / `c++latest` / `c++fly`（实验性试验场） |
+| C 标准 | `c11` | `.c` 文件自动经由 C 编译器处理 |
+| 静态 stdlib | `true` | 可移植二进制 |
+| 头文件 | `include/`（若存在） | 自动加入 `-I` |
+| 测试 | `tests/**/*.cpp` | 由 `mcpp test` 自动发现；`[test] discover` 替换这个集合 |
+| 依赖命名空间 | `mcpplibs`（默认） | 一个裸选择器只匹配这一个精确命名空间 |
 
 ### 4.1 旧 `[language]` 兼容层
 
-旧配置仍可读取:
+旧的配置仍然可以被读取：
 
 ```toml
 [language]
 standard = "c++26"
 ```
 
-新项目请使用 `[package].standard`。如果两个位置都出现，`[package].standard` 是权威配置。
+新工程应使用 `[package].standard`。若两处都写了，以
+`[package].standard` 为准。
diff --git a/docs/zh/05-dependencies.md b/docs/zh/05-dependencies.md
index 6b7111def..654923815 100644
--- a/docs/zh/05-dependencies.md
+++ b/docs/zh/05-dependencies.md
@@ -1,22 +1,22 @@
 # 05 —— 依赖与解析
 
-**读者:**构建里已经不只有自己代码的作者。
+**读者：** 构建里已经不只有自己代码的作者。
 
-**本章回答的那一个问题:**一个依赖从哪里来,版本约束是什么意思,以及两个约束
-不一致时会发生什么。
+**本章回答的那一个问题：** 一个依赖从哪里来，一条版本约束是什么意思，以及两条
+约束不一致时会发生什么。
 
-**不在这里:**什么使两个包成为同一个包 —— 那是
-[SPEC-001](../specs/package-identity.md),本章施用它而不复述它;以及怎么发布一个包,
-那是 [11 —— 发布一个库](11-publishing-a-library.md)。
+**不在这里：** 什么使两个包成为同一个包 —— 那是
+[SPEC-001](../specs/package-identity.md)，本章施用它而不复述它；以及怎样发布
+一个包，那是 [11 —— 发布一个库](11-publishing-a-library.md)。
 
-在此之前:[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) 是这些表与其余表同处的
-地方。在此之后:[06 —— Feature 与能力](06-features-and-capabilities.md) 讲一个依赖
-怎么变成可选的。
+在此之前：[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) 是这些表与其余表同处
+的地方。在此之后：[06 —— Feature 与能力](06-features-and-capabilities.md) 讲
+一个依赖怎样变成可选的。
 
-## `[dependencies]` — 运行时依赖
+## `[dependencies]` —— 运行时依赖
 
-**推荐写法是带精确版本的 dotted selector。** dotted 形式点名的是**一个身份** ——
-最后一段是包名,之前所有段都是 namespace —— 因此解析到什么,不取决于当前配置了
+**推荐写法是带精确版本的点式选择器。** 点式形式点名的是**一个身份** —— 最后
+一段是包名，之前所有段都是 namespace —— 因此解析到什么，不取决于当前配置了
 哪些 namespace。
 
 ```toml
@@ -27,19 +27,19 @@ imgui.backend.glfw_opengl3 = "0.0.1"
 mcpplibs.capi.lua          = "0.0.3"
 ```
 
-裸名也被接受,它经由默认 namespace(`mcpplibs`)解析 —— 在只用那一个 namespace 的
-工程里方便,在不是的工程里有歧义:
+裸名也被接受，它经由默认 namespace（`mcpplibs`）解析 —— 在只用那一个
+namespace 的工程里方便，在不是的工程里有歧义：
 
 ```toml
 [dependencies]
-cmdline = "0.0.2"        # 解析为 mcpplibs.cmdline
+cmdline = "0.0.2"        # resolves to mcpplibs.cmdline
 ```
 
 <details>
-<summary>等价拼法:namespace 子表</summary>
+<summary>等价拼法：namespace 子表</summary>
 
-把同一 namespace 下的条目归组。它解析到的身份与 dotted 形式完全相同,在许多依赖
-共享一个 namespace 时值得用。
+把同一 namespace 下的条目归组。它解析到的身份与点式形式完全相同，在许多依赖
+共享一个 namespace 时值得使用。
 
 ```toml
 [dependencies.mcpplibs]
@@ -48,59 +48,61 @@ tinyhttps = "0.2.2"
 llmapi    = "0.2.5"
 
 [dependencies.compat]
-glfw = "3.4"                    # 显式 namespace,不做回退搜索
+glfw = "3.4"                    # Explicit namespace; no fallback search
 ```
 
 </details>
 
 ```toml
-# 路径依赖(本地开发)
+# Path dependency (local development)
 [dependencies]
 mylib = { path = "../mylib" }
 ```
 
 ```toml
-# Git 依赖 —— tag / branch / rev 三选一
+# Git dependency — pick exactly one of tag / branch / rev
 [dependencies]
 mylib = { git = "https://github.com/user/mylib.git", tag = "v1.0.0" }
 applib = { git = "https://github.com/user/applib.git", branch = "develop" }
 ```
 
 ```toml
-# 长式 dep spec:features 与 backend 旋钮
+# Long-form dep spec: features and backend knobs
 [dependencies]
-imgui = { version = "0.0.3", features = ["docking"] }   # 请求该依赖的 feature
-widget = { version = "1.0", backend = "glfw_opengl3" }  # 糖:= features=["backend-glfw_opengl3"]
+imgui = { version = "0.0.3", features = ["docking"] }   # Request a feature of this dependency
+widget = { version = "1.0", backend = "glfw_opengl3" }  # Sugar for: features=["backend-glfw_opengl3"]
 ```
 
-`backend = "<impl>"` 是**通用约定糖**:1:1 脱糖为请求该依赖的 `backend-<impl>`
-feature(库若支持该旋钮,应在自己的 `[features]` 中声明 `backend-*` 系列)。
-若目标包声明了 `[features]` 但不含所请求的 feature(含 backend 脱糖结果),
-默认给出 warning,`mcpp build --strict` 下报错。
+`backend = "<impl>"` 是**通用的约定糖衣**：它 1:1 脱糖为请求该依赖的
+`backend-<impl>` feature（库若支持这个旋钮，应在自己的 `[features]` 中声明
+一族 `backend-*`）。若目标包声明了 `[features]` 但不含所请求的 feature
+（包括 backend 脱糖的结果），默认给出 warning，`mcpp build --strict` 下报错。
 
-**Git 依赖与 `mcpp.lock`**:`tag` 和 `rev` 本身就指向历史中的固定点,而 `branch`
-是会动的。首次构建把分支解析成一个 commit 并写进 `mcpp.lock`,此后每次构建都重建
-**那个** commit —— lock 是权威而不是缓存提示,所以删掉 `~/.mcpp/git` 或换一台机器
-都不会静默切换到更新的分支头。需要新的分支头时,必须显式指定:
+**Git 依赖与 `mcpp.lock`**:`tag` 和 `rev` 已经指向历史中的一个固定点，而
+`branch` 是会移动的。首次构建把分支解析成一个 commit 并写进 `mcpp.lock`,
+此后每次构建都重新构建**那个** commit —— lock 是权威来源而不是缓存提示，
+所以删掉 `~/.mcpp/git` 或换一台机器，都不会静默切换到更新的分支头。要用新的
+分支头，必须显式请求：
 
 ```bash
-mcpp update mylib     # 丢掉记录的 commit,下次构建重新解析
-mcpp update           # 同上,对所有依赖
+mcpp update mylib     # drop the recorded commit; the next build re-resolves it
+mcpp update           # same, for every dependency
 ```
 
-既然记录的 commit 已经足以决定构建什么,那么在 `~/.mcpp/git` 里已有克隆的情况下,
-重新构建完全不发网络请求,`--offline` 下照常工作。只有两件事需要网络:解析一个在
-lock 里没有 commit 的分支,以及克隆一个尚未缓存的 commit。`git =` 若指向本地目录
-(或 `file://` URL),这两件事都不需要网络,因此离线下也绝不会被拒绝。
+既然记录下来的 commit 已经足以决定构建什么内容，那么在 `~/.mcpp/git` 里已有
+克隆的情况下，重新构建完全不发出网络请求，在 `--offline` 下照常工作。只有两件
+事需要网络：解析一个在 lock 里没有 commit 的分支，以及克隆一个尚未缓存的
+commit。`git =` 指向本地目录（或 `file://` URL）时，这两件事都不需要，因此
+离线状态下从不会被拒绝。
 
 **SemVer 约束**:
 
 ```toml
 [dependencies]
-foo = "^1.2.3"      # >= 1.2.3, < 2.0.0 (caret,默认)
+foo = "^1.2.3"      # >= 1.2.3, < 2.0.0 (caret, default)
 bar = "~1.2.3"      # >= 1.2.3, < 1.3.0 (tilde)
-baz = "=1.2.3"      # 精确匹配
-qux = ">=1.0, <2.0" # 范围组合
+baz = "=1.2.3"      # Exact match
+qux = ">=1.0, <2.0" # Range combination
 ```
 
 ### `visibility` —— 一个依赖的用法是否跨越本包自己的边界
@@ -110,57 +112,60 @@ qux = ">=1.0, <2.0" # 范围组合
 sdk = { version = "1.0", visibility = "private" }
 ```
 
-每条依赖边都带一个 `visibility`,默认 `public`。它决定该依赖对消费方提出的要求
-——`provides`/`requires` 之外,头文件目录、宏定义与 flag——只到达本包自己的
-翻译单元,还是同时到达本包的**消费方**。
+每条依赖边都带一个 `visibility`，默认 `public`。它决定该依赖对消费方提出的
+要求 ——`provides`/`requires` 之外，头文件目录、宏定义与 flag —— 只到达本包
+自己的翻译单元，还是同时到达本包的**消费方**。
 
 | 取值 | 本包自己的翻译单元 | 本包的消费方 |
 |---|---|---|
-| `public`(默认) | 是 | 是 |
+| `public`（默认） | 是 | 是 |
 | `private` | 是 | **否** |
 | `interface` | 否 | 是 |
 
-`private` 是实现细节的常规情形:一个被 vendor 进来的库,或者一个包为实现某个
-功能而需要、但自己的接口并不暴露的平台 SDK。`interface` 是更少见的反向情形——
-本包自己的头文件会 `#include` 这个依赖,但本包从不编译链接它的目标文件。
-`public` 是大多数依赖想要的:依赖的某个类型出现在本包自己的公开头文件里,
-消费方就需要同一条头文件搜索路径才能用到它们。
+`private` 是实现细节的常规情形：一个被 vendor 进来的库，或者一个包为实现
+某项功能而需要、但自己的接口并不暴露的平台 SDK。`interface` 是更少见的反向
+情形 —— 本包自己的头文件会 `#include` 这个依赖，但本包从不编译链接它的目标
+文件。`public` 是大多数依赖想要的：依赖的某个类型出现在本包自己的公开头文件
+里，消费方就需要同一条头文件搜索路径才能用到它们。
 
-在某一个方向上写错是静默的(不必要的 `public` 把没人要的头文件广播出去),
-在另一个方向上则是构建失败——在第一个需要 `private` 所隐藏之物的消费方那里
-——这是更安全的失败方式,也是为什么 `[feature-deps.<feature>]`
-(见 06 —— "平台 SDK 依赖保持私有")要显式写出 `private`,而不是依赖一个
-恰好在没有消费方之前都能用的默认值。
+在其中一个方向上写错是静默的（不必要的 `public` 把没人要的头文件广播
+出去），在另一个方向上则是构建失败 —— 发生在第一个需要 `private` 所隐藏之物
+的消费方那里 —— 这是更安全的失败方式，也是为什么 `[feature-deps.<feature>]`
+（见 [06 ——「平台 SDK 依赖保持私有」](06-features-and-capabilities.md#平台-sdk-依赖保持私有)）
+要显式写出 `private`，而不是依赖一个恰好能用、直到有消费方加入才会露馅的
+默认值。
 
 ### 同一依赖两条声明冲突的处理
 
 依赖图里的两条边可能指向同一个身份 —— 同一个 `(namespace, name)` 二元组 ——
-却来自图中两个不同的位置:根 manifest 与某个依赖自己的 `[dependencies]`,或者
-两个互不相干的依赖。一条声明有一个**种类**(`version`、`git` 或 `path`)和该种
-类下的一个**引用**(一条 SemVer 约束、一个 `git` URL 加 `rev`/`tag`/`branch`,
-或一个文件系统路径)。mcpp 只解析这个身份一次;每个请求方的边都会被记录,而
-其中一个请求方的声明决定了同一身份下所有其他请求方拿到的是什么。
+却来自图中两个不同的位置：根 manifest 与某个依赖自己的 `[dependencies]`，
+或者两个互不相干的依赖。一条声明有一个**种类**（`version`、`git` 或
+`path`）和该种类下的一个**引用**（一条 SemVer 约束、一个 `git` URL 加
+`rev`/`tag`/`branch`，或一个文件系统路径）。mcpp 只解析这个身份一次；每个
+请求方的边都会被记录，其中一个请求方的声明决定了同一身份下所有其他请求方
+拿到的是什么。
 
 | 第一条声明 | 第二条声明 | 结果 |
 |---|---|---|
-| 任意 | 同种类、同引用 | 不变:第二条声明成为指向已解析身份的一条边,不报告任何信息。 |
-| `version` | `version`,不同的约束 | 按上文所述用 SemVer 对两个约束做 AND 合并;无法满足的一对被拒绝,并点名两个约束与两个请求方。 |
-| `git` | `git`,不同的 `rev`/`tag`/`branch` | 若根是两个请求方之一,根的声明胜出;否则先解析出来的声明胜出。`dependency/source-override` 警告点名两个请求方与两个引用,说明哪一个被采用、原因是什么,以及如何取用另一个。这个警告绝不会被吞掉。 |
-| `path` | `path`,不同的目录 | 规则与警告同上一行,只是比较的是规范化后的绝对目录而不是 git 引用。 |
-| 根的 `path` 或 `git` 声明 | 某个依赖的 `git` 或 `version` 声明(种类冲突) | 根的声明胜出,警告同上。若败下阵的声明是一条 `version` 需求,它会被拿去与根已解析出的那份 checkout 的 `[package] version` 核对;需求被违反就拒绝,并点名那个 pin、请求方与需求本身。 |
-| 某个依赖的 `path`/`git` 声明 | 另一个依赖的不同种类的声明(种类冲突,且双方都不是根) | 拒绝:"requested as both a … dep … and a … dep …. Pick one."。消息多出一句:在根里声明该身份即可解决。 |
-
-这里根所拥有的特权,与 `linkage` 只在根 manifest 自己的边上生效(见上文
-`[dependencies]`)是同一条边界:一个身份最终解析到*哪一份 checkout*,是一个
-只有构件自己的 manifest 才能替某个依赖悄悄做出的整图级决定。两个依赖互相冲
-突、且都不是根的情形,绝不会靠猜哪个先被声明来解决 —— 那正是本节要替换掉的
-"队列顺序的意外"。
-
-### `path` 与 `git` 依赖的身份(mcpp 2026.9.14.2+)
-
-`path` 或 `git` 依赖就是它的清单所声明的那个包,与指向它的键无关。一个键规范化后的
-身份若不同于清单 `[package]` 的 `namespace` 与 `name`,就采用清单声明的身份;mcpp
-对每条声明边告警一次,点名请求方、键、键所指的身份与清单声明的身份:
+| 任意 | 同种类、同引用 | 不变：第二条声明成为指向已解析身份的一条边，不报告任何信息。 |
+| `version` | `version`，不同的约束 | 按上文所述，用 SemVer 对两个约束做 AND 合并；无法满足的一对被拒绝，并点名两个约束与两个请求方。 |
+| `git` | `git`，不同的 `rev`/`tag`/`branch` | 根是两个请求方之一时，根的声明胜出；否则先解析出来的声明胜出。`dependency/source-override` 警告点名两个请求方与两个引用，说明哪一个被采用、原因是什么，以及如何取用另一个。这个警告绝不会被吞掉。 |
+| `path` | `path`，不同的目录 | 规则与警告同上一行，只是比较的是规范化后的绝对目录，而不是 git 引用。 |
+| 根的 `path` 或 `git` 声明 | 某个依赖的 `git` 或 `version` 声明（种类冲突） | 根的声明胜出，警告同上。若败下阵的声明是一条 `version` 需求，它会被拿去与根已解析出的那份 checkout 的 `[package] version` 核对；需求被违反就拒绝，并点名那个 pin、请求方与需求本身。 |
+| 某个依赖的 `path`/`git` 声明 | 另一个依赖的不同种类的声明（种类冲突，且双方都不是根） | 拒绝："requested as both a … dep … and a … dep …. Pick one."。消息多出一句：在根里声明该身份即可解决。 |
+
+这里根所拥有的特权，与 `linkage` 只在根 manifest 自己的边上生效（见上文
+`[dependencies]`）是同一条边界：一个身份最终解析到*哪一份 checkout*，是一个
+只有构件自己的 manifest 才能替某个依赖悄悄做出的整图级决定。两个依赖互相
+冲突、且都不是根的情形，绝不会靠猜哪个先被声明来解决 —— 那正是本节要替换掉
+的"队列顺序的意外"。
+
+### `path` 或 `git` 依赖的身份（mcpp 2026.9.14.2+）
+
+`path` 或 `git` 依赖就是它的 manifest 所声明的那个包，与指向它的键无关。一个
+键规范化后的身份，若不同于 manifest `[package]` 的 `namespace` 与 `name`,
+就采用 manifest 声明的身份；mcpp 对每条声明边告警一次，点名请求方、键、键所指
+的身份，以及 manifest 声明的身份：
 
 ```toml
 # comp/mcpp.toml; fw/mcpp.toml declares namespace = "huxdemo"
@@ -173,67 +178,73 @@ warning: 'huxdemo.comp@path' declares the dependency 'fw', which names mcpplibs.
   hint: write 'huxdemo.fw' in 'huxdemo.comp@path' to state the identity the manifest declares.
 ```
 
-因此同一目录上分别写作 `fw` 与 `huxdemo.fw` 的两条边是同一个包,只编译一次,
-`mcpp why deps` 在它下面列出两个键。未声明命名空间的清单取键的命名空间,于是在这样
-一个目录上用两个不同命名空间的键,就是同一来源上的两个身份:构建在扫描之前被拒绝,
-点名二者;修正方式是在该清单中声明 `namespace`,或两处写同一个键。`version` 依赖
-不受影响,它的身份就是键。
+因此，同一目录上分别写作 `fw` 与 `huxdemo.fw` 的两条边是同一个包，只编译
+一次，`mcpp why deps` 在它下面列出两个键。未声明命名空间的 manifest 取键的
+命名空间，于是在这样一个目录上使用两个不同命名空间的键，就是同一来源上的两个
+身份：构建在扫描之前被拒绝，点名二者；修正方式是在该 manifest 中声明
+`namespace`，或两处写同一个键。`version` 依赖不受影响，它的身份就是键。
 
-### git 仓库中的一个包(mcpp 2026.9.16.1+)
+### git 仓库中的一个包（mcpp 2026.9.16.1+）
 
-`git` 依赖指向一个仓库,键说明指的是仓库里的哪一个包。根清单的包是其一;根清单
-`[workspace] members` 的每一项是另一个。键的身份不是根包时,选中清单声明该身份的那个
-member,提交相同:
+`git` 依赖指向一个仓库，键说明指的是仓库里的哪一个包。根 manifest 的包是
+其一；根 manifest `[workspace] members` 的每一项是另一个。当键的身份不是
+根包时，选中 manifest 声明该身份的那个 member，取同一个提交：
 
 ```toml
-# repo/mcpp.toml 声明 spike.fw 与 [workspace] members = ["tool"];
-# repo/tool/mcpp.toml 声明 spike.fw-installer
+# repo/mcpp.toml declares spike.fw and [workspace] members = ["tool"];
+# repo/tool/mcpp.toml declares spike.fw-installer
 [dependencies]
 spike.fw           = { git = "https://example.org/fw.git", rev = "cc3c74c5" }
 spike.fw-installer = { git = "https://example.org/fw.git", rev = "cc3c74c5", tools = ["fw-installer"] }
 ```
 
-- member 继承仓库的 `[workspace.package]`,与从仓库自己的检出构建时相同。
-- member 中留在克隆目录之内的 `path` 边(例如 `spike.fw = { path = ".." }`)指向同一
-  git 源的同一提交,因此它就是根的键解析到的那个包,而不是第二条以 path 为源的声明。
-- 既不指根包也不指任何 member 的键沿用上一节的规则:使用根清单的身份,并给出警告。
+- member 继承仓库的 `[workspace.package]`，与从仓库自己的检出构建时相同。
+- member 中留在克隆目录之内的 `path` 边（例如 `spike.fw = { path = ".." }`）
+  指向同一 git 源的同一提交，因此它就是根的键解析到的那个包，而不是第二条
+  以 path 为源的声明。
+- 既不指根包、也不指任何 member 的键，沿用上一节的规则：使用根 manifest 的
+  身份，并给出警告。
 
-键按身份选择,不存在 `subdir` 键:较旧的客户端会忽略这样的键,并不声不响地构建根包。
+键按身份选择，不存在 `subdir` 键：较旧的客户端会忽略这样的键，并不声不响地
+构建根包。
 
 ### 命名空间解析规则
 
-每个包的身份是**命名空间 + 名字**二元组。每个 selector 都只规范化成一个身份:
+每个包的身份是**命名空间 + 名字**二元组。每个选择器都只规范化成一个身份：
 
-- `cmdline` → `(mcpplibs, cmdline)`;省略 namespace 只表示默认 `mcpplibs`。
+- `cmdline` → `(mcpplibs, cmdline)`；省略 namespace 只表示默认 `mcpplibs`,
+  不表示别的。
 - `compat.gtest` → `(compat, gtest)`。
 - `mcpplibs.capi.lua` → `(mcpplibs.capi, lua)`。
 
-不存在有序回退或按短名的全索引模糊搜索:
+不存在有序回退，也不存在按短名的全索引模糊搜索：
 
 ```toml
-# 正确 —— 点式选择器
+# Correct — dotted selector
 [dependencies]
 chriskohlhoff.asio = "1.38.1"
 
-# 正确 —— 命名空间子表(同一组织有多个包时更推荐)
+# Correct — namespace sub-table (preferred for several packages from one org)
 [dependencies.chriskohlhoff]
 asio = "1.38.1"
 
-# 错误 —— 裸名永远到不了 chriskohlhoff 命名空间
+# Wrong — a bare name never reaches the `chriskohlhoff` namespace
 [dependencies]
 asio = "1.38.1"
 ```
 
-第三种写法会明确报错,指出实际尝试的 `(mcpplibs, asio)`;若该短名存在于别处,错误信息会给出可直接复制的显式 selector。
+第三种写法会明确报错，指出实际尝试过的 `(mcpplibs, asio)` 身份；该短名若存在
+于别处，错误信息会给出一个可直接复制的显式选择器。
 
-#### 裸名过渡期(`2026.8.10.1` 起,`2026.9` 移除)
+#### 裸名过渡期（`2026.8.10.1` 起，`2026.9` 移除）
 
-索引里已发布的 `compat.*` 包与既有 manifest **全部**写成裸名(`gtest = "1.15.2"`)。
-升级后直接失败,等于让一次程序发布把**已经发布、且无法追溯修改**的数据作废,
-所以有一个版本的过渡期:裸名在 `mcpplibs` 未命中时仍可到达 `compat.<name>`,
-不声明 namespace 的 descriptor 也仍可被裸名解析。
+索引里每一个已发布的 `compat.*` 包，以及精确身份出现之前写下的每一份
+manifest，都把它的依赖写成裸名 —— `gtest = "1.15.2"`。升级时让它们直接失败，
+等于让一次程序发布，把已经发布、且无法追溯修改的数据作废，所以有一个版本的
+过渡期：一个在 `mcpplibs` 未命中的裸名，仍可到达 `compat.<name>`，一个完全不
+声明 namespace 的描述符，也仍可响应它的裸名。
 
-但它不再静默:
+但它不再是静默的：
 
 ```
 warning: dependency 'gtest' resolved to 'compat.gtest' through the deprecated
@@ -244,70 +255,82 @@ package:
   (or run `mcpp add compat.gtest@1.15.2`). This fallback is removed in 2026.9.
 ```
 
-写进 `mcpp.lock`、install 与 cache 的是**规范身份**;歧义拼写只存在于工程的
-`mcpp.toml` 中,直到被改写 —— `mcpp add gtest@1.15.2` 会完成这次改写。
+写进 `mcpp.lock`、install 层与 cache 的是**规范身份**，因此歧义的拼法只存在
+于一个地方 —— manifest 本身 —— 直到它被改写为止。`mcpp add gtest@1.15.2`
+执行的正是这次改写。
 
-过渡期**不适用于**写明 namespace 的 selector(`mcpplibs.gtest` 未命中就是未命中),
-裸名也**仍然**到不了第三方 namespace。
+这个过渡期**不适用于**写明了 namespace 的选择器（`mcpplibs.gtest` 未命中就
+保持未命中），裸名也**仍然**永远到不了第三方 namespace。
 
-**为什么只允许一个身份?** 因为依赖解析必须可复现。候选搜索会让同短名包受索引状态影响,新增索引还可能悄悄重定向既有依赖。
+**为什么只允许一个身份?** 依赖解析必须可复现。候选搜索会让两个短名相同的
+namespace，由索引当时的状态来裁决，而新增一个索引就可能悄悄改变一个既有依赖
+指向的目标。
 
-**给 xpkg 作者:** 索引描述符里,身份是 `(package.namespace, package.name)` 二元组。命名空间是点分路径,**`name` 是单一原子段**:
+**给 xpkg 作者：** 在一个索引描述符里，身份是 `(package.namespace,
+package.name)` 这一对。namespace 是点分路径,**`name` 是单一的原子段**:
 
 ```lua
 package = {
     namespace = "chriskohlhoff",
-    name      = "asio",                 -- 单一段;不是 "chriskohlhoff.asio"
+    name      = "asio",                 -- one segment; NOT "chriskohlhoff.asio"
 }
 
 package = {
-    namespace = "mcpplibs.capi",        -- 层级放这里
+    namespace = "mcpplibs.capi",        -- depth belongs here
     name      = "lua",
 }
 ```
 
-文件名只是提示 —— 描述符按声明的身份被发现,所以 `pkgs/c/chriskohlhoff.asio.lua` 与 `pkgs/z/anything.lua` 解析结果完全相同。推荐 `<name>.lua` 或 `<namespace>.<name>.lua`(命中 mcpp 的快路径),但不强制。
-
-旧的完全限定拼写(`name = "chriskohlhoff.asio"`)仍被接受,已发布的描述符无需改动。`mcpp xpkg parse` 会校验该规则,请在索引 CI 里跑它。描述符身份需要 mcpp >= 0.0.106,精确 selector 需要 mcpp >= 2026.8.10.1,两者使用 xlings >= 0.4.69;规范全文见 `docs/specs/package-identity.md`。
-
-`mcpp new --template` 刻意复用同一身份模型，而不是另造包文法:
-`[ns.]name[@version][:tname]`。其中裸名同样只表示 `mcpplibs`，version 与模板名可分别
-省略。省略 `tname` 时选择唯一显式 default；若未写 `default = true` 且只有一个模板，
-该单模板自动成为默认。多个未标默认的模板会报错，绝不按目录顺序选择。规范表见
+文件名只是一个提示 —— 描述符按它声明的身份被发现，所以
+`pkgs/c/chriskohlhoff.asio.lua` 与 `pkgs/z/anything.lua` 解析结果完全相同。
+`<name>.lua` 或 `<namespace>.<name>.lua` 是推荐写法（它们命中 mcpp 的快
+路径），但不是强制要求。
+
+较旧的完全限定拼法（`name = "chriskohlhoff.asio"`）仍被接受，因此已发布的
+描述符不需要改动。`mcpp xpkg parse` 会校验这条规则，索引 CI 里应当运行它。
+描述符身份要求 mcpp >= 0.0.106，精确选择器要求 mcpp >= 2026.8.10.1，两者都
+使用 xlings >= 0.4.69。规范全文在 `docs/specs/package-identity.md`。
+
+`mcpp new --template` 刻意复用同一套身份模型，而不是另造一套包文法：
+`[ns.]name[@version][:tname]`。这里的裸名同样只表示 `mcpplibs`;version 与
+模板名可以分别省略。省略 `tname` 会选中唯一的显式 default；若没有一个
+`default = true` 而只有一个模板，该模板自动成为默认。多个未标默认的模板
+是一个错误，绝不会按目录顺序选择。规范化的模板行见
 `docs/specs/package-identity.md` §4.4。
+
 ### mcpp 何时刷新包索引
 
-`mcpp build` / `run` / `test` **只在依赖无法用本地索引解析时**刷新包索引,绝不会
-因为"时间到了"就刷。具体地说,只有三种情况会触发:本地根本没有索引、依赖的描述符
-不在其中、或 SemVer 约束在本地已知版本里无解。只要所有依赖都能在本地解析出来,
-无论本地索引多旧,构建都不会发起任何网络请求。
+`mcpp build` / `run` / `test` **只在依赖无法用本地副本解析时**刷新包索引，
+绝不会仅仅因为时间流逝就刷新。具体地说：本地根本没有索引、依赖的描述符不在
+其中，或一条 SemVer 约束在本地已知版本里无解，这三种情况会触发刷新。只要
+所有依赖都能在本地解析出来，不论本地索引多旧，构建都不会发出任何网络请求。
 
-由此带来的一个需要知道的语义:`^1.2` 这类约束是对**本地索引已知的版本**求解的。
-若上游在上次刷新之后发布了 `1.3.0`,需要主动获取:
+由此带来一个值得知道的推论：`^1.2` 这类约束，是对**本地索引已知的那些版本**
+求解的。上游在上一次刷新之后发布的 `1.3.0`，在被主动取回之前不可见：
 
 ```bash
-mcpp index update     # 同步索引
-mcpp update           # 同步索引,并重新解析依赖
-mcpp index status     # 看本地现状:状态、年龄、修订号
+mcpp index update     # sync the index
+mcpp update           # sync, then re-resolve dependencies
+mcpp index status     # local state: state, age and revision
 ```
 
-三个开关,优先级从高到低:
+三个开关，按优先级从高到低：
 
-| 开关 | 作用 |
+| 开关 | 效果 |
 |---|---|
-| `--offline`(任意命令) | 完全不碰网络——不刷索引、不下载、不自动装工具链,也不发 `git ls-remote`/`clone`。已安装的东西照常构建,包括 commit 已在 `mcpp.lock`、克隆已在缓存里的 git 依赖 |
-| `MCPP_OFFLINE=1` | 同上,作用于整个 shell 会话或 CI job |
-| `~/.mcpp/config.toml` 里 `[index] auto_refresh = false` | 永不隐式刷新索引:依赖未命中时不刷新,安装本地索引缺少的包之前不刷新,工程自定义索引的首次同步也不做(该次构建停止并指出 `mcpp index update`)。下载仍然可用 |
+| `--offline`（任意命令） | 完全不碰网络 —— 不刷索引、不下载、不自动安装工具链，也不发出 `git ls-remote`/`clone`。已安装的东西照常构建，包括 commit 已在 `mcpp.lock`、克隆已在缓存里的 git 依赖 |
+| `MCPP_OFFLINE=1` | 同上，作用于整个 shell 会话或一次 CI job |
+| `~/.mcpp/config.toml` 中的 `[index] auto_refresh = false` | 永不隐式刷新索引：依赖未命中时不刷新，安装本地索引没有的包之前不刷新，工程自定义索引的首次同步也不做（该次构建停止，并指出 `mcpp index update`）。下载仍然可用 |
 
-`MCPP_NO_AUTO_INSTALL=1` 作为 `--offline` 的旧式窄化拼写仍然有效(它只管工具链的
-自动安装)。
+`MCPP_NO_AUTO_INSTALL=1` 作为 `--offline` 更早、更窄的拼法，仍然被接受
+（它只约束工具链的自动安装）。
 
-刷新有期限。`[index] refresh_timeout`(秒,默认 120)是一次刷新最长可用的时间;超过
-即被终止,一条警告指出该设置,构建与任何一次刷新失败之后一样,继续使用本地索引。经由
-xlings 的安装在 xlings 连续 300 秒没有任何输出(包括心跳)时被终止。结束 mcpp 会一并
-结束它启动的 xlings 进程。
+一次刷新有时限。`[index] refresh_timeout`（单位秒，默认 120）是一次刷新
+可用的最长时间；超过它就被终止，一条警告指出这个设置，构建像在任何一次刷新
+失败之后一样，继续使用本地索引。经由 xlings 的安装，在 xlings 连续 300 秒
+没有任何输出（包括心跳）时被终止。终止 mcpp 会一并终止它启动的 xlings 进程。
 
-任意命令加 `-v` 可以看到每个依赖的判定结果与原因。
+对任意命令加 `-v`，可以看到每个依赖的判定结果与原因。
 
 ## `[dev-dependencies]` —— 测试依赖
 
@@ -316,61 +339,67 @@ xlings 的安装在 xlings 连续 300 秒没有任何输出(包括心跳)时被
 gtest = "1.15.2"
 ```
 
-`mcpp build` 忽略这些依赖;`mcpp test` 解析并使用它们。`mcpp test` 自动发现
-`tests/**/*.cpp` 并把它们编译为测试二进制。运行器与框架无关:每个文件是一个独立的
-二进制,以退出码判定 —— 裸 `main`、gtest(经 `[dev-dependencies]` + `gtest_main`)
-或任何其他框架的行为完全一致,`-- args` 会转发给每个测试二进制
-(例如 `-- --gtest_filter=...`)。注意:合成的测试目标名可能包含 `/`
-(`tests/00-a/0.cpp` → `00-a/0`),这与 `[targets.*]` 名不同 —— 两个命名空间是
-刻意分开的(测试目标从不进入 manifest,也不参与发布)。测试按其相对 `tests/` 的
-路径命名(`tests/00-a/0.cpp` → `00-a/0`),每个测试独立编译(一个测试写坏只让它
-自己失败;包或依赖损坏则报告为构建错误),`mcpp test <pattern>` 与
-`--message-format json` 分别提供过滤与机器可读输出。
+`mcpp build` 忽略这些依赖；`mcpp test` 解析并使用它们。`mcpp test` 自动
+发现 `tests/**/*.cpp` 并把它们编译为测试二进制。运行器与框架无关：每个文件
+是一个独立的二进制，由退出码判定 —— 裸 `main`、gtest（经 `[dev-dependencies]`
+加 `gtest_main`）或任何其他框架，行为完全一致，`-- args` 会转发给每一个测试
+二进制（例如 `-- --gtest_filter=...`）。注意：合成出来的测试目标名可能包含
+`/`(`tests/00-a/0.cpp` → `00-a/0`)，这与 `[targets.*]` 的名字不同 ——
+两个命名空间是刻意分开的（测试目标从不进入 manifest，也不参与发布）。测试
+以它相对 `tests/` 的路径命名（`tests/00-a/0.cpp` → `00-a/0`），每个测试
+独立编译（一个测试写坏，只让它自己失败；包或依赖本身损坏则报告为构建
+错误），`mcpp test <pattern>` 与 `--message-format json` 分别提供过滤与
+机器可读输出。
 
-## `[build-dependencies]` —— 构建期依赖(mcpp 2026.8.29.1+)
+## `[build-dependencies]` —— 构建期依赖（mcpp 2026.8.29.1+）
 
 ```toml
 [build-dependencies]
 protobuf = { version = "35.1", tools = ["protoc"] }
 ```
 
-段与边上的请求回答的是**两个不同的问题**,把它们混为一谈是建模上的错误,不是写法之争。
+段与边上的请求回答的是**两个不同的问题**，把它们混为一谈是建模上的错误，
+不是写法之争。
 
-- **段**回答:这个包本身进不进目标。`[dependencies]` 进;`[build-dependencies]` 永不进,
-  只能经由它到达的东西也一样。
-- **边上的请求**回答:要它的哪一种构建期产物。`tools = [...]` 要一个宿主可执行文件,
-  `host-module = true` 要一个构建程序可以 import 的模块。
+- **段**回答：这个包本身进不进目标。`[dependencies]` 表示进；
+  `[build-dependencies]` 表示永不进，只能经由它到达的东西同样不进。
+- **边上的请求**回答：想要它的哪一种构建期产物。`tools = [...]` 要一个宿主
+  可执行文件，`host-module = true` 要一个构建程序可以 import 的模块。
 
-一个包可以同时在两个轴上取值,而 protobuf 正是证明这两个轴必须分开的例子:工程既链接
-`libprotobuf`,构建期又需要 `protoc`。它只写一次,写在 `[dependencies]` 里:
+一个包可以同时在这两个轴上取值，而 protobuf 正是证明这两个轴必须分开的
+例子：一个工程既链接 `libprotobuf`，构建期又需要 `protoc`。它只写一次，
+写在 `[dependencies]` 里：
 
 ```toml
 [dependencies]
 protobuf = { version = "35.1", tools = ["protoc"] }
 ```
 
-`[build-dependencies]` 用于第一个轴无法表达的那种组合 —— 某个包的库不得进入目标,
-而它的工具或规则仍然需要。同一个包同时出现在两张表里不是错误:普通声明胜出,因为
-一行 `[build-dependencies]` 不应该悄悄拿掉目标真正需要的库;两条声明各自的请求
-(`tools`、`features`、`host-module`、`reexport`)都作用于这一条边(mcpp 2026.9.16.1+;
-此前第二条声明的请求被丢弃)。
+`[build-dependencies]` 用于第一个轴无法表达的那种组合 —— 某个包的库不得
+进入目标，而它的工具或规则仍然需要。同一个包同时出现在两张表里不是错误：
+普通声明胜出，因为一行 `[build-dependencies]` 不应该悄悄拿掉目标真正需要
+的库；两条声明各自请求的内容（`tools`、`features`、`host-module`、
+`reexport`）都作用在同一条边上（mcpp 2026.9.16.1+；该版本之前，第二条声明
+的请求会被丢弃）。
 
-**只含程序的包只贡献它的程序(mcpp 2026.9.16.1+)。** 声明的 `[targets]` 全部是程序
-(`bin`、`app`、`test`)的依赖没有可链接的东西。它的工具由工具子构建构建,子构建把这个包
-当作自己的根来解析;在消费方的图里它只提供工具与目录:它自己的依赖不在那里解析,它的源码
-不在那里编译,它的 `ldflags` 不进入消费方的链接。因此一个程序可以依赖请求它的那个包,
-SDK 正是这样提供一个针对自身构建的程序。没有 `[targets]` 表的包不受影响,即使
-`src/main.cpp` 为它推断出一个程序。
+**只含程序的包，只贡献它的程序（mcpp 2026.9.16.1+）。** 一个声明的
+`[targets]` 全部是程序（`bin`、`app`、`test`）的依赖，没有可链接的东西。
+它的工具由工具子构建构建出来，子构建把这个包当作自己的根来解析；在消费方的
+图里，它只提供它的工具与它的目录，别无其他：它自己的依赖不在那里解析，它的
+源码不在那里编译，它的 `ldflags` 不进入消费方的链接。因此，一个程序可以
+依赖请求它的那个包，SDK 正是这样提供一个针对自身构建出来的程序。没有
+`[targets]` 表的包不受影响，即使某个 `src/main.cpp` 为它推断出一个程序。
 
-包之间的环在解析依赖图的地方被拒绝,并列出环上的边,与缓存模式无关;工具子构建再次请求
-正在构建的同一个工具时,在第一次重复处被拒绝,并给出请求链。
+包之间的环，在解析依赖图的地方就被拒绝，并列出环上的边，与缓存模式无关；
+一个工具子构建再次请求正在构建的同一个工具时，在第一次重复处被拒绝，并给出
+请求链。
 
-与 `[dev-dependencies]` 不同,这些依赖**会**被传递遍历:一个构建期依赖自己的依赖正是
-让它能工作的东西,并且继承它「只服务构建」的性质。
+与 `[dev-dependencies]` 不同，这些依赖**会**被传递遍历：一个构建期依赖自己
+的依赖，正是让它能工作的东西，并且继承它"只服务构建"的性质。
 
-feature 可以为构建期请求划定范围而无需第二个声明处。`[feature-deps.<name>]` 的条目可以
-以相同的源重述一条已经无条件声明的依赖,并为它追加 `tools`,所以「按需才要」不需要另开
-一张表:
+一个 feature 可以为构建期请求划定范围，而无需另开一个声明处。
+`[feature-deps.<name>]` 的条目可以用相同的源，重述一条已经无条件声明的
+依赖，并为它追加 `tools`，所以"只在需要时才要"不需要另开一张表：
 
 ```toml
 [dependencies]
@@ -380,20 +409,21 @@ spike.installer = { path = "../installer" }
 spike.installer = { path = "../installer", tools = ["installer"] }
 ```
 
-重述要写出源,因为每张依赖表都如此:没有 `path`、`git`、`version` 或 `workspace` 的条目
-被当作命名空间表读取并被拒绝,拒绝消息会说明要重述源。重述中的 `tools`、`features`、
-`host-module` 与 `reexport` 加到该行生效的声明上。重述写了另一个源时被拒绝,并列出两个源
-(mcpp 2026.9.16.1+);此前它被忽略。
+这次重述要写出它的源，因为每一张依赖表都是如此：一个没有 `path`、`git`、
+`version` 或 `workspace` 的条目会被当作命名空间表读取并被拒绝，拒绝消息会
+说明要重述源。重述中的 `tools`、`features`、`host-module` 与 `reexport`
+会加到这一行当前生效的声明上。重述若写了另一个源，会被拒绝，并列出两个源
+(mcpp 2026.9.16.1+)；该版本之前它会被忽略。
 
-> 这个段很早就能被解析,而直到 2026.8.29.1 之前没有任何做决定的代码读它:写下它得到的是
-> 一份能加载的清单、零诊断、零效果。
+> 这个段很早就能被解析，而直到 2026.8.29.1，没有任何做决定的代码读过它：
+> 写下它得到的是一份能加载的 manifest、零诊断、零效果。
 
 ## 当前边界
 
-- **只有两件事需要网络,也只有这两件:**解析一个在锁里没有 commit 的分支,以及克隆
-  一个尚未缓存的 commit。指向本地目录或 `file://` URL 的 `git =` 两者都不需要,因此
-  离线时从不会被拒绝。
-- 索引刷新窗口**不适用于写明了 namespace 的选择器**。`mcpplibs.gtest` 一旦未命中就
-  保持未命中,直到下一次刷新。
-- `mcpp.lock` 记录并核验一次解析,但不约束解析。见
+- **只有两件事需要网络，而且只有这两件：** 解析一个在 lock 里没有 commit 的
+  分支，以及克隆一个尚未缓存的 commit。指向本地目录或 `file://` URL 的
+  `git =`，两者都不需要，因此离线时从不会被拒绝。
+- 索引刷新窗口**不适用于写明了 namespace 的选择器**。`mcpplibs.gtest` 一旦
+  未命中，就保持未命中，直到下一次刷新。
+- `mcpp.lock` 记录并核验一次解析，但不约束一次解析。见
   [51 —— 受支持的版本与兼容性](51-supported-versions.md)。
diff --git a/docs/zh/06-features-and-capabilities.md b/docs/zh/06-features-and-capabilities.md
index 7e50e4b94..53aca4014 100644
--- a/docs/zh/06-features-and-capabilities.md
+++ b/docs/zh/06-features-and-capabilities.md
@@ -1,110 +1,119 @@
 # 06 —— Feature 与能力
 
-**读者:**手上有可选内容的作者 —— 一份额外的源、一个额外的依赖,或者在多个后端
+**读者：** 手上有可选内容的作者 —— 一份额外的源、一个额外的依赖，或者在多个后端
 之间做选择。
 
-**本章回答的那一个问题:**一个包怎样提供可选内容,消费者又怎样要它。
+**本章回答的那一个问题：** 一个包怎样提供可选内容，消费方又怎样请求它。
 
-**不在这里:**一次构建面向哪些设备后端 —— 那看起来像 feature 而不是 feature,
-它是 [42 —— 异构硬件构建](42-heterogeneous-builds.md)。在此之前:
-[05 —— 依赖与解析](05-dependencies.md)。在此之后:[07 —— 工作空间](07-workspace.md)。
+**不在这里：** 一次构建面向哪些设备后端 —— 那看起来像 feature，却不是 —— 它是
+[42 —— 异构硬件构建](42-heterogeneous-builds.md)。在此之前：
+[05 —— 依赖与解析](05-dependencies.md)。在此之后：[07 —— 工作空间](07-workspace.md)。
 
-Feature 是一个包提供可选内容的方式:一个编译宏、一份额外的源文件、一个额外的
-依赖,或者在多个后端之间做选择。本章是声明与消费 feature 的参考。
+Feature 是一个包提供可选内容的方式：一个编译宏、一份额外的源文件、一个额外的
+依赖，或者在多个后端之间的一次选择。本章是声明与消费 feature 的参考。
 
-相关文档:[04 —— mcpp.toml](04-mcpp-toml.md) 是 manifest 其余部分的字段参考;
+相关文档：[04 —— mcpp.toml](04-mcpp-toml.md) 是 manifest 其余部分的字段参考；
 [`examples/11-features`](../../examples/11-features/) 是一个把三种形态都声明了
-一遍、并且用 dev-dependency 写测试的包;[42 —— 异构硬件构建](42-heterogeneous-builds.md)
-是这套机制最大的消费者,因为每条加速器 lane 都是一个 feature。
+一遍、并且用 dev-dependency 写了测试的包；[42 —— 异构硬件构建](42-heterogeneous-builds.md)
+是这套机制最大的消费方，因为每一条加速器 lane 都是一个 feature。
 
-## `[features]` —— Feature(Cargo 风格,可加性)
+## `[features]` —— Feature（Cargo 风格，可加性）
 
 ```toml
 [features]
-default = ["base"]        # 默认激活集合
+default = ["base"]        # Default activation set
 base    = []
-docking = ["extra"]       # 激活 docking 即隐含激活 extra(传递闭包)
+docking = ["extra"]       # Activating docking implies activating extra (transitive closure)
 extra   = []
 ```
 
-- 激活来源:包自己的 `default` 集合 ∪ 显式请求(根包经由
-  `mcpp build --features a,b`;依赖经由长形式依赖 spec 的 `features = [...]`
-  与 `backend = "..."` 糖)。
-- 每个被激活的 feature 在该包编译时得到宏 `-DMCPP_FEATURE_<NAME>`(名字大写,
-  非字母数字变 `_`,例如 `backend-a` → `MCPP_FEATURE_BACKEND_A`)。
-- **严格校验**:目标包声明了 `[features]` 表时,请求一个未声明的 feature 产生
-  警告,在 `--strict` 下是错误。不声明 `[features]` 的包接受任意请求(纯宏用法)。
+- 激活来源：包自己的 `default` 集合，并上显式请求（根包经由
+  `mcpp build --features a,b`；依赖经由长形式依赖 spec 的 `features = [...]`
+  与 `backend = "..."` 糖衣）。
+- 每个被激活的 feature，在该包编译时得到宏 `-DMCPP_FEATURE_<NAME>`（名字转大写，
+  非字母数字字符变 `_`，例如 `backend-a` → `MCPP_FEATURE_BACKEND_A`）。
+- **严格校验**：目标包声明了 `[features]` 表时，请求一个未声明的 feature 会产生
+  warning，在 `--strict` 下是错误。不声明 `[features]` 的包接受任意请求（纯宏用法）。
 
 ### 依赖的 feature
 
-`<依赖>/<feature>` 形式的记号打开某个依赖的 feature。依赖以消费方清单所写的键命名
-(`spike.fw`、`compat.opencv`),记号是可加的:它只打开依赖更多的部分,从不把依赖拉进来。
+`<依赖>/<feature>` 形式的记号，打开某个依赖的一个 feature。依赖以消费方 manifest
+所写的键命名（`spike.fw`、`compat.opencv`），记号是可加的：它只打开依赖更多的
+部分，从不把依赖本身拉进来。
 
 ```toml
 [dependencies]
 spike.fw = { path = "../fw" }
 
 [features]
-windows-installer = ["spike.fw/installer"]   # 与表形式中的 `forward = [...]` 相同
+windows-installer = ["spike.fw/installer"]   # the same as `forward = [...]` in the table form
 ```
 
-- **命令行上**(mcpp 2026.9.16.1+),`mcpp build --features spike.fw/installer` 为一条命令
-  打开同一个 feature,与根的转发相同;`run`、`test`、`pack`、`emit build-database` 与
-  `why deps` 同样接受该记号。它从不是根的 feature,也从不变成宏。
-- **校验**读取写下该转发的清单的每一张依赖表:`[dependencies]`、`[build-dependencies]`、
-  `[dev-dependencies]` 与 `[feature-deps.<name>]`,覆盖所有行。只在别的行或未激活的 feature
-  下声明的键同样算已声明;在当前行上该转发不到达任何边,不产生效果。没有任何表声明的键会被
-  报告,在 `--strict` 下报告为错误。命令行上无论根是否声明 `[features]`,都做同样的检查。
+- **命令行上**(mcpp 2026.9.16.1+),`mcpp build --features spike.fw/installer` 为
+  一条命令打开同一个 feature，效果与根的转发相同；`run`、`test`、`pack`、
+  `emit build-database` 与 `why deps` 同样接受这个记号。它从不是根自己的 feature,
+  也从不变成宏。
+- **校验**会读遍写下该转发的那份 manifest 里的每一张依赖表：`[dependencies]`、
+  `[build-dependencies]`、`[dev-dependencies]` 与 `[feature-deps.<name>]`，覆盖
+  所有行。一个键只在别的行、或未激活的 feature 下声明，仍算已声明；在当前这一行
+  上，该转发到达不了任何边，不产生效果。没有任何表声明的键会被报告，`--strict`
+  下报告为错误。命令行上的这条检查不论根是否声明 `[features]` 都一样执行。
 
 ### 表形式 —— 让 feature 贡献的不止是隐含 feature
 
-`[features]` 的条目除了写成数组,还可写成**表**,从而让该 feature 在隐含 feature
-之外,携带包自有的预处理 `defines`、feature 门控的源 glob(`sources`,mcpp
-0.0.95+——列出的 glob 离开默认构建,仅当 feature 激活时才编译,与 index 描述符的
-`features.<f>.sources` 完全对等;这正是 vendored 大库最高频的形态:*feature =
-一组源文件 + 一个 define*)、feature 门控的 per-glob 编译旗标(`flags`,mcpp
-0.0.101+),以及 capability 的 `requires` / `provides`(见下文*`provides` / `requires`*):
+`[features]` 的条目除了写成数组，还可以写成**表**，从而让该 feature 除了隐含
+feature 之外，再携带包自有的预处理 `defines`、feature 门控的源 glob(`sources`,
+mcpp 0.0.95+ —— 列出的 glob 离开默认构建，仅在 feature 激活时才编译，与 index
+描述符的 `features.<f>.sources` 完全对等；这正是 vendored 大库最高频的形态：
+*feature = 一组源文件 + 一个 define*)、feature 门控的 per-glob 编译旗标
+(`flags`,mcpp 0.0.101+)，以及 capability 的 `requires` / `provides`（见下文
+*`provides` / `requires`*）：
 
 ```toml
 [features]
 default    = []
-# 数组简写:仅隐含 feature。
+# Array shorthand: just implied features.
 docking    = ["extra"]
 extra      = []
-# 表形式:激活时贡献一个包自有的宏。
+# Table form: contribute a package-owned define when active.
 mpl2only   = { defines = ["EIGEN_MPL2_ONLY"] }
-# 表形式:宏 + 一个隐含 feature。
+# Table form: a define + an implied feature.
 fast_math  = { defines = ["APP_FAST=1"], implies = ["extra"] }
-# 表形式:feature 门控源 + 与其同居的 per-glob 旗标。
+# Table form: feature-gated sources + per-glob flags that co-locate with them.
 simd       = { sources = ["src/simd/**"], flags = [
                  { glob = "src/simd/**/*.avx2.cpp", cxxflags = ["-mavx2"] } ] }
 ```
 
 - **表形式恰好接受** `implies`、`forward`、`defines`、`sources`、`flags`、
-  `requires`、`provides`。其余键会被报成一条 schema 警告并忽略(mcpp 2026.9.1.1+);
-  `deps` 单独报为「保留」(它是计划中的而不是写错的),并指向 `[feature-deps.<name>]`。在该版本之前,`[features]`
-  是唯一一个完全没有 schema 检查的结构化段落 —— 把 `include_dirs` 误写进 feature 里
-  会零诊断地构建成功,而同样的错误写在 `[build]` 里会被报出来。
-- `defines` 为**裸**宏名(不带 `-D`);feature 激活时每个脱糖为 `-D<x>`,加到该包
-  自己的编译上——与 `[targets.*] defines` 完全一致。按约定仅限包**自有**的带命名
-  空间宏:feature **不**注入自由的包级 `cflags`/`ldflags`,否则会破坏加性的 feature
-  并集模型。链接旗标来自 provider 依赖(见下文*`provides` / `requires`*),而非 feature。
-- 每个激活的 feature 仍会得到自动的 `-DMCPP_FEATURE_<NAME>`,`defines` 与之叠加。
-- `flags`(mcpp 0.0.101+)与 `[build].flags`([04 §2.3](04-mcpp-toml.md))共用同一有序 inline-table 数组
-  文法(`glob` 必填,加 `cflags`/`cxxflags`/`asmflags`/`defines`;与
-  `[[build.flags]]` 一样也接受 `[[features.<name>.flags]]` 拼写)。feature 激活时
-  条目追加在 base `[build].flags` **之后**(feature 按名
-  序),"last flag wins" 使 feature 规则可覆盖更宽的 base 规则;未激活时条目根本
-  不存在(不会有死 glob 告警)。这让 feature 的组内专属旗标与其 `sources` 同居,
-  而不必写成 base 规则、在 feature-off 构建里留下必死的 glob。与 `defines` 不同,
-  feature `flags` 是**私有 per-TU 构建旗标**——永不传播给消费者(与 `[build].flags`
-  同契约),因此不破坏加性模型:glob 限定作用面、顺序确定、无跨包效应。
+  `requires`、`provides`。其余键会被报为一条 schema warning 并忽略
+  (mcpp 2026.9.1.1+);`deps` 单独报为"保留"，并指向 `[feature-deps.<name>]`。
+  该版本之前，`[features]` 是唯一一个完全没有 schema 检查的结构化段落 ——
+  把 `include_dirs` 误写进 feature 里会零诊断地构建成功，而同样的错误写在
+  `[build]` 里会被报出来。
+- `defines` 是**裸**宏名（不带 `-D`）;feature 激活时，每个都在该包自己的编译上
+  脱糖为 `-D<x>` —— 与 `[targets.*] defines` 完全一致。按约定，它们仅限于包
+  **自有**的、带命名空间的宏：feature **不**注入自由的包级 `cflags`/`ldflags`,
+  否则会破坏可加的 feature 并集模型。链接旗标来自 provider 依赖（见下文
+  *`provides` / `requires`*），而不是来自 feature。
+- 每个激活的 feature 仍会得到自动的 `-DMCPP_FEATURE_<NAME>`,`defines` 叠加在
+  它之上。
+- `flags`（mcpp 0.0.101+）与 `[build].flags`（[04 §2.3](04-mcpp-toml.md)）共用
+  同一套有序、inline-table 数组的文法（`glob` 必填，加 `cflags`/`cxxflags`/
+  `asmflags`/`defines`；与 `[[build.flags]]` 一样，也接受
+  `[[features.<name>.flags]]` 这种 array-of-tables 拼法）。feature 激活时，
+  条目追加在 base `[build].flags` **之后**（各 feature 按名字排序）,"最后一条
+  旗标胜出"使 feature 规则能覆盖更宽的 base 规则；未激活时，这些条目根本不存在
+  （不会产生死 glob 告警）。这让 feature 的组内专属旗标与它的 `sources` 同居，
+  而不必写成 base 规则、在 feature 关闭的构建里留下一条注定命中不到的 glob。
+  与 `defines` 不同，feature 的 `flags` 是**私有的、per-TU 的构建旗标**——它们
+  从不传播给消费方（与 `[build].flags` 同一契约），因此不破坏可加模型：由 glob
+  限定作用面，顺序确定，没有跨包效应。
 
 
 ### 作为构建规则的 feature(mcpp 2026.9.7.1+)
 
-两个键把一个 feature 变成其它包可以使用的构建规则。它们是消费者只写一条依赖边、
-不写构建程序的原因。
+两个键能把一个 feature 变成其他包可以使用的构建规则。它们是消费方只写一条
+依赖边、不必写构建程序的原因。
 
 ```toml
 [features.rules-spirv]
@@ -113,49 +122,52 @@ rule_module       = "mcpp.rules.spirv"
 device_extensions = [".comp", ".vert", ".frag", ".glsl"]
 ```
 
-`device_extensions` 陈述这条规则编译哪些**设备源**扩展名。激活了该 feature 的消费者
-会把它们分类为设备源 —— 不扫描 import、不产 BMI、由 mcpp 不驱动的编译器编译。这与
-`[build] module_extensions` 是同一个形状:mcpp 知道设备源*是什么*,不知道 `.cu` 是
-CUDA,所以**一门新设备语言不需要引擎改动**。
-[42 — 异构硬件构建](42-heterogeneous-builds.md) 里那句「第六个后端是一个包而不是一次
-引擎改动」由此才成立;`.slang` 已从 mcpp 的内置表中移除,现在正是经由这条路到达的。
+`device_extensions` 陈述这条规则编译哪些**设备源**扩展名。激活了该 feature 的
+消费方会把它们分类为设备源 —— 不做 import 扫描、不产出 BMI、由 mcpp 不驱动的
+编译器编译。这与 `[build] module_extensions` 是同一个形状：mcpp 知道设备源
+*是什么*，不知道 `.cu` 是 CUDA，所以**一门新的设备语言不需要引擎改动**。
+[42 —— 异构硬件构建](42-heterogeneous-builds.md) 里"第六个后端是一个包而不是
+一次引擎改动"这句话由此才成立，而不只是愿望；`.slang` 已经从 mcpp 的内置表中
+移除，现在正是经由这条路到达的。
 
-`rule_module` 给出消费者的构建程序为够到这条规则而 import 的模块,以及它调用的
-`compile()` 所在。它是**声明**的而不是从源码扫描出来的,因为那个程序必须在任何东西
-被编译**之前**写出来,而一次为了决定写什么而去扫描依赖源码的构建会把两者的顺序颠倒。
+`rule_module` 给出消费方的构建程序为够到这条规则而 import 的模块，以及它要调用
+的 `compile()` 所在。它是**声明**出来的，而不是从源码扫描出来的，因为那个程序
+必须在任何东西被编译**之前**写出来，而一次为了决定写什么、去扫描依赖源码的构建，
+会把两者的先后顺序颠倒。
 
-由此得出两件事,而且都不把任何包名放进 mcpp:
+由此得出两件事，而且都没有把任何包名放进 mcpp:
 
-- **`host-module = true` 被推出来。** 一个点名了规则模块的 feature 已经说过那是使用
-  它的唯一方式,所以依赖边不必再说一遍。
-- **没有 `build.mcpp` 的包会得到一个。** mcpp 把这些规则描述的程序写进构建目录并编译
-  它。自带程序的包保留自己的:合成只填补缺席、绝不覆盖;而生成出来的那份就是这个工程
-  本来要手写的那份,所以接管它是一次复制加一次编辑。
+- **`host-module = true` 被隐含。** 一个点名了规则模块的 feature，已经说明那是
+  使用它的唯一方式，所以依赖边不必再说一遍。
+- **没有 `build.mcpp` 的包会得到一个。** mcpp 把这些规则描述的程序写进构建目录
+  并编译它。自带程序的包保留自己的那份：合成只填补缺席，绝不覆盖已有的；而
+  生成出来的那份，正是这个工程本来要手写的那份，所以接管它是一次复制加一次
+  编辑。
 
-feature 仍然**按名字**请求:
+feature 仍然**按名字**请求：
 
 ```toml
 [build-dependencies.mcpp]
 plugins = { version = "0.3.0", features = ["rules-spirv"] }
 ```
 
-早先的一版设计从工程源码里出现的扩展名推导这个集合。它被撤销了,因为两个包可能认领
-同一个扩展名 —— 第三方写一条处理 `.cu` 的规则是会发生的事 —— 也因为 manifest 的职责
-是描述这次构建,而派生出来的 feature 集合让文件不再陈述它。
+早先的一版设计，从工程源码里出现的扩展名推导这个集合。它被撤销了，原因有二：
+两个包可能认领同一个扩展名 —— 第三方写一条处理 CUDA 的规则是会发生的事 ——
+而且 manifest 的职责是描述这次构建，派生出来的 feature 集合不再做到这一点。
 
-两个键必须成对出现。只写其一是一条没有任何东西能据以行动的声明,会在解析期被拒绝,
-而不是留到消费者的构建里。
+两个键必须成对出现。只写其一是一条没有任何东西能据以行动的声明，会在解析期
+被拒绝，而不是留到消费方的构建里才发现。
 
 
-## `provides` / `requires` —— 能力(后端选择)
+## `provides` / `requires` —— 能力（后端选择）
 
-**capability(能力)** 是一个共享的抽象名字(如 `blas`)。包可以 *provide*(提供)
-一种能力;feature 可以 *require*(需要)一种能力而非点名某个具体包,解析器会从依赖
-图中绑定**恰好一个** provider。这样就能在多个可互换后端(OpenBLAS / MKL / …)中选其
-一,而不必把选择写死进库里。
+**能力**（capability）是一个共享的抽象名字（例如 `blas`）。包可以 *provide*
+（提供）一种能力；feature 可以 *require*（需要）一种能力而不点名某个具体包，
+解析器会从依赖图中绑定**恰好一个** provider。这样就能在多个可互换的后端
+（OpenBLAS / MKL / …）之间选出一个，而不必把选择写死进库里。
 
 ```toml
-# provider 包为任何 require 它的依赖方满足某能力。
+# A provider package satisfies a capability for any dependent that requires it.
 [package]
 name     = "compat.openblas"
 version  = "0.3.0"
@@ -163,21 +175,20 @@ provides = ["blas", "lapack"]
 ```
 
 ```toml
-# 消费方经由自己的某个 feature 来 require 这个抽象能力。
+# A consumer requires the abstract capability via one of its features.
 [features]
 use_blas = { defines = ["EIGEN_USE_BLAS"], requires = ["blas"] }
 
-# 图中有 >1 个 provider 时,选其一(否则构建报错并列出候选)。
+# When >1 provider is in the graph, pick one (else the build errors and lists them).
 [capabilities]
-blas = "compat.openblas"     # 等价于:mcpp build --cap blas=compat.openblas
+blas = "compat.openblas"     # equivalently: mcpp build --cap blas=compat.openblas
 
 [dependencies]
-compat.openblas = "0.3.0"    # provider 必须是图中真实存在的依赖
+compat.openblas = "0.3.0"    # the provider must be a real dependency in the graph
 ```
 
-保留前缀 `mcpp:` 命名本引擎解析的目标侧层,这些名字对照一个闭集校验。
-包级 `requires` 数组承载对称的陈述 —— 某个目标侧层必须解析为什么,
-本包才可用。
+保留前缀 `mcpp:` 命名本引擎解析的目标侧层，这些名字对照一个闭集做校验。包级的
+`requires` 数组承载对称的陈述 —— 某个目标侧层必须解析出什么，本包才可用。
 
 ```toml
 [package]
@@ -187,7 +198,8 @@ provides = ["mcpp:compiler-runtime=compiler-rt", "mcpp:c++-abi=libc++"]
 requires = ["mcpp:compiler=llvm"]
 ```
 
-对产物 ABI 开关的需求用 `requires_abi` 陈述,写在包上或某个 feature 上,而不是写成层:
+对产物 ABI 开关的需求，用 `requires_abi` 陈述，写在包上或某个 feature 上，而不是
+写成一层：
 
 ```toml
 [package]
@@ -197,12 +209,13 @@ requires_abi = { threads = true }
 mt = { requires_abi = { threads = true } }
 ```
 
-只有根 manifest 设置该开关(`[target.<selector>.abi]`,见 [22 —— 目标侧](22-target-side.md));
-根包未满足的需求在编译之前被拒绝,拒绝信息指出包与 feature。安装钩子针对某一个 C++ 标准库编译静态库的
-包,则把该实现陈述为层需求,即 `requires = ["mcpp:c++-abi=libstdc++"]`,原因见同一章。
+只有根 manifest 能设置这个开关（`[target.<selector>.abi]`，见
+[22 —— 目标侧](22-target-side.md)）；根未满足的需求会在编译之前被拒绝，拒绝信息
+点名包与 feature。安装钩子针对某一个 C++ 标准库编译静态库的包，把该实现陈述为
+层需求，即 `requires = ["mcpp:c++-abi=libstdc++"]`，原因见同一章。
 
-作为标准库的包在 `[build]` 下陈述它的 `std` 模块源,
-其所需的 flag 在那里与任何其它构建输入一样可条件化。
+作为标准库的包，在 `[build]` 下陈述它的 `std` 模块源，它所需的 flag 在那里与
+任何其他构建输入一样，可以条件化。
 
 ```toml
 [build]
@@ -214,41 +227,43 @@ std-module-flags  = ["--no-default-config", "-nostdinc++"]
 std-module-flags = ["-D_GNU_SOURCE"]
 ```
 
-五个层、约束它们的规则与相应诊断,见 [22 - 目标侧](22-target-side.md)。
+五个层、约束它们的规则，以及相应的诊断，见 [22 —— 目标侧](22-target-side.md)。
 
-绑定是**确定性**的:
+绑定是**确定性**的：
 
 | 图中某被需要能力的 provider 数量 | 结果 |
 |---|---|
-| 恰好一个 | 自动绑定(无需配置) |
+| 恰好一个 | 自动绑定（无需配置） |
 | `[capabilities]` pin / `--cap` 指定了一个 | 以 pin 为准 |
-| 零个 | **报错**:没有包提供 `<cap>` |
-| 两个及以上且未 pin | **报错**并列出候选——绝不静默猜测 |
+| 零个 | **报错**：没有包提供 `<cap>` |
+| 两个及以上，且未 pin | **报错**并列出候选 —— 绝不静默猜测 |
 
-被绑定 provider 的链接/头文件旗标经由常规依赖机制流到消费方;capability 层是那道
-*选择与校验* 步骤,把"静默选错后端 / 缺后端"变成构建期的显式报错。
+被绑定 provider 的链接/头文件旗标，经由普通的依赖机制流向消费方；capability
+层是那道*选择与校验*步骤，把"静默选错后端"或"缺后端"变成构建期的显式报错。
 
-**绑定选中的是 provider,它不裁剪链接行。** 依赖包的目标文件一律进入消费方的链接,
-与它的能力是否被绑定无关。实测:两个包都提供同一能力且都定义 `cap_probe`,未 pin 时
-解析按上表报错;按提示用 `[capabilities]` pin 其中一个之后,构建走到链接器才失败——
+**绑定选中的是 provider，它不裁剪链接行。** 依赖包的目标文件一律进入消费方的
+链接，与它的能力是否被绑定无关。实测：两个包都提供同一能力，都定义
+`cap_probe`；未 pin 时，解析按上表报错；用 `[capabilities]` pin 其中一个之后，
+构建走到链接器才失败 ——
 
 ```
 ld: obj/mcpplibs_pa/src/impl.o: in function `cap_probe':
     multiple definition of `cap_probe'; obj/mcpplibs_pb/src/impl.o: first defined here
 ```
 
-这一点对**多个 provider 定义同一批符号**的能力有影响 —— 全程序单例(例如
-`operator new`),或名字集合固定的 C 接口。对这类能力,图中出现两个 provider 是**待修的
-缺陷**而非可 pin 的歧义:pin 会把一个点名两个候选的报错,换成一个点名 mangled 符号的报错。
-可互换的**库**(各 BLAS 实现导出不同的符号集合,按链接选其一)不受此影响。
+这一点对**多个 provider 定义同一批符号**的能力有影响 —— 一个全程序单例（例如
+`operator new`），或一个名字集合固定的 C 接口。对这类能力而言，图中出现两个
+provider 是一个**待修的缺陷**，而不是一个可以 pin 的歧义：pin 会把一个点名两个
+候选的报错，换成一个点名 mangled 符号的报错。可互换的**库**（各 BLAS 实现导出
+不同的符号集合，按链接各自选一个）不受此影响。
 
 ### `exclusive` —— 包声明自己是唯一提供者
 
-上一段描述的是一个引擎**看不见**的缺陷:要看出两个 provider 定义了同一批符号,
-需要它们的目标文件,而绑定 capability 时那些还不存在;而「一律拒绝重复 provider」
-又会打断同一段里那个合法的 BLAS 用例。
+上一段描述的是一个引擎**看不见**的缺陷：要看出两个 provider 定义了同一批符号，
+需要它们的目标文件，而绑定 capability 时那些文件还不存在；而"一律拒绝重复
+provider"这条规则，又会打断同一段里那个合法的 BLAS 用例。
 
-所以由包自己声明:
+所以由包自己声明：
 
 ```toml
 [package]
@@ -257,25 +272,29 @@ provides  = ["gpu-blas"]
 exclusive = ["gpu-blas"]
 ```
 
-两个都提供 `gpu-blas` 的包,只要其中至少一个声明了独占,就在绑定 capability 时
-被拒绝 —— 在任何东西被编译之前,并点名该能力与双方:
+两个都提供 `gpu-blas` 的包，只要其中至少一个声明了独占，就在绑定 capability
+时被拒绝 —— 在任何东西被编译之前，并点名该能力与双方 provider:
 
 ```
 error: capability 'gpu-blas' is provided by more than one package, and they
        declare it EXCLUSIVE.
          providers: [compat.cublas, compat.rocblas]
          exclusive: [compat.cublas, compat.rocblas]
+       Two implementations of one interface define the same symbols, so the
+       link would resolve every call to whichever archive it reached first.
+       Keep one of them — a `[capabilities]` pin selects a provider for a
+       REQUIREMENT and cannot make two definitions of one symbol safe.
 ```
 
-该拒绝在 `--format json` 里报 `exclusive-capability`(见第 11 章)。
+这个拒绝在 `--format json` 里报 `exclusive-capability`（见第 11 章）。
 
-### `version-floor` —— 对机器的要求高于它所有
+### `version-floor` —— 对机器的要求超出它所有
 
-有些关于机器的事实约束着能为它构建什么,而忽略它们时的失败来得很晚:
-一个针对比它将遇到的驱动更新的运行时构建出来的程序,**干净地链接**,
-在第一次使用时失败,而消息里两侧都没有。
+关于一台机器的某些事实约束着能为它构建什么，而忽略它们时的失败来得很晚：一个
+针对比它将遇到的驱动更新的运行时构建出来的程序，链接得干干净净，却在第一次
+使用时失败，而且错误消息不点名任何一侧。
 
-包声明它需要什么:
+包声明它需要什么：
 
 ```toml
 [[runtime.requirements]]
@@ -283,36 +302,38 @@ kind  = "version-floor"
 value = "cuda.driver >= 12.0"
 ```
 
-而某个在**安装期**(探测该发生的地方)确立了机器某项事实的包,声明它:
+而某个在**安装期**（探测本该发生的地方）确立了机器上某项事实的包，声明它：
 
 ```toml
 [runtime]
 provides = ["cuda.driver=12.4"]
 ```
 
-mcpp 在绑定 capability 时比较二者,并在任何东西被编译之前拒绝,
-报 `version-floor-unmet`:
+mcpp 在绑定 capability 时比较二者，并在任何东西被编译之前拒绝，报
+`version-floor-unmet`:
 
 ```
 error: `toolkitnew` requires cuda.driver >= 13.0, and cuda.driver is stated as 12.4.
          stated by: driverfact
 ```
 
-**没有任何厂商词汇抵达引擎。** 它读到的是一个名字、一个关系和一个版本;
-`cuda.driver` 是流过的数据,一个 mcpp 从未听说过的后端比较方式完全相同。
+**没有任何厂商词汇抵达引擎。** 它读到的是一个名字、一个关系和一个版本；
+`cuda.driver` 只是流过它的数据，一个 mcpp 从未听说过的后端，比较方式完全相同。
 
-**没人回答的下界是沉默的。** 一台从未声明自己有什么的机器,不是「未满足下界」的机器,
-而是「没人问过」的机器。把「我们不知道」变成「不行」正是这个机制要避免的失败,
-并且有直接判据:`tests/e2e/603_version_floor.sh` 会构建一个下界指向无人提供之物的工程。
+**没人回答过的下界是沉默的。** 一台从未声明过自己有什么的机器，不是"未满足
+下界"的机器，而是"没人问过"的机器。把"我们不知道"变成"不行"，正是这个机制
+要避免的那种失败，而且有一条直接判据：`tests/e2e/603_version_floor.sh` 构建了
+一个下界指向无人提供之物的工程。
 
-**引擎陈述目标的平台下限**(mcpp 2026.9.14.2+)。在编译器接受最低平台版本的行上,
-引擎以平台自己的术语把该版本陈述为一项事实,包像对待其他事实一样对它写下界:
+**引擎陈述目标的平台下限**(mcpp 2026.9.14.2+)。在编译器接受一个最低平台版本
+的那一行上，引擎以该平台自己的说法，把这个版本陈述为一项事实，包像对待其他
+事实一样，对它写下界：
 
-| 事实 | 行 | 设定来源 |
+| 事实 | 适用行 | 设定来源 |
 |---|---|---|
-| `android.api-level` | `*-linux-android` | `[target.<triple>] min_api_level`,否则为工具链支持的最低级别 |
-| `ios.deployment-target` | iOS 真机与模拟器各行 | `[build] ios_deployment_target`,否则为定位到的 SDK 版本 |
-| `macos.deployment-target` | macOS 各行 | `[build] macos_deployment_target`,否则为 mcpp 的 macOS 默认值 |
+| `android.api-level` | `*-linux-android` | `[target.<triple>] min_api_level`，否则取工具链支持的最低级别 |
+| `ios.deployment-target` | iOS 真机与模拟器各行 | `[build] ios_deployment_target`，否则取定位到的 SDK 版本 |
+| `macos.deployment-target` | macOS 各行 | `[build] macos_deployment_target`，否则取 mcpp 在 macOS 上的默认值 |
 
 ```toml
 [[runtime.requirements]]
@@ -325,55 +346,58 @@ error: `fw` requires android.api-level >= 23, and this build targets 21.
          set by: [target.x86_64-linux-android] min_api_level
 ```
 
-不陈述这类事实的行上,该要求保持沉默,因此要求本身不需要选择器。下限不会替依赖
-抬高:键设定的值就是编译器面向的值,应用安装到哪些设备上由应用决定。包陈述同名
-事实不会替换引擎陈述的那一项。
+不陈述这类事实的行，让这条要求保持沉默，因此要求本身不需要选择器。下限不会替
+依赖抬高：这个键设定的值，就是编译器实际面向的值，而应用要安装到哪些设备上，
+是应用自己的决定。一个包陈述同名事实，不会替换引擎陈述的那一项。
 
-**它是关于这个包自己的符号的声明**,所以一条指向本包并不提供的能力的条目会被报为
-schema 警告:那里没有可独占的东西。而无人声明独占的能力行为完全不变 —— 两个 BLAS
-实现照常共存,既有的「两个或更多、未 pin」报错也仍然只在**有人 require** 该能力时出现。
+**这是一条关于本包自己的符号的声明**，所以一条指向本包并不提供的能力的条目，
+会被报为一条 schema warning：那里没有可独占的东西。而无人声明独占的能力，
+行为完全不变 —— 两个 BLAS 实现照常共存，既有的"两个或更多、未 pin"报错也仍然
+只在**有人 require** 该能力时才出现。
 
-## `[feature-deps.<name>]` —— 由 feature 拉取的依赖
+## `[feature-deps.<name>]` —— feature 拉取的依赖
 
-在 `[feature-deps.<name>]` 下声明的依赖是**可选的**:仅当该 feature 激活时(根 `--features`,
-或某依赖 spec 的 `features = [...]`)才会被解析。`[dependencies]` 中的依赖始终被解析;
-可选性由声明的*位置*表达,而非某个标志位。
+在 `[feature-deps.<name>]` 下声明的依赖是**可选的**：仅当该 feature 激活时
+（根的 `--features`，或某依赖 spec 的 `features = [...]`）才会被解析。
+`[dependencies]` 中的依赖始终被解析；可选性由声明的*位置*表达，而不是由某个
+标志位表达。
 
 ```toml
 [features]
 use_blas         = { defines = ["EIGEN_USE_BLAS"], requires = ["blas"] }
 backend-openblas = { implies = ["use_blas"] }
 
-# 仅当 `backend-openblas` 激活时才拉取。每个条目都是完整的依赖 spec
-#(version/path/git + 其自身的 features)。
+# Pulled ONLY when `backend-openblas` is active. Each entry is a full dependency
+# spec (version/path/git + its own features).
 [feature-deps.backend-openblas]
 compat.openblas = "0.3"
 ```
 
-**写 `"^0.3.0"`,而不是 `"0.3.x"` 或 `"0.3"`。** 以索引中确定存在的包作对照,
-判据取**构建成功**:
+**写 `"^0.3.0"`，而不是 `"0.3.x"` 或 `"0.3"`。** 以索引中确定存在的一个包做
+对照，判据取**构建成功**:
 
 | 写法 | 结果 |
 |---|---|
 | `cmdline = "0.0.1"` | 构建通过 |
 | `cmdline = "^0.0.1"` | 构建通过 |
-| `cmdline = "0.0"` | 解析通过,随后 `install path missing after fetch` |
-| `cmdline = "0.0.x"` | `E_NOT_FOUND`,点名的是包 —— 而该包存在 |
+| `cmdline = "0.0"` | 解析通过，随后 `install path missing after fetch` |
+| `cmdline = "0.0.x"` | `E_NOT_FOUND`，点名的是那个存在的包 |
 
-这三种结果值得分开,因为两个更弱的判据各自会放行一种不可用的写法:
-「没有 `E_NOT_FOUND`」放行两段前缀,「解析通过」同样放行它。**只有对着真实索引构建
-一次**才能定论。
+这三种结果值得分开看，因为有两个更弱的判据，各自会放行一种不可用的写法：
+"没有 `E_NOT_FOUND`"放行两段式前缀，"解析通过"同样放行它。**只有对着真实索引
+构建一次**才能定论。
 
-这一点在此处比在 `[dependencies]` 中更要紧:**实现取不回来的 feature 等于不存在的
-feature**,而开发期使用 **path** 依赖的工程根本不查索引 —— 该失败只在发布之后才出现,
-而且是出现在别人身上。
+这一点在此处比在 `[dependencies]` 里更要紧。一个取不回实现的 feature，等于
+一个不存在的 feature；而开发期使用**path** 依赖的工程根本不查索引 —— 这个
+失败只在发布之后才出现，而且出现在别人身上。
 
-该机制与能力(上文*`provides` / `requires`*)组合:单个 `backend-openblas` feature 既**拉取** provider
-(`compat.openblas`,其 `provides = ["blas"]`),又**开启**消费方开关
-(`implies = ["use_blas"]`,其 `requires = ["blas"]`)。当图中只有一个 provider 时,
-能力自动绑定——消费方只需写 `features = ["backend-openblas"]`。
+这一机制与能力（见上文 *`provides` / `requires`*）组合使用：单个
+`backend-openblas` feature 既**拉取** provider（`compat.openblas`，其
+`provides = ["blas"]`），又**开启**消费方的开关（`implies = ["use_blas"]`，
+其 `requires = ["blas"]`）。图中只有一个 provider 时，能力自动绑定 ——
+消费方只需写 `features = ["backend-openblas"]`。
 
-在索引包的 Lua 描述符中,等价写法为内联形式:
+在索引包的 Lua 描述符中，同样的内容写成内联形式：
 
 ```lua
 features = {
@@ -387,71 +411,76 @@ features = {
 
 ### 保持可替换的默认实现
 
-同样这三件东西,也覆盖"库希望**提供**一份实现但不**强加**一份"的情形 —— 全程序单例,
-例如 `operator new`、日志 sink、panic handler:
+同样这三件东西，也覆盖了"库希望**提供**一份实现，但不**强加**一份"的情形 ——
+一个全程序单例，例如 `operator new`、一个日志 sink、一个 panic handler:
 
 ```toml
 [features]
 default   = []
-# 消费方开关:"我用到了本库中需要分配器的那部分"。
+# The consumer-side switch: "I use the part of this library that needs an allocator".
 alloc     = { requires = ["freestanding-allocator"] }
-# 内置默认:激活它就够了。
+# The built-in default: activating this one is enough.
 alloc-kal = { implies = ["alloc"] }
 
-# 仅在 `alloc-kal` 激活时解析,因此库本体不携带对该实现的依赖。
+# Resolved only when `alloc-kal` is active, so the library itself carries no
+# dependency on the implementation.
 [feature-deps.alloc-kal]
 std-freestanding-alloc-kal = "0.1.x"
 ```
 
-三种用法各一行:
+三种用法各一行：
 
-| 消费方需要 | 清单中的写法 |
+| 消费方需要 | manifest 中的写法 |
 |---|---|
 | 不用会分配的那部分 | `std-freestanding = "0.2.0"` —— 分配器不进图 |
-| 默认实现 | `features = ["alloc-kal"]` —— 实现随之进图,**无需知道其包名** |
-| 自己的或第三方的 | `features = ["alloc"]` 加一个 `provides = ["freestanding-allocator"]` 的包 |
+| 内置的默认实现 | `features = ["alloc-kal"]` —— 实现随之进图，不必知道它的包名 |
+| 自己的或第三方的实现 | `features = ["alloc"]` 加一个 `provides = ["freestanding-allocator"]` 的包 |
 
-有两条性质使该形状优于无条件随包提供实现。随包提供实现的库替程序做了本属程序的决定,
-而且**撤销不掉**:feature 是**加性**的,消费方没有把某个默认**关掉**的手段。以及,由于
-依赖包的目标文件无条件参与链接(上文*`provides` / `requires`*),随包的默认加上程序自备的那份是**重复定义**
-而非替换 —— 让 C++ 标准库能提供可替换 `operator new` 的那套归档语义,对包依赖并不适用。
-把实现放在开关之后,意味着两者**从不共存**。
+有两条性质，使这个形状优于随包无条件提供实现。随包提供实现的库，替程序做了
+一个本该属于程序的决定，而且**撤销不掉**:feature 是**可加的**，消费方没有
+把某个默认实现**关掉**的手段。此外，由于依赖包的目标文件无条件参与链接
+（见上文 *`provides` / `requires`*），随包的默认实现加上程序自备的一份，
+是**重复定义**而不是替换 —— 让 C++ 标准库能提供一个可替换的 `operator new`
+的那套归档语义，并不适用于普通的包依赖。把实现放在开关之后，意味着两者
+**从不共存**。
 
 ### 平台 SDK 依赖保持私有
 
-一个绑定到某个平台的包 —— 它需要那个平台的头文件才能实现某个功能,而不是
-为了陈述自己的接口 —— 在 `[feature-deps.<feature>]` 下用 `visibility = "private"`
-依赖该 SDK:
+一个绑定到某个平台的包 —— 它需要那个平台的头文件才能实现某项功能，而不是为了
+陈述自己的接口 —— 在 `[feature-deps.<feature>]` 下用 `visibility = "private"`
+来依赖那个 SDK:
 
 ```toml
 [features]
 windows-crt = {}
 
-# 仅在激活该行时解析,其头文件只到达本包自己的翻译单元。
+# Resolved only on the row that activates it, and its headers reach ONLY
+# this package's own translation units.
 [feature-deps.windows-crt]
 some.windows-headers = { version = "1.0", visibility = "private" }
 ```
 
-`visibility` 是任意依赖项 spec 的一个字段(默认 `public`,还可以是 `private`
-或 `interface` —— 见[05 — 依赖](05-dependencies.md))。让 SDK 不跨越包边界的正是
-`private`:该依赖的头文件目录、宏定义与 flag 只并入本包自己的构建,到此为止,
-正如 `privateIncludeDirs` 让一个包**自己的**内部头文件不到达它的消费方。
-一个依赖该平台绑定包并激活 `windows-crt` 的消费方,会得到这个功能;它不会在
-自己的 `-I` 列表里得到 `some.windows-headers` 的目录,甚至无法按名字
+`visibility` 是任意依赖 spec 的一个字段（默认 `public`，还可以是 `private`
+或 `interface` —— 见 [05 —— 依赖](05-dependencies.md)）。让 SDK 不跨越包边界的
+正是 `private`：该依赖的头文件目录、宏定义与 flag 只并入本包自己的构建，到此
+为止，正如 `privateIncludeDirs` 让一个包**自己的**内部头文件不到达它的消费方。
+一个依赖该平台绑定包、并激活 `windows-crt` 的消费方，会得到这项功能；它不会在
+自己的 `-I` 列表里得到 `some.windows-headers` 的目录，甚至无法按名字
 `#include` 它的头文件。
 
-这正是[24 —— openkal 与由依赖图供给的目标](24-openkal-cross.md)所指向的模式:
-一个包若需要它声明的层(`kernel-abi`、`c-abi`、`c++-abi`)之外的平台头文件,
-这个依赖是合法的,但不能变成每一个消费方的问题。把它写成 `public`
-(或者不写 `visibility`,二者等价)正是本节要指出的错误 —— 对声明它的包而言这样
-可以工作,却会把 SDK 的头文件不由分说地交给消费方,而消费方构建的目标上很可能
-根本不该出现这个 SDK。
+这正是 [24 —— openkal 与由依赖图供给的目标](24-openkal-cross.md) 为一个需要
+超出其已声明层（`kernel-abi`、`c-abi`、`c++-abi`）之外平台头文件的包所指向
+的模式：这条依赖是合法的，但它不能变成每一个消费方的问题。把它写成 `public`
+（或者不写 `visibility`，二者等价）正是本节要指出的错误 —— 对声明它的包而言，
+这样能工作；但这会把 SDK 的头文件不由分说地交给消费方，而消费方构建的目标上
+很可能根本不该出现这个 SDK。
 
-#### 让闭包也能看见它,而不只是私有(mcpp 2026.9.18+)
+#### 让闭包也能看见它，而不只是私有（mcpp 2026.9.18+）
 
-`visibility = "private"` 回答的是「这个依赖会不会泄漏到消费方的 `-I` 列表」,不回答
-「这个依赖到底在不在图里」——后者是[22 —— 目标侧](22-target-side.md#闭包可见性)
-要为**整个构建**回答的问题。由 SDK 包自己陈述报告或拒绝开关需要的事实:
+`visibility = "private"` 回答的是"这个依赖会不会泄漏到消费方的 `-I` 列表",
+不回答"这个依赖到底在不在图里" —— 后者是
+[22 —— 目标侧](22-target-side.md#闭包可见性) 要为**整个构建**回答的问题。
+SDK 包自己陈述报告或拒绝所需要的那项事实：
 
 ```toml
 [package]
@@ -460,22 +489,22 @@ version  = "1.0.0"
 provides = ["platform-sdk"]
 ```
 
-`platform-sdk` 是一个普通的、不带命名空间前缀的能力——像上面的 `blas`,不像
-`mcpp:c-abi=<impl>`——因为它不指代引擎解析的任何一层,只是包对自己陈述的一个事实。
-构建的 `Target` 报告会列出图中每一个声明了它的包(没有则显示为空);
-`[build] platform-dependencies = "refuse"` 则在它出现时直接让构建失败——这是
-「本次构建完全是基于其 kernel-abi 实现的闭包,不多不少」这句话的机器可核验形式。
-同时声明 `provides = ["platform-sdk"]` 与 `visibility = "private"` 才是完整的陈述:
-private 让头文件不出现在消费方的搜索路径上,`platform-sdk` 让这个事实不从任何人的
-报告里消失。
+`platform-sdk` 是一个普通的、不带命名空间前缀的能力 —— 像上文的 `blas`，不像
+`mcpp:c-abi=<impl>` —— 因为它不指代引擎解析的任何一层，只是包对自己陈述的一项
+事实。一次构建的 `Target` 报告会列出图中每一个声明了它的包（没有则为空）;
+`[build] platform-dependencies = "refuse"` 会在它出现时直接让构建失败 —— 这是
+"本次构建完全是基于其 kernel-abi 实现的闭包，不多不少"这句话的机器可核验形式。
+同时声明 `provides = ["platform-sdk"]` 与 `visibility = "private"`，才是完整
+的陈述：private 让头文件不出现在消费方的搜索路径上，`platform-sdk` 让这项事实
+不从任何人的报告里消失。
 
 ## 当前边界
 
-**默认 feature 在 manifest 里关掉,不在命令行上关掉。** 没有 `--no-default-features`。
-`mcpp build --features metrics` 激活的是 `default ∪ {metrics}`;要在不带 `default`
-某个成员的情况下构建,得改 `[features] default`。实测于 2026.9.8.1。
-
-**依赖不能以加速器为条件。** `accelerator` 是从依赖图解析出来的,因此由它选择的
-依赖会决定它自己在问的那个答案。mcpp 会报告该谓词并忽略它。包要么无条件,要么以
-平台为条件;由加速器选择的是 `[build] sources`。
+**默认 feature 在 manifest 里关掉，不在命令行上关掉。** 没有
+`--no-default-features`。`mcpp build --features metrics` 激活的是
+`default ∪ {metrics}`；要在不带 `default` 中某个成员的情况下构建，得改
+`[features] default`。实测于 2026.9.8.1。
 
+**依赖不能以加速器为条件。** `accelerator` 是从依赖图中解析出来的，因此由它
+选择的依赖会决定它自己所问的那个答案。mcpp 会报告该谓词并忽略它。包要么无
+条件，要么以平台为条件；由加速器选择的是 `[build] sources`。
diff --git a/docs/zh/07-workspace.md b/docs/zh/07-workspace.md
index a19ec8d15..128c4c436 100644
--- a/docs/zh/07-workspace.md
+++ b/docs/zh/07-workspace.md
@@ -1,24 +1,26 @@
 # 07 —— 工作空间
 
-**读者:**仓库里不止一个包的作者。
+**读者：** 仓库里不止一个包的作者。
 
-**本章回答的那一个问题:**多个包怎样成为一次构建,以及一个成员与其余成员共享什么。
+**本章回答的那一个问题：** 多个包怎样成为一次构建，以及一个成员与其余成员共享什么。
 
-**不在这里:**把这些包发布出去,那是 [11 —— 发布一个库](11-publishing-a-library.md)。
-在此之前:[06 —— Feature 与能力](06-features-and-capabilities.md)。在此之后:
+**不在这里：** 把这些包发布出去，那是 [11 —— 发布一个库](11-publishing-a-library.md)。
+在此之前：[06 —— Feature 与能力](06-features-and-capabilities.md)。在此之后：
 [08 —— 测试](08-testing.md)。
 
-工作空间允许在同一个仓库中组织和管理多个相关的 mcpp 包（库或应用程序）。各成员包共享统一的依赖版本配置和工具链设置，同时保持独立的 `mcpp.toml` 工程文件。
+工作空间在同一个仓库中组织多个相关的 mcpp 包（库或应用程序）。各成员包共享统一
+的依赖版本与工具链配置，同时各自保留独立的 `mcpp.toml` 工程文件。
 
 ## 1. 概述
 
 工作空间解决以下问题：
 
-- **依赖版本统一管理** — 多个子包使用相同版本的第三方依赖，避免重复声明和版本不一致
-- **工具链配置共享** — 在工作空间根目录统一声明工具链，各成员继承或覆盖
-- **多包协同开发** — 库与应用在同一仓库中开发，通过 `path` 依赖相互引用
+- **依赖版本统一管理**——多个子包使用相同版本的第三方依赖，避免重复声明与版本漂移。
+- **工具链配置共享**——在工作空间根声明一次工具链，成员继承或按需覆盖。
+- **多包协同开发**——库与应用在同一仓库中开发，通过 `path` 依赖相互引用。
 
-工作空间不改变依赖声明方式。成员之间通过已有的 `path = "..."` 机制声明依赖关系，与非工作空间项目的用法完全一致。
+工作空间不改变依赖的声明方式。成员之间通过既有的 `path = "..."` 机制相互引用，
+与非工作空间工程的用法完全一致。
 
 ## 2. 工程文件结构
 
@@ -35,9 +37,9 @@ members = [
 ]
 ```
 
-`members` 列出各成员包的相对路径，每个路径下须包含独立的 `mcpp.toml`。
+`members` 列出各成员包的相对路径，每个路径下必须包含各自的 `mcpp.toml`。
 
-可选 `exclude` 字段排除特定路径：
+可选字段 `exclude` 排除特定路径：
 
 ```toml
 [workspace]
@@ -45,17 +47,19 @@ members = ["libs/*"]
 exclude = ["libs/experimental"]
 ```
 
-### 2.2 虚拟工作空间与根包工作空间
+### 2.2 虚拟工作空间与带根包的工作空间
 
-**虚拟工作空间**：根 `mcpp.toml` 仅包含 `[workspace]`，不包含 `[package]`。根目录不产出构建产物，仅作为管理节点。
+**虚拟工作空间**：根 `mcpp.toml` 只含 `[workspace]`，不含 `[package]`。根目录不
+产出构建产物，只作为管理节点。
 
 ```toml
-# 虚拟工作空间 — 只有 [workspace]
+# 虚拟工作空间 —— 只有 [workspace]
 [workspace]
 members = ["libs/core", "apps/server"]
 ```
 
-**根包工作空间**：根 `mcpp.toml` 同时包含 `[package]` 和 `[workspace]`。根目录本身也是一个可构建的包。
+**带根包的工作空间**：根 `mcpp.toml` 同时含 `[package]` 与 `[workspace]`。根目录
+本身也是一个可构建的包。
 
 ```toml
 [workspace]
@@ -71,7 +75,7 @@ myproject.core = { path = "libs/core" }
 
 ### 2.3 成员工程文件
 
-各成员维护独立的 `mcpp.toml`，结构与普通项目一致：
+各成员维护自己的 `mcpp.toml`，结构与普通工程相同：
 
 ```toml
 # libs/core/mcpp.toml
@@ -84,7 +88,7 @@ version   = "0.1.0"
 kind = "lib"
 ```
 
-成员之间通过 `path` 依赖引用：
+成员之间通过 `path` 依赖相互引用：
 
 ```toml
 # libs/http/mcpp.toml
@@ -100,9 +104,10 @@ myproject.core = { path = "../core" }
 mbedtls.workspace = true
 ```
 
-## 3. 依赖版本继承
+## 3. 依赖版本的继承
 
-在 `[workspace.dependencies]` 中集中声明依赖版本，成员通过 `.workspace = true` 继承：
+在 `[workspace.dependencies]` 中集中声明依赖版本，成员通过 `.workspace = true`
+继承：
 
 ```toml
 # 根 mcpp.toml
@@ -124,16 +129,17 @@ mbedtls.workspace = true    # 继承版本 → "3.6.1"
 gtest.workspace = true      # 继承版本 → "1.15.2"
 ```
 
-成员可以覆盖继承的版本：
+成员可以覆盖继承来的版本：
 
 ```toml
 [dependencies.compat]
-mbedtls = "4.0.0"          # 覆盖，不使用 workspace 版本
+mbedtls = "4.0.0"          # override; does not use the workspace version
 ```
 
-## 4. 工具链与构建配置继承
+## 4. 工具链与构建配置的继承
 
-工作空间根的 `[toolchain]` 和 `[target.<triple>]` 配置自动继承到所有成员。成员可在自身的工程文件中覆盖。
+工作空间根的 `[toolchain]` 与 `[target.<triple>]` 配置由全体成员自动继承。成员
+可以在自己的工程文件中覆盖。
 
 配置优先级（从高到低）：
 
@@ -144,7 +150,7 @@ mbedtls = "4.0.0"          # 覆盖，不使用 workspace 版本
 5. 内置默认值
 
 ```toml
-# 工作空间根
+# workspace root
 [toolchain]
 default = "gcc@16.1.0"
 
@@ -154,21 +160,21 @@ linkage   = "static"
 ```
 
 ```toml
-# 某成员覆盖工具链
+# a member overrides the toolchain
 [toolchain]
 default = "llvm@20.1.7"
 ```
 
 ### 4.1 `[workspace.package]` 与 `[workspace.build]`
 
-所有成员共享的包元信息与构建标志,在 workspace 根声明一次:
+全体成员共享的包元信息与构建标志，在工作空间根声明一次：
 
 ```toml
 [workspace]
 members = ["libs/core", "libs/http", "apps/server"]
 
 [workspace.package]
-standard = 26                  # 也可写 "c++26",两种拼法都接受
+standard = 26                  # or "c++26"; both spellings are accepted
 version  = "0.4.2"
 license  = "Apache-2.0"
 authors  = ["example"]
@@ -178,58 +184,61 @@ cxxflags         = ["-Wall", "-Wextra"]
 dialect_cxxflags = ["-fno-exceptions"]
 ```
 
-成员只声明属于它自己的部分:
+成员只声明属于自己的部分：
 
 ```toml
 [package]
 name = "core"
-# standard / version / license / authors 继承自 workspace
-# [workspace.build] 的 cxxflags 也继承
+# standard, version, license and authors are inherited;
+# [workspace.build] cxxflags are inherited
 ```
 
 **合并规则。**
 
-| 类别 | 规则 |
+| 种类 | 规则 |
 |---|---|
-| 标量(`standard`、`version`、`license`、`c_standard`、`linkage` 等) | 成员**声明了该键**时成员优先;否则取 workspace 的值 |
-| 向量(`cxxflags`、`ldflags`、`defines`、`dialect_cxxflags`、`include_dirs` 等) | 追加,**workspace 在前** —— 成员自己的标志排在命令行后面,后者生效 |
-| `[workspace.dependencies]` | 逐依赖显式选择加入,`x.workspace = true`(§3) |
-
-"声明了"指的是**这个键被写过**,而不是它的值与默认值不同。成员在
-`[workspace.package] standard = 26` 之下刻意写 `standard = "c++23"`,得到的就是
-c++23;什么都不写的成员得到 c++26。这两种情况的值相同而意图相反,所以这个事实是被
-**记录**下来的,而不是推断出来的。
-
-标量与向量是**隐式继承**,不需要逐键选择加入。workspace 要消除的漂移正是"某个成员忘了
-选择加入",所以继承是默认行为,覆盖才是需要主动表达的动作。依赖保留显式选择加入,因为
-依赖是解析图上的一条**边**:隐式继承一条边,会在成员自己的 manifest 只字未提的情况下改变
-它解析到什么。
-
-**成员可以省略 `version`**,只要 `[workspace.package]` 提供了它。这个字段整体上仍是必需的
-—— 两边都没有时会被拒绝,并同时指出成员文件和本该提供它的 workspace 键。
-
-**并非所有键都可继承。** `[workspace.build] allow_host_libs` 会被拒绝:它关掉的是某个具体
-产物的 hermetic 链接检查,而 workspace 根若能设置一次,就等于替所有后来加入的成员也关掉了
-这项检查 —— 而那些成员的作者可能从没读过根 manifest。**描述"如何构建"的键可继承;描述
-"不要跑哪项安全检查"的键留在产物所属的那个包里。** `[workspace.package]` /
-`[workspace.build]` 中其他不认识的键同样会被拒绝而不是忽略:一个以"传播"为唯一目的的表,
-若能静默丢弃某个键,产出的就是"看起来配置好了、实际没有"的 workspace。
-
-**没有 `[workspace.target.<triple>]`。** workspace 根里一个普通的 `[target.<triple>]` 块
-本来就会按 triple 逐项被所有成员继承(成员优先)。为同一能力再加一种拼法,只会增加接口面
-而不增加功能。
+| 标量（`standard`、`version`、`license`、`c_standard`、`linkage` 等） | 成员**声明了该键**时成员胜出；否则取工作空间的值 |
+| 向量（`cxxflags`、`ldflags`、`defines`、`dialect_cxxflags`、`include_dirs` 等） | 追加，**工作空间在前**——因而成员自己的标志排在命令行更后面，后者胜出 |
+| `[workspace.dependencies]` | 逐依赖显式选择加入，`x.workspace = true`（§3） |
+
+"声明了"指的是这个键被写过，而不是它的值与默认值不同。成员在
+`[workspace.package] standard = 26` 之下刻意写 `standard = "c++23"`，得到的就是
+c++23；什么都不写的成员得到 c++26。这两种情况值相同而意图相反，所以这一点被
+记录下来，而不是靠推断。
+
+标量与向量都是**隐式继承**，不需要逐键选择加入。工作空间要消除的正是"某个成员
+忘了选择加入"这种漂移，所以继承是默认行为，覆盖才是需要主动写出的动作。依赖保留
+显式选择加入，因为依赖是解析图上的一条边：隐式继承一条边，会在成员自己的
+manifest 只字未提的情况下改变它解析到什么。
+
+**成员可以省略 `version`**，只要 `[workspace.package]` 提供了它。这个字段整体上
+仍是必需的——两边都没有时会被拒绝，同时指出成员文件和本该提供它的那个
+workspace 键。
+
+**并非所有键都可继承。** `[workspace.build] allow_host_libs` 会被拒绝：它关闭的
+是某个具体产物的 hermetic 链接检查，而工作空间根若能设置一次，就等于替所有后来
+加入、可能从未读过根 manifest 的成员一并关闭了这项检查。**描述"如何构建"的键可
+继承；描述"不跑哪项安全检查"的键留在产物所属的那个包里。** `[workspace.package]`
+与 `[workspace.build]` 里其他不认识的键同样会被拒绝而不是被忽略：一张以"传播"
+为唯一目的的表，如果能静默丢弃某个键，产出的就是一个看起来配置好了、实际上没有
+的工作空间。
+
+**没有 `[workspace.target.<triple>]`。** 工作空间根里一个普通的 `[target.<triple>]`
+块本来就按 triple 逐项被全体成员继承（成员优先）。为同一能力再造一种拼法，只会
+增加接口面而不增加功能。
 
 ### 4.2 整个模块图只有一个标准
 
-C++ 模块图有且只有一个标准:BMI 跨档位不兼容,因此根包的 `standard` 会施加到图中每一个包,
-依赖也不例外。依赖自己的 `standard` 不会被应用。
+C++ 模块图有且只有一个标准：BMI 跨档位不兼容，因此根包的 `standard` 施加于图中
+每一个包，依赖也不例外。依赖自己的 `standard` 不会被应用。
 
-有一类包是例外。供给 C++ 层的包(即标准库本身)陈述了 `standard` 时,它的每个既不提供也不导入
-模块的翻译单元恰好以该档位编译;它的模块单元仍按图的档位编译
-([22 —— 目标侧](22-target-side.md)「标准库自身的语言级别」)。没有 BMI 穿过这些单元,因此上面的
-规则没有被打破;正是这一点让 c++20 工程可以使用源码按 C++23 编写的标准库。
+有一类包是例外。供给 C++ 层（即标准库本身）的包陈述了 `standard` 时，它那些既
+不提供也不导入模块的翻译单元恰好按该档位编译；它的模块单元仍按图的档位编译
+（[22 —— 目标侧](22-target-side.md)「标准库自身的语言级别」）。没有 BMI 穿过这些
+单元，因此上面的规则并未被打破；正是这一点让一个 c++20 工程可以使用源码按 C++23
+编写的标准库。
 
-当依赖**声明**了高于当前图的档位时,mcpp 在编译前就报出来:
+当依赖**声明**了高于当前图的档位时，mcpp 在编译前就报出来：
 
 ```
 warning: dependency `render` declares standard = "c++26", and this graph is
@@ -243,52 +252,56 @@ warning: dependency `render` declares standard = "c++26", and this graph is
             standard = "c++26"
 ```
 
-这是 warning 而不是 error —— 这类构建通常仍然成功;`--strict` 会把它提升为错误。按上文被应用了声明的 C++ 层供给者不会被报出。它只对
-**工程作者自己拥有的 manifest** 生效(根包、workspace 成员、`path` 依赖):从索引解析来的
-包,其 `standard` 是描述符生成器写的,不是读到这条消息的人写的。
+这是 warning 而不是 error——这类构建通常仍会成功，`--strict` 会把它提升为
+错误。按上文被应用了声明的 C++ 层供给者不会被这样报出。它只对**工程作者自己拥有
+的 manifest** 生效（根包、workspace 成员、`path` 依赖）：从索引解析来的包，其
+`standard` 是由描述符生成器写的，而不是由读到这条消息的人写的。
 
 ## 5. 构建命令
 
-### 5.1 从工作空间根目录构建与测试
+### 5.1 从工作空间根构建与测试
 
 ```bash
-mcpp build                  # 虚拟工作空间 → 构建所有成员；带根包 → 构建根包
-mcpp build -p server        # 构建指定成员及其依赖
-mcpp build --workspace      # 显式构建每个成员
-mcpp test                   # 虚拟工作空间 → 测试所有成员；带根包 → 测试根包
-mcpp test  -p core          # 测试单个成员
-mcpp test  --workspace      # 测试每个成员（逐成员汇报；遇失败继续）
+mcpp build                  # virtual workspace → builds ALL members; rooted → the root package
+mcpp build -p server        # build a specific member and its dependencies
+mcpp build --workspace      # build every member explicitly
+mcpp test                   # virtual workspace → tests ALL members; rooted → the root package
+mcpp test  -p core          # test a single member
+mcpp test  --workspace      # test every member (one report per member; continues past failures)
 ```
 
-在**虚拟工作空间**根(只有 `[workspace]`、无 `[package]`)下,裸 `mcpp build` /
-`mcpp test` 作用于**所有**成员;在**带根包工作空间**(`[package]` + `[workspace]`)下作用于
-根包,用 `--workspace` 纳入全部成员。`mcpp test --workspace` 独立构建+运行每个成员的
-`tests/**/*.cpp`——测试发现按成员隔离,因此两个成员各有一个 `tests/main.cpp` 也不会冲突。
+在**虚拟**工作空间根（只有 `[workspace]`、没有 `[package]`）下，裸 `mcpp build` /
+`mcpp test` 作用于**全体**成员；在**带根包**的工作空间（`[package]` +
+`[workspace]`）下，两者作用于根包，用 `--workspace` 才纳入全体成员。
+`mcpp test --workspace` 独立构建并运行每个成员的 `tests/**/*.cpp`——发现按成员
+隔离，因此两个成员各有一个 `tests/main.cpp` 也不冲突。
 
 ### 5.2 从成员子目录构建
 
 ```bash
 cd libs/http
-mcpp build                  # 自动检测工作空间，构建当前成员
+mcpp build                  # auto-detects the workspace and builds the current member
 ```
 
-mcpp 从当前目录向上搜索，若发现包含 `[workspace]` 的 `mcpp.toml` 且当前目录在 `members` 列表中，则自动进入工作空间模式，继承工作空间配置。
+mcpp 从当前目录向上搜索；若发现某个 `mcpp.toml` 含 `[workspace]` 且当前目录在其
+`members` 列表中，则自动进入工作空间模式并继承工作空间配置。
 
 ### 5.3 `-p, --package` 选项
 
-`-p` 可用于 `build`、`test`、`run` 等命令，指定构建的目标成员。参数值为成员路径的最后一段目录名或完整相对路径：
+`-p` 可用于 `build`、`test`、`run` 等命令，指定目标成员。参数值可以是成员目录名
+的最后一段，也可以是完整相对路径：
 
 ```bash
-mcpp build -p server        # 匹配 apps/server
-mcpp test -p core           # 匹配 libs/core
+mcpp build -p server        # matches apps/server
+mcpp test -p core           # matches libs/core
 mcpp run -p server -- --port 8080
 ```
 
-`--workspace`(用于 `build` 和 `test`)是扇出形式:作用于**每个**成员。
-`mcpp test --workspace` 逐成员独立汇报、遇失败继续,只要有任一成员失败即非零退出——
-非常适合作为「一个测试众多库的工作空间」的单条、无 shell 的 CI 步骤。
+`--workspace`（用于 `build` 与 `test`）是扇出形式：作用于**每个**成员。
+`mcpp test --workspace` 逐成员分别汇报，遇失败继续，只要有任一成员失败就非零
+退出——很适合作为"一个测试众多库的工作空间"单条、无需 shell 的 CI 步骤。
 
-#### 扇出的汇报内容
+#### 扇出的汇报
 
 ```
    Workspace testing member 'libs/core' (3/97)
@@ -300,25 +313,26 @@ test_paths ... ok (0.31s)
     slowest: libs/jsc 93.5s, libs/install 32.2s, libs/http 24.1s
 ```
 
-`M/N` 进度、逐测试耗时,以及**按 build / run 拆开**的成员耗时。拆开才是有用的那部分:
-一个测试只要几毫秒、但链接要 90 秒的成员,在单个合并数字里和「测试套件很慢」长得一模一样,
-而两者里只有一个值得去查。
+`M/N` 进度、逐测试耗时，以及按 **build** 与 **run** 拆开的成员耗时。拆开才是有用
+的部分：一个测试只要几毫秒、但链接要 90 秒的成员，在单个合并数字里与"测试套件本身
+很慢"长得一模一样，而这两种情形只有一种值得去查。
 
-`--message-format json` 承载同样的数据。每条 test 记录都带 `"member"` 限定,流末尾是一条
-`workspace_summary`,列出失败成员与未运行成员 —— 一旦两个成员都有名为 `smoke` 的测试,
-裸测试名就不再可归因。
+`--message-format json` 以 NDJSON 承载同样的数据。每条 test 记录都带成员限定
+字段（`"member"`），流的末尾是一条 `workspace_summary` 记录，列出失败成员与未
+运行成员——一旦两个成员都有一个叫 `smoke` 的测试，裸测试名就不再能归因。
 
 #### 给扇出设期限
 
 ```bash
-mcpp test --workspace --timeout 60        # 单测试**运行**期限(默认 300)
-mcpp test --workspace --build-timeout 300 # 单次 ninja 驱动期限(默认 0 = 不限)
-mcpp test --workspace --workspace-timeout 1800   # 整条扇出(默认 0 = 不限)
+mcpp test --workspace --timeout 60        # per-test RUN deadline (default 300)
+mcpp test --workspace --build-timeout 300 # per-ninja-drive deadline (default 0 = no limit)
+mcpp test --workspace --workspace-timeout 1800   # whole fan-out (default 0 = no limit)
 ```
 
-扇出是串行的,所以一个没有上界的成员会拖住它后面的所有成员。三个期限都是**汇报而非中止**:
-测试超时只判该测试失败、扇出继续;构建超时只判该成员失败;`--workspace-timeout` 停止扇出并
-列出未运行的成员 —— 而不是把进程留给 CI 去 kill(那会把它想说的话一并丢掉)。
+扇出是串行的，所以一个没有上界的成员会拖住排在它后面的每一个成员。三个期限都是
+**汇报而非中止**：测试超时只判该测试失败，扇出继续；构建超时只判该成员失败；
+`--workspace-timeout` 停止扇出并列出未运行的成员，而不是把进程留给 CI 去 kill——
+那样会把进程本该说出的话一并丢掉。
 
 ## 6. 目录布局
 
@@ -326,7 +340,7 @@ mcpp test --workspace --workspace-timeout 1800   # 整条扇出(默认 0 = 不
 
 ```
 myproject/
-├── mcpp.toml               # [workspace] 声明
+├── mcpp.toml               # [workspace] declaration
 ├── libs/
 │   ├── core/
 │   │   ├── mcpp.toml       # [package] namespace="myproject" name="core"
@@ -343,22 +357,24 @@ myproject/
             └── main.cpp    # import myproject.http;
 ```
 
-各成员的构建产物位于各自的 `target/` 子目录下。
+各成员的构建产物存在各自的 `target/` 子目录下。
 
-工作空间之外的项目以 member 的身份引用托管在 git 上的工作空间中的 member:
-`myproject.http = { git = "...", rev = "..." }` 在根清单的 `members` 中选中 `libs/http`,
-提交相同,且该 member 与在此处一样继承 `[workspace.package]`(mcpp 2026.9.16.1+;见
-[05 —— 依赖](05-dependencies.md))。
+工作空间之外的工程，以成员身份引用托管在 git 上的工作空间中的一个成员：
+`myproject.http = { git = "...", rev = "..." }` 会在根 manifest 的 `members`
+中选中 `libs/http`，取同一个提交，而该成员会像在工作空间内部一样继承
+`[workspace.package]`（mcpp 2026.9.16.1+；见 [05 —— 依赖](05-dependencies.md)）。
 
 ## 7. 与 C++ 模块的关系
 
 工作空间与 C++23 模块机制协同工作：
 
-- **接口可见性由语言控制** — `export module` 和 `import` 语句决定模块的公开接口，工作空间不做额外的可见性限制
-- **模块名由库作者决定** — 工作空间不强制模块名与包名或命名空间一致
-- **partition 用于内部组织** — `import :internal;`（不带 `export`）的 partition 对消费者不可见，无需构建工具介入
+- **接口可见性由语言控制**——`export module` 与 `import` 语句决定一个模块的
+  公开接口，工作空间不施加额外的可见性限制。
+- **模块名由库作者决定**——工作空间不要求模块名与包名或命名空间一致。
+- **partition 用于内部组织**——通过 `import :internal;`（不带 `export`）导入
+  的 partition 对消费者不可见，不需要构建工具介入。
 
 ## 8. 完整示例
 
-参见 [`examples/04-workspace/`](../../examples/04-workspace/)，包含一个三成员工作空间的完整可运行示例。
-
+见 [`examples/04-workspace/`](../../examples/04-workspace/)，一个三成员工作空间
+的完整可运行示例。
diff --git a/docs/zh/08-testing.md b/docs/zh/08-testing.md
index 9070d0277..9ce4b0c1a 100644
--- a/docs/zh/08-testing.md
+++ b/docs/zh/08-testing.md
@@ -1,79 +1,80 @@
 # 08 —— 测试
 
-**读者:**任何有代码需要持续可用的人。
+**读者：** 任何拥有「必须持续可用」的代码的人。
 
-**本章回答的那一个问题:**测试怎么写、怎么跑,mcpp 认为什么是一个测试,以及
-在本机跑不了的东西怎么测。
+**本章回答的那一个问题：** 测试怎么写、怎么跑，mcpp 把什么算作一个测试，以及
+在本机跑不了的东西如何测试。
 
-**不在这里:**runner 怎么抵达一台设备 —— 那是
-[41 —— 抵达一台设备](41-devices.md);以及机器可读流的 schema,那是
-[50 —— 机器可读输出](50-machine-output.md)。本章只说明哪个旗标产生它,到此为止。
+**不在这里：** runner 如何抵达一台设备 —— 那是
+[41 —— 抵达一台设备](41-devices.md)；机器可读流的 schema 是
+[50 —— 机器可读输出](50-machine-output.md)。本章只说明哪个旗标产生它，到此为止。
 
-在此之前:[05 —— 依赖与解析](05-dependencies.md) 覆盖 `[dev-dependencies]`,
-那是测试如何取到产物取不到的包。在此之后:
+在此之前：[05 —— 依赖与解析](05-dependencies.md) 覆盖 `[dev-dependencies]`，
+那是测试用来取到产物取不到的包的手段。在此之后：
 [09 —— 按场景选命令](09-commands-by-scenario.md) 是其余一切的查阅入口。
 
 ## 测试的定义
 
-每一个 `tests/**/*.cpp` 都是一个测试:mcpp 把每个文件编译成它自己的程序并运行它。
-测试通过的判据是它的程序以 0 退出。
+每一个 `tests/**/*.cpp` 都是一个测试：mcpp 把每个文件编译成它自己的程序并运行。
+测试通过的判据是该程序以 0 退出。
 
 ```
 myproject/
   mcpp.toml
   src/…
   tests/
-    test_parse.cpp        一个程序
-    unit/test_span.cpp    另一个
+    test_parse.cpp        one program
+    unit/test_span.cpp    another
 ```
 
-没有框架,也不需要注册。测试**可以**用一个框架 —— `[dev-dependencies]` 是它取到
-框架的方式 —— 但 mcpp 持有的契约是退出码,这也是为什么为别的框架写的测试不需要
-适配层。
+没有框架，也不需要注册。测试可以使用一个框架 —— `[dev-dependencies]` 是取到框架的
+途径 —— 但 mcpp 持有的契约只是退出码，这也是为什么为其他框架写的测试不需要适配层。
 
-`mcpp new` 会生成 `tests/test_smoke.cpp`,让工程一开始就有这个目录。
+`mcpp new` 生成 `tests/test_smoke.cpp`，使工程从一开始就带有这个目录。
 
 ### 测试的位置
 
-`tests/**/*.cpp` 是一个键的默认值:
+`tests/**/*.cpp` 是一个键的默认值：
 
 ```toml
 [test]
 discover = ["checks/**/*.cpp", "!checks/fixtures/**"]
 ```
 
-`discover` 接受与 `[build] sources` 同一套词汇的 glob:glob 匹配到的每个文件都是一个
-测试程序,以 `!` 开头的 glob 把它匹配到的文件从集合中去掉,无论是哪个 glob 找到的。
-测试的名字是它相对于第一个匹配它的 glob 的固定目录的路径,去掉扩展名,因此默认值
-把 `tests/unit/test_span.cpp` 命名为 `unit/test_span`。`discover = []` 不发现任何测试。
-名字相同的两个文件会被拒绝,并点名两者。
+`discover` 接受与 `[build] sources` 同一套词汇的 glob：某个 glob 匹配到的每个文件
+都是一个测试程序，以 `!` 开头的 glob 把它匹配到的文件从集合中剔除，无论这些文件是
+被哪个 glob 找到的。一个测试的名字，是它相对于第一个匹配它的 glob 所在固定目录的
+路径，去掉扩展名 —— 因此默认配置下 `tests/unit/test_span.cpp` 的名字是
+`unit/test_span`。`discover = []` 不发现任何测试。两个名字相同的文件会被拒绝，并
+点出这两者。
 
-由多个源文件编译成的测试套件是一个独立的包:一个工作区成员,它的 `[build] sources`
-承载套件,它唯一的测试程序驱动套件,用 `mcpp test -p <member>` 选中。
+由多个源文件编译而成的测试套件本身是一个独立的包：一个工作区成员，它的
+`[build] sources` 承载整套套件，其唯一的测试程序驱动套件，用
+`mcpp test -p <member>` 选中。
 
-## 运行它们
+## 运行测试
 
 ```bash
-mcpp test                 # 构建并运行每个测试
-mcpp test parse           # 只运行名字匹配的那些
-mcpp test --list          # 列出会跑哪些,不构建也不运行
-mcpp test -- --verbose    # `--` 之后的一切传给每个测试程序
+mcpp test                 # build and run every test
+mcpp test parse           # only those whose name matches
+mcpp test --list          # what would run, without building or running it
+mcpp test -- --verbose    # everything after `--` goes to each test binary
 ```
 
-测试的构建轴与 `mcpp build` 相同,因此测试跑在它要检查的那个配置上,而不是默认
-配置上:
+测试的构建轴与 `mcpp build` 相同，因此测试跑在它要检查的那个配置上，而不是默认
+配置上：
 
 | 旗标 | 选中的集合 |
 |---|---|
-| `--profile <name>` | `dev`(默认)、`release`、`dist`,或 manifest 声明的某个 `[profile.*]` |
-| `--features <list>` | 这次测试构建的 feature 集合 |
+| `--profile <name>` | `dev`（默认）、`release`、`dist`，或 manifest 声明的某个 `[profile.*]` |
+| `--features <list>` | 本次测试构建的 feature 集合 |
 | `--target <triple>` | 宿主以外的目标 |
 | `--accel <spec>` / `--no-accel` | 本次构建面向的设备后端 |
 | `--cap <list>` | 钉住某个能力的 provider |
-| `--toolchain <spec>` | 本次调用使用的工具链,例如 `llvm@22.1.8` |
+| `--toolchain <spec>` | 本次调用使用的工具链，例如 `llvm@22.1.8` |
 
-`--timeout <secs>` 杀掉仍在运行的测试(默认 300;`0` 关闭),`--build-timeout <secs>`
-限制编译。一个挂住的测试被报为**以它自己的名字失败**,而不是一个停下来的任务。
+`--timeout <secs>` 杀掉仍在运行的测试（默认 300；`0` 关闭），`--build-timeout <secs>`
+限制编译耗时。挂起的测试以它自己的名字被报为失败，而不是报成一个停止的任务。
 
 ## 取到产物取不到的包的测试
 
@@ -82,57 +83,58 @@ mcpp test -- --verbose    # `--` 之后的一切传给每个测试程序
 counters = { path = "../counters" }
 ```
 
-`[dev-dependencies]` 的条目只为测试构建解析,别处一概不用:它不在产物里,包的
-消费者也永远看不见它。这就是「测试的依赖」与「包自己的依赖」之间的区别,也是
-测试框架不会变成一个库所发布内容的一部分的原因。
+`[dev-dependencies]` 的条目只为测试构建解析，别处一律不用：它不在产物里，包的消费者
+也永远看不到它。这就是「测试的依赖」与「包自己的依赖」之间的区别，也是测试框架不会
+成为一个库所发布内容之一部分的原因。
 
-[`examples/11-features`](../../examples/11-features/) 声明了一个并使用它。
+[`examples/11-features`](../../examples/11-features/) 声明了一个这样的依赖并使用它。
 
 ## 在本机跑不了的目标上测试
 
-面向交叉目标或裸机板子的测试,会被编译到那个目标,并经由一个 **runner** 执行 ——
-runner 是板级支持包提供的一串 argv,mcpp 把测试二进制附加在其后执行它。
+面向交叉目标或裸机板子的测试被编译到那个目标，并经由一个 **runner** 执行 ——
+runner 是板级支持包提供的一串 argv，mcpp 把测试二进制附加在其后交给它执行。
 
 ```bash
-mcpp test --target thumbv7em-none-eabihf     # 为板子构建,经它的 runner 运行
-mcpp test --no-runner                        # 忽略 runner,直接执行
-mcpp test --target aarch64-macos --no-run    # 只为目标构建测试,不执行
+mcpp test --target thumbv7em-none-eabihf     # built for the board, run through its runner
+mcpp test --no-runner                        # ignore the runner and execute directly
+mcpp test --target aarch64-macos --no-run    # build the tests for the target and stop
 ```
 
-测试本身一个字都不用改。同样的 `tests/**/*.cpp` 为设备编译,判据仍然是退出码 ——
-这正是裸机 runner 被选成「能产生 semihosting 退出码或 QEMU 退出码」的原因。
+测试本身没有任何改变。同样的 `tests/**/*.cpp` 为设备编译，判据仍然是退出码 ——
+这正是裸机 runner 被选来产生 semihosting 退出码或 QEMU 退出码的原因。
 
-`--no-runner` 是给「本机就能原生执行这些二进制、不该为模拟器付代价」的宿主准备的。
+`--no-runner` 是为「本机能原生执行这些二进制、不该为模拟器付代价」的宿主准备的。
 
-`--no-run` 做的是更窄的那个断言,而它必须被显式要求。没有它时,一个本机既不能执行、
-也没有 runner 可达的目标,会让每个测试都停在 not run,命令退出 2:mcpp 没有查明这些
-测试是否通过,而把它报成成功是本仓记录得最多的一种假读数。但 2 同样是 runner 坏掉时
-的退出码,于是一个只想要「构建」的调用方无法区分这两者。在 `--no-run` 下,每个被选中
-的测试都为该目标编译并链接,没有任何一个被执行,结果也这么写:
+`--no-run` 做出的是更窄的断言，且必须显式要求。不给它时，一个本机既无法执行、也没有
+runner 可达的目标，会让每个测试都停在「未运行」，命令退出 2：mcpp 没有查明这些测试
+是否通过，把这种情况报成成功，是本仓记录得最多的一种假读数。但 2 同样是 runner
+坏掉时的退出码，于是一个只想要「构建」结果的调用方无法区分这两种情况。在 `--no-run`
+下，每个被选中的测试都为目标编译并链接，没有一个被执行，结果也如实写出：
 
 ```
 test result ok. 0 passed; 0 failed; 2 built, not run
 ```
 
-编译不过的测试仍然是失败;`--no-run` 与 `--no-runner` 同时给出会被拒绝,而不是在两者
-之间挑一个:一个说的是「不经声明的 runner 直接执行」,另一个说的是「不要执行」。
+编译不过的测试仍然是失败。`--no-run` 与 `--no-runner` 同时给出会被拒绝，而不是在
+两者间择一执行：一个说的是「不经声明的 runner 直接执行二进制」，另一个说的是
+「不要执行」。
 
-测试程序把它读取的文件带在身边:runner 收到 `MCPP_RUNTIME_FILES`,即它部署的文件与
-它加载的共享库的清单,把程序移到设备上的 runner 连同这些文件一起复制。测试按相对于
-自身所在目录的路径定位这类文件。在 Android 行上,除非 `cxx_runtime` 另有声明,测试
-程序静态链接 C++ 运行时,因此设备上不需要 `libc++_shared.so`。
+测试程序把它读取的文件带在身边：runner 收到 `MCPP_RUNTIME_FILES`，即它已部署的文件
+与它加载的共享库的清单，把程序移动到设备上的 runner 会把这些文件一并复制过去。测试
+按相对于自身所在目录的路径定位这类文件。在 Android 的各行上，除非 `cxx_runtime`
+另有声明，测试程序静态链接 C++ 运行时，因此设备上不需要 `libc++_shared.so`。
 
-runner 本身、具名 runner,以及一块板子声明什么,见
+runner 本身、具名 runner，以及一块板子声明了什么，见
 [41 —— 抵达一台设备](41-devices.md)。
 
 ## 不能彼此并排运行的测试
 
-`mcpp test` 在一个工作池上运行测试程序。一块板子接一个探针、一块 GPU、一个串口,
-或者一份单座许可证,同一时刻只容一个使用者;两个 worker 同时去拿的结果是交错,
+`mcpp test` 在一个工作池上运行测试程序。一块接了一个探针的板子、一块 GPU、一个串口，
+或者一份单座许可证，同一时刻只容一个使用者；两个 worker 同时去争抢它的结果是交错，
 而不是干净地失败。
 
-拥有该资源的那个包**自己声明**这一点,`mcpp test` 随后把这些测试串行化。工程方
-永远不需要记得加 `-j1`。
+拥有该资源的包对此做出声明，`mcpp test` 随后把这些测试串行化。工程方永远不需要
+记得加上 `-j1`。
 
 ## 报告给程序
 
@@ -140,16 +142,17 @@ runner 本身、具名 runner,以及一块板子声明什么,见
 mcpp test --message-format json
 ```
 
-每个测试一条 NDJSON 记录,供 CI 任务或编辑器消费。schema 及其版本见
-[50 —— 机器可读输出](50-machine-output.md);属于本章的只有「这个旗标存在」以及
-「人类可读格式是默认」。
+每个测试一条 NDJSON 记录，供 CI 任务或编辑器使用。schema 及其版本见
+[50 —— 机器可读输出](50-machine-output.md)；本章只交代这个旗标存在，以及人类可读
+格式是默认值。
 
 ## 当前边界
 
-- 一个测试是一个 `.cpp` 产出一个程序。mcpp 不发现文件内部的用例,因此框架的
-  逐用例选择发生在程序内部,经由 `--` 之后的参数。
-- 清单无法加载时,`mcpp test --list` 列出的是 `tests/**/*.cpp`,而不是它读不到的
+- 一个测试是一个 `.cpp` 产出一个程序。mcpp 不发现文件内部的用例，因此框架的逐用例
+  选择发生在程序内部，经由 `--` 之后的参数传递。
+- manifest 加载不了时，`mcpp test --list` 列出的是 `tests/**/*.cpp`，而不是它读不到的
   `[test] discover` 集合。
 - `--build-timeout` 只在 POSIX 上有效。
-- `--workspace-timeout` 限制 `--workspace` 的扇出并报告跑到了哪些;它不把超时
-  归因到某个成员。
+- `--workspace-timeout` 限制 `--workspace` 扇出的耗时，并报告哪些成员跑完了；它不把
+  超时归因到某一个成员。
+</content>
diff --git a/docs/zh/09-commands-by-scenario.md b/docs/zh/09-commands-by-scenario.md
index 8a7cc9cb7..d94d1d83c 100644
--- a/docs/zh/09-commands-by-scenario.md
+++ b/docs/zh/09-commands-by-scenario.md
@@ -1,35 +1,37 @@
 # 09 —— 按场景选命令
 
-**读者:**已经认识那些名词、现在想找动词的人。
+**读者：** 已经认识那些名词、现在想找动词的人。
 
-**本章回答的那一个问题:**手上这件事该用哪个命令 —— 回收磁盘、解释一次解析、
-校验一个描述符、诊断环境。
+**本章回答的那一个问题：** 手上这件事该用哪条命令 —— 回收磁盘、解释一次
+解析、校验一个描述符、诊断环境。
 
-**不在这里:**每个命令的含义细节。一个场景点名命令,并链接到拥有它的那一章。
-在此之前:[08 —— 测试](08-testing.md)。
+**不在这里：** 每条命令含义上的细节。一个场景点名命令，并链接到拥有它的
+那一章。在此之前：[08 —— 测试](08-testing.md)。
 
-命令清单是 `mcpp --help`,每个子命令还有自己的 `--help`。本章回答的是另一个问题:
-某个情形已经发生时该用哪条命令 —— 构建目录一直变大、解析结果出乎意料、描述符即将
-发布、索引可能陈旧。这里收的都是名字本身没有说出它所属场景的命令。
+命令清单是 `mcpp --help`，每个子命令还带自己的 `--help`。本章回答的是另一个
+问题：某个情形已经发生时该用哪条命令 —— 构建目录一直在变大、一次解析结果
+出乎意料、一个描述符即将发布、一份索引可能已经陈旧。这里收的都是名字本身
+没有说出它所属场景的命令。
 
-相关文档:[01 — 快速开始](01-getting-started.md)(日常构建与测试循环)、
-[20 — 工具链管理](20-toolchains.md)、
-[11 — 发布库到 mcpp-index](11-publishing-a-library.md)、
-[50 — 机器可读输出](50-machine-output.md)。
+相关文档：[01 —— 快速开始](01-getting-started.md)（日常构建与测试循环）、
+[20 —— 工具链管理](20-toolchains.md)、
+[11 —— 发布一个库](11-publishing-a-library.md)、
+[50 —— 机器可读输出](50-machine-output.md)。
 
-下面每段输出都由本章所在版本的 mcpp 实际产生。
+下面每一段输出，都由本章所对应版本的 mcpp 实际产生。
 
 ## 回收磁盘而不触发重编
 
-有两个存储会增长,增长的原因不同,各由一条命令清空。把两者弄混的代价是一次全量重编。
+有两个存储会增长，增长的原因不同，各由一条命令清空。把两者弄混，代价是一次
+全量重编。
 
 | 存储 | 作用域 | 增长时机 | 清空方式 |
 |---|---|---|---|
-| `target/<三元组>/<指纹>/` | 单个工程 | 配置指纹变化,开出新目录 | `mcpp clean`、`mcpp clean --stale` |
-| 构建缓存(`mcpp cache dir`) | 整台机器 | 任何工程编译依赖、`std` 模块,或构建一个 host 工具 | `mcpp cache gc`、`mcpp cache prune`、`mcpp cache clean` |
+| `target/<三元组>/<指纹>/` | 单个工程 | 一个配置指纹变化，开出一个新目录 | `mcpp clean`、`mcpp clean --stale` |
+| 构建缓存（`mcpp cache dir`） | 整台机器 | 任何工程编译一个依赖、一个 `std` 模块，或构建一个 host 工具 | `mcpp cache gc`、`mcpp cache prune`、`mcpp cache clean` |
 
-`mcpp clean` 整个删掉 `target/`,下次构建重编一切。`mcpp clean --stale` 只删已无构建
-记录使用的指纹目录,在用的配置保留:
+`mcpp clean` 整个删掉 `target/`，下次构建重编一切。`mcpp clean --stale`
+只删已无构建记录使用的指纹目录，在用的配置保留：
 
 ```
 $ mcpp clean --stale --dry-run
@@ -37,22 +39,25 @@ would remove target/x86_64-linux-gnu/0123456789abcdef  (0.0 B)
 Would remove 1 directory (0.0 B)
 ```
 
-「在用」指被 `target/.build_cache` 记录 —— 它由 `mcpp build` 写入,由快路径读取。
-这个定义带来三个后果:
+"在用"指被 `target/.build_cache` 记录 —— 它由 `mcpp build` 写入，由快
+路径读取。这个定义带来三个推论：
 
-- 没有记录并不足以让一个目录被删。`mcpp test` 走的构建路径不写记录,`--no-cache`
-  构建同样不写。未被记录但在 `--older-than`(默认一天)之内写过的目录保留;更旧的
-  会被删,而判断错误的代价是重编一个此后无人碰过的配置。
-- 完全没有记录时,命令拒绝执行而不是猜测。跑一次 `mcpp build` 即可确立什么是当前的。
-- `target/` 下不是指纹目录的东西 —— 例如 `mcpp pack` 的 `dist/` —— 从不被访问。
+- 一个没有记录的目录，不会仅因此就被删除。`mcpp test` 走的构建路径不写
+  记录，`--no-cache` 构建同样不写。未被记录、但写在 `--older-than`（默认
+  一天）之内的目录会被保留；更旧的会被删，判断出错的代价是重编一个此后
+  无人碰过的配置。
+- 完全没有记录时，命令拒绝执行，而不是去猜。跑一次 `mcpp build` 就能确立
+  什么是当前的。
+- `target/` 下不是指纹目录的东西 —— 例如 `mcpp pack` 的 `dist/` —— 从不
+  被访问。
 
-`--dry-run` 只列出,不删除。`--stale`、`--dry-run`、`--older-than` 三者任一都选中这一
-档:`mcpp clean --older-than 3d` 是一次有范围的请求,不会被读成整删。`--older-than 0`
-不保留任何未记录目录;负的时长被拒绝。
+`--dry-run` 只列出，不删除。`--stale`、`--dry-run`、`--older-than` 三者
+任一都选中这一档：`mcpp clean --older-than 3d` 是一次有范围的请求，不会被
+读成一次整删。`--older-than 0` 不保留任何未记录的目录；负的时长被拒绝。
 
-构建缓存是全机共享的,所以工程级命令不得清空它 —— `--stale` 与 `--bmi-cache` 不能同时
-给出。`mcpp cache list` 列出占用。行没有排序,而 `0.0 B  (incomplete)` 那样的行,是被
-中断的构建留下的条目:
+构建缓存是全机共享的，因此工程级命令不得清空它 —— `--stale` 与
+`--bmi-cache` 不能同时给出。`mcpp cache list` 列出占用。行没有排序，而像
+`0.0 B  (incomplete)` 那样的行，是被中断的构建留下的条目：
 
 ```
 $ mcpp cache list
@@ -61,14 +66,15 @@ key               kind          size       last used  package
 9234eed9ef786c13  std          0.0 B          2d ago  std  (incomplete)
 ```
 
-`mcpp cache gc` 要求给出 `--max-size`、`--older-than` 或两者,并且只驱逐包条目。一份
-`std` BMI 被机器上每个工程共享,实现以「重建它是用大量时间换少量磁盘」为由把它排除在
-按体积驱逐之外。`mcpp cache clean --std` 仍是显式移除它的做法。
+`mcpp cache gc` 要求给出 `--max-size`、`--older-than` 或两者，并且只驱逐
+包条目。一份 `std` BMI 被机器上每个工程共享，实现以"重建它是用大量时间
+换少量磁盘"为由，把它排除在按体积驱逐之外。`mcpp cache clean --std` 仍是
+显式移除它的做法。
 
 ## 一个包已发布的版本
 
-`mcpp search` 按子串匹配,并在每个命中行后附上该包发布的版本 —— 跨描述符的 per-OS 表
-合并,按 semver 降序:
+`mcpp search` 按子串匹配，并在每个命中行后附上该包发布的版本 —— 跨描述符
+的 per-OS 表合并，按 semver 降序：
 
 ```
 $ mcpp search imgui
@@ -76,24 +82,25 @@ $ mcpp search imgui
   mcpplibs:imgui        C++23 module package for Dear ImGui core and GLFW/OpenGL3 backends  (0.0.6, 0.0.5, 0.0.4, ...)
 ```
 
-末尾的 `, ...` 表示被截断:默认显示三个,没有这个标记就说明列表是完整的。
-`--all-versions` 打印全部。描述符读不到的包按两列输出 —— 版本列表是尽力而为的展示,
-不会让 search 失败。
+末尾的 `, ...` 标记截断：默认显示三个版本，没有这个标记就说明列表是完整的。
+`--all-versions` 打印全部。一个描述符读不到的包，按两列输出 —— 版本列表是
+尽力而为的展示，从不会让 search 失败。
 
-`mcpp add` 在名字解析不到时携带同样的信息。建议里给出该写的命名空间,以及它背后的版本:
+`mcpp add` 在一个名字解析不到时，携带同样的信息。建议里给出该写的命名
+空间，以及它背后的版本：
 
 ```
   a package with this name exists under another namespace:
     compat.eui-neo (0.5.6, 0.5.5, 0.5.3)
 ```
 
-这次扫描只在查找已经失败之后进行,结果只进入错误文本与 search 输出。裸名不会因此跨
-命名空间解析。
+这次扫描只在查找已经失败之后进行，结果只进入错误文本与 search 输出。裸名
+不会因此跨命名空间解析。
 
 ## 为一次调用换一个工具链
 
-`mcpp build`、`mcpp run`、`mcpp test` 与 `mcpp pack` 接受 `--toolchain <spec>`,
-它为这一次调用选择编译器,不写入任何东西:
+`mcpp build`、`mcpp run`、`mcpp test` 与 `mcpp pack` 接受
+`--toolchain <spec>`，它为这一次调用选择编译器，不写入任何东西：
 
 ```bash
 mcpp test --toolchain llvm@22.1.8
@@ -101,13 +108,14 @@ mcpp run --toolchain gcc@16.1.0
 mcpp pack --toolchain llvm@22.1.8 --format dir
 ```
 
-对这一次调用,这个选项取代 `mcpp.toml` 中的 `[toolchain] default`,其优先级即
-[20 —— 工具链管理](20-toolchains.md) 给 `MCPP_TOOLCHAIN` 的那一级。每个工具链构建到
-它自己的输出目录,一次记录下来的构建只为记录它的那个工具链请求重放。
+对这一次调用，这个选项取代 `mcpp.toml` 中的 `[toolchain] default`，优先级
+与 [20 —— 工具链管理](20-toolchains.md) 给 `MCPP_TOOLCHAIN` 的那一级相同。
+每个工具链构建到它自己的输出目录，一次记录下来的构建只为记录它的那个工具链
+请求重放。
 
 ## 解释一次解析
 
-`mcpp why` 报告一次构建会解析出什么,并且不构建任何东西:
+`mcpp why` 报告一次构建会解析出什么，并且不构建任何东西：
 
 ```
 $ mcpp why toolchain
@@ -116,9 +124,9 @@ toolchain: gcc 16.1.0 (x86_64-linux-gnu)
   reason: [toolchain] in mcpp.toml if set, else platform-native default
 ```
 
-`mcpp why deps` 在 `mcpp.lock` 的各行之前列出解析出的依赖图(2026.9.14.2+):每个包、
-每条请求书写时用的键与所在的表,以及库的链接形态与其原因。锁文件不记录的 `path`
-依赖同样列出:
+`mcpp why deps` 在 `mcpp.lock` 各行之前列出解析出的依赖图（2026.9.14.2+）:
+每个包、每条请求书写时用的键与所在的表，以及库的链接形态与其原因。锁文件
+不记录的 `path` 依赖同样列出：
 
 ```
 $ mcpp why deps
@@ -130,14 +138,16 @@ dependency graph:
       linked static (default)
 ```
 
-同一张图记录在 `target/<triple>/<fp>/resolution.json` 的 `graph` 下,每个包一条,
-根在最前:`package`(规范身份、命名空间、名字、版本、来源)、`root`、
-`requested_by`(`requester`、`key`、`table`),库还有 `link`(`form`、`reason`)。
+同一张图记录在 `target/<triple>/<fp>/resolution.json` 的 `graph` 下，
+每个包一条，根在最前：`package`（规范身份、命名空间、名字、版本、来源）、
+`root`、`requested_by`(`requester`、`key`、`table`)，对库还有 `link`
+(`form`、`reason`)。
 
-话题是 `toolchain`、`runtime`、`deps` 或 `runners`,不给话题时四者全报。`--target` 与
-`--toolchain` 把报告变成对当前目录并不使用的那一对的查询,目标矩阵正是这样逐格提问的。
+话题是 `toolchain`、`runtime`、`deps` 或 `runners`，不给话题时四者全报。
+`--target` 与 `--toolchain` 把报告变成对当前目录并不使用的那一对的查询，
+一个目标矩阵正是这样逐格提问的。
 
-诊断里的错误码可以用 `mcpp self explain` 展开:
+诊断里的一个错误码，可以用 `mcpp self explain` 展开：
 
 ```
 $ mcpp self explain E0006
@@ -150,7 +160,7 @@ silently misbehave, so resolution stops instead. Upgrade mcpp:
 
 ## 索引新鲜度与离线构建
 
-`mcpp index status` 在不碰网络的前提下回答本地索引副本是否当前:
+`mcpp index status` 在不碰网络的前提下，回答本地索引副本是否当前：
 
 ```
 $ mcpp index status
@@ -159,17 +169,19 @@ $ mcpp index status
   mcpplibs   fresh    28s ago      d4b36d7      /home/speak/.mcpp/registry/data/mcpplibs
 ```
 
-`mcpp index update` 刷新它们。一个刚发布几分钟、刷新后仍然找不到的包,是传播问题而不是
-名字问题 —— 索引以 artifact 而非 git clone 的形式到达客户端。
+`mcpp index update` 刷新它们。一个刚发布几分钟、刷新后仍然找不到的包，
+是传播问题而不是命名问题 —— 索引以 artifact 而非 git clone 的形式到达
+客户端。
 
-`--offline`(或 `MCPP_OFFLINE=1`)在单次调用中禁止网络,宁可失败也不拉取。`--locked` 在
-解析结果与 `mcpp.lock` 不一致时失败而不是改写它,这正是 CI 作业需要的形状。
-`mcpp index pin <name> <rev>` 把自定义索引的某个 commit 记进 `mcpp.toml`;
-`mcpp index unpin` 移除它。
+`--offline`（或 `MCPP_OFFLINE=1`）在单次调用中禁止网络，宁可失败也不拉取。
+`--locked` 在解析结果与 `mcpp.lock` 不一致时失败，而不是改写它，这正是 CI
+作业需要的形状。`mcpp index pin <name> <rev>` 把一个自定义索引的某个
+commit 记进 `mcpp.toml`;`mcpp index unpin` 移除它。
 
 ## 发布前校验描述符
 
-`mcpp xpkg parse` 用解析器自己的文法读描述符,所以它报告的就是解析时会看到的:
+`mcpp xpkg parse` 用解析器自己的文法读一个描述符，所以它报告的就是解析时
+会看到的：
 
 ```
 $ mcpp xpkg parse mcpp.plugins.lua
@@ -181,9 +193,9 @@ form       A — no mcpp segment (build info from the source's mcpp.toml)
 parse OK
 ```
 
-per-OS 列表分开打印是有意的:一个版本只加进了某一个平台表而在其余表里被遗漏,在缺它的
-平台上读起来就是「找不到」,而文件里明明含有这个版本字符串。`--json` 以同样的事实供脚本
-使用:
+per-OS 列表分开打印是有意的：一个版本只加进了某一个平台表、在其余表里被
+遗漏，在缺它的平台上读起来就是"找不到"，而文件里明明含有这个版本字符串。
+`--json` 以同样的事实供脚本使用：
 
 ```
 $ mcpp xpkg parse mcpp.plugins.lua --json
@@ -191,12 +203,12 @@ $ mcpp xpkg parse mcpp.plugins.lua --json
 ```
 
 `mcpp emit xpkg` 生成要提交的条目。完整路径见
-[11 — 发布库到 mcpp-index](11-publishing-a-library.md)。
+[11 —— 发布一个库](11-publishing-a-library.md)。
 
 ## 环境诊断
 
-`mcpp self doctor` 检查工具链、`std` 模块、registry、缓存健康与最近一次运行期闭包判定,
-并报告它查到了什么,而不只报告失败的部分:
+`mcpp self doctor` 检查工具链、`std` 模块、registry、缓存健康与最近一次
+运行期闭包判定，并报告它查到了什么，而不只报告失败的部分：
 
 ```
 $ mcpp self doctor
@@ -207,19 +219,20 @@ $ mcpp self doctor
 warning: pre-v1 cache at '/home/speak/.mcpp/bmi' occupies 167.5 MiB and is no longer used — `mcpp cache clean --legacy` reclaims it
 ```
 
-`mcpp self env` 打印路径与已解析的工具链,含 `--format json`。
-`mcpp self config --mirror CN|GLOBAL` 选择下载镜像;mcpp 与 xlings 各自持有这个设置,
-为其中一个选定不会为另一个选定。
+`mcpp self env` 打印路径与已解析的工具链，包括 `--format json`。
+`mcpp self config --mirror CN|GLOBAL` 选择下载镜像；mcpp 与 xlings 各自
+持有这个设置，为其中一个选定，不会为另一个选定。
 
-## `[hooks]` —— 项目构建生命周期命令(实验性)
+## `[hooks]` —— 项目构建生命周期命令（实验性）
 
-> **实验性。** Hook 目前**不能**决定一次构建成功与否。所有 Hook 失败都以
-> **warning** 报出,`mcpp build` 保留它自己挣来的结果;`side_effect = true`
-> 会被报错拒绝,而不是被采纳。这个键保留在 schema 里,这样今天写下的 manifest
-> 在该功能转正时无需改动。另有两条限制是永久的、不是临时的:**只有根项目的 Hook
-> 会执行**,而且**只有 `mcpp build` 会执行它们**。
+> **实验性。** Hook 目前**不能**决定一次构建是否成功。每一次 Hook 失败
+> 都以 **warning** 报出，`mcpp build` 保留它自己挣来的结果；
+> `side_effect = true` 会被报错拒绝，而不是被采纳。这个键留在 schema 里，
+> 这样今天写下的 manifest，在该功能转正时不必改动。另有两条限制是永久的，
+> 不是临时的：**只有根项目的 Hook 会执行**，而且**只有 `mcpp build`
+> 会执行它们**。
 
-Hook 是 `mcpp build` **在一段区间内持有**的命令,事件名就是那段区间:
+Hook 是 `mcpp build` **在一段区间内持有**的命令，事件名就是那段区间：
 
 ```toml
 [hooks]
@@ -227,107 +240,119 @@ build_start = "echo build started"
 build_failed = "notify-send 'build failed'"
 build_finished = "notify-send 'build finished'"
 
-# 可选;以下是默认值。
+# Optional; these are the defaults.
 timeout_seconds = 10
 enabled = true
-side_effect = false           # 实验期内 `true` 会被拒绝
+side_effect = false           # `true` is refused while this is experimental
 ```
 
 | 键 | 类型 | 默认值 | 它命名的区间 |
 |---|---|---:|---|
-| `build_start` | 命令 | — | 项目准备完成后开启,命令退出时闭合 |
-| `build_finished` | 命令 | — | 构建成功后开启,命令退出时闭合 |
-| `build_failed` | 命令 | — | 构建失败后开启,命令退出时闭合 |
-| `during_build` | 命令 | — | 构建开始前开启,构建结束后闭合 |
-| `timeout_seconds` | 整数,1–86400 | `10` | 单次运行的时限 |
-| `enabled` | 布尔 | `true` | 是否启用本表中的全部命令 |
-| `side_effect` | 布尔 | `false` | Hook 失败是否让本次构建失败。**保留键**——实验期内只接受 `false` |
+| `build_start` | 命令 | — | 项目准备完成后开启，命令退出时闭合 |
+| `build_finished` | 命令 | — | 构建成功后开启，命令退出时闭合 |
+| `build_failed` | 命令 | — | 构建失败后开启，命令退出时闭合 |
+| `during_build` | 命令 | — | 构建开始前开启，构建结束后闭合 |
+| `timeout_seconds` | 整数，1–86400 | `10` | 单次运行的时限 |
+| `enabled` | 布尔 | `true` | 是否启用这张表里的全部命令 |
+| `side_effect` | 布尔 | `false` | Hook 失败是否让本次构建失败。**保留键** —— 实验期内只接受 `false` |
 
-前三个区间是**自闭合**的——命令退出,区间就结束。"同步"在这里不是一种单独的模式,
-它就是自闭合区间的样子。`during_build` 是唯一由别的东西闭合的区间,而那两个只对其中
-一种形状有意义的键,是从这一点推出来的,不是额外规定的例外。
+前三个区间是**自闭合**的 —— 命令一退出，区间就结束。"同步"在这里不是一种
+单独的模式，它就是自闭合区间的样子。`during_build` 是唯一由别的东西闭合的
+区间，而那两个只对其中一种形状有意义的键，是从这一点推出来的，不是额外
+规定的例外。
 
-命令写成字符串;需要选项时写成表:
+一条命令写成字符串，需要选项时写成一张表：
 
 | 表内键 | 适用于 | 含义 |
 |---|---|---|
-| `cmd` | 所有事件 | 命令本身,必填 |
-| `timeout_seconds` | 自闭合事件 | 覆盖本表默认值 |
-| `loop` | `during_build` | 命令在区间闭合前退出时重新启动 |
+| `cmd` | 所有事件 | 命令本身，必填 |
+| `timeout_seconds` | 自闭合事件 | 覆盖这张表的默认值 |
+| `loop` | `during_build` | 命令在区间闭合之前退出时重新启动 |
 
-`loop` 写在自闭合事件上、`timeout_seconds` 写在 `during_build` 上,都是**错误**而不是
-被忽略的键:自闭合区间随命令退出而结束,没有东西可重启;而 `during_build` 已经由构建
-定界。一个被接受却什么都不做的键,读起来就是"这功能坏了"。
+`loop` 写在一个自闭合事件上、`timeout_seconds` 写在 `during_build` 上，
+都是**错误**，而不是被忽略的键：自闭合区间随它的命令退出而结束，没有东西
+可重启；而 `during_build` 已经由构建本身定界。一个被接受、却什么都不做的
+键，读起来就是"这功能坏了"。
 
-命令通过宿主 Shell(`/bin/sh` 或 `cmd.exe`)执行,工作目录是**项目根目录**——不是敲
-`mcpp build` 的那个目录,所以 Hook 里的相对路径在哪儿发起构建都指同一处。自闭合命令
-的标准输入、输出和错误沿用普通终端行为。没有配置的事件直接跳过。
+命令通过宿主 Shell（`/bin/sh` 或 `cmd.exe`）执行，工作目录是**项目根
+目录** —— 不是敲下 `mcpp build` 的那个目录，所以 Hook 里的相对路径，不论
+在哪里发起构建都指同一处。一个自闭合命令沿用普通终端的输入、输出。没有
+配置的事件直接跳过。
 
-生命周期为:
+生命周期为：
 
 ```text
-during_build 开启
+during_build opens
 build_start
-    ├─ 构建成功 → during_build 闭合 → build_finished
-    └─ 构建失败 → during_build 闭合 → build_failed
+    ├─ build succeeds → during_build closes → build_finished
+    └─ build fails    → during_build closes → build_failed
 ```
 
-`during_build` 在终止 Hook **之前**闭合,因此两条命令不会重叠执行。
+`during_build` 在终止 Hook **之前**闭合，因此这两条命令从不重叠执行。
 
-`build_failed` 与 `build_finished` 互斥,而且两者都只在 `build_start` 已经执行之后
-才可达。项目**准备**阶段就失败的情况——manifest 非法、依赖无法解析、没有可用工具链
-——一个 Hook 都不触发:此时构建尚未开始,而 Hook 程序本身可能正是准备阶段要装的东西。
+`build_failed` 与 `build_finished` 互斥，而且两者都只在 `build_start` 已经
+执行之后才可达。项目**准备**阶段就失败的情形 —— manifest 非法、依赖无法
+解析、没有可用工具链 —— 一个 Hook 都不触发：构建此时尚未开始，而 Hook
+程序本身可能正是准备阶段要装的那个东西。
 
-命令无法启动、返回非零或超过时限均视为 Hook 失败。`during_build` 还多一种:开了 `loop`
-的命令**起不来**——连续五次在一秒内以非零状态结束——就不再重启,并被报出来。(很快就
-成功结束的命令,正是 `loop` 被要求重复的那件事,不算失败。)以上每一种都以 **warning**
-报出,构建保留它自己挣来的结果——`[hooks]` 还在实验期,它没有投票权。Hook 自身失败不会
-再触发另一个 Hook。
+一个 Hook 命令无法启动、返回非零，或超过时限，都算作一次 Hook 失败。
+`during_build` 还多一种：一个开了 `loop` 的命令**起不来** —— 连续五次
+在一秒之内以非零状态结束 —— 就不再被重启，并被报出来。（一个很快就成功
+结束的命令，正是 `loop` 被要求重复的那件事，不算失败。）以上每一种都以
+**warning** 报出，构建保留它自己挣来的结果 ——`[hooks]` 还在实验期，它
+没有投票权。一个 Hook 自身的失败不会触发另一个 Hook。
 
-改变这一点的正是 `side_effect = true`,而今天写它是一个错误:
+改变这一点的正是 `side_effect = true`，而今天写下它是一个错误：
 
 ```text
 error: mcpp.toml: error: [hooks].side_effect = true is not available yet:
 [hooks] is experimental and cannot decide whether a build succeeded. …
 ```
 
-是拒绝而不是悄悄降级,因为两种沉默的做法都更糟:采纳它等于让一个实验性功能对每一次
-构建都有否决权;忽略它则让项目以为自己的构建被通知程序把着关,而实际上没有。功能转正
-后,`true` 的含义是"Hook 失败让构建失败"——而构建自身失败时仍保留它自己的退出码,所以
-`mcpp build` 不会把一次编译错误报成通知程序的问题。
-
-关于 `during_build` 有两件事值得单独知道:
-
-- **它的输出被丢弃**,因为它与构建并发写出,否则会插进某条编译诊断的中间。要看它的
-  输出就跑 `mcpp build --verbose`。
-- **停止的单位是进程树,不是进程。** `player & wait` 让播放器成为 mcpp 所启动那条命令
-  的孙子进程,只停掉后者会让音频设备在构建结束后仍被占着。mcpp 把命令放进它自己的
-  进程组(Windows 上是 job object)并停止整组,构建被 Ctrl-C 打断时也一样。
-
-作用范围:
-
-- 只有 `mcpp build` 执行 Hook。`mcpp run`、`mcpp test` 和
-  `mcpp build --configure-only` 同样会构建,但有意不执行。
-- Hook 属于**被构建的那个包**。workspace 展开时就是逐个成员:各自的 `[hooks]`、
-  各自的构建、各自的根目录。**虚拟** workspace 根(只有 `[workspace]` 没有
-  `[package]`)不构建任何东西,写在那里的 `[hooks]` 永不触发。
-- 依赖的 `[hooks]` **一律跳过**,只有根项目的会执行。mcpp 解析的每一份 manifest 都
-  带着这一节,依赖的也带,而没有任何东西去读它——这正是"装一个包"不会变成"在我下次
-  构建时跑包作者的 Shell 命令"的原因。这是设计的性质,不是一个等着被打开的默认值。
-- 声明了生效的 Hook 就等于让项目放弃空转快路径,因为 `build_start` 规定在准备阶段之后
-  执行。对已经是最新状态的带 Hook 项目,`mcpp build` 的代价是一次准备,而不是毫秒级。
-
-`[hooks]` 里、以及某个事件表里不认识的**键**都是 warning(`--strict` 下为错误),所以为更新版 mcpp 写的
-manifest 在这一版仍能加载;不认识的**值**——`cmd` 缺失或不是字符串、`timeout_seconds` 不在
-1–86400 之间、键写给了错误的区间——是 manifest 错误。
-
-> **Hook 是代码,而 `mcpp.toml` 是仓库的一部分。** 构建一个刚克隆下来的项目,会以
-> 执行 `mcpp build` 的那个账户的权限,运行它 `[hooks]` 里写的任何东西。这与
-> `build.mcpp`([30 — build.mcpp](30-build-mcpp.md))已经要求的信任是同一份;
-> `[hooks]` 扩大的是它的范围,而不是引入了一份新的信任。
-
-Hook 程序可以作为普通 xlings 依赖安装。例如,音频通知程序可以把音频内置进自己的
-可执行文件,无需让 mcpp 处理媒体资源:
+是拒绝而不是悄悄降级，因为两种沉默的做法都更糟：采纳它，等于让一个实验性
+功能对每一次构建都有否决权；忽略它，则让项目误以为自己的构建被一个通知
+程序把着关，而实际上没有。功能转正之后，`true` 的含义将是"一次 Hook 失败
+让构建失败" —— 而构建自身失败时，仍会保留它自己的退出码，所以 `mcpp build`
+从不会把一次编译错误报成通知程序的问题。
+
+关于 `during_build` 命令，有两件事值得单独知道：
+
+- **它的输出被丢弃**，因为它与构建并发写出，否则会插进某条编译诊断的
+  中间。要看它的输出，跑 `mcpp build --verbose`。
+- **停止的单位是进程树，不是单个进程。** `player & wait` 让播放器成为
+  mcpp 所启动那条命令的孙子进程，只停掉后者，会让音频设备在构建结束后
+  仍被占用。mcpp 把命令放进它自己的进程组（Windows 上是 job object）
+  并停止整组，构建被 Ctrl-C 打断时也一样。
+
+作用范围，精确地说：
+
+- 只有 `mcpp build` 执行 Hook。`mcpp run`、`mcpp test` 与
+  `mcpp build --configure-only` 同样会构建，但有意不执行 Hook。
+- Hook 属于**被构建的那个包**。workspace 展开时，就是逐个成员各自的
+  `[hooks]`、各自的构建、各自的根目录。**虚拟** workspace 根（只有
+  `[workspace]` 没有 `[package]`）不构建任何东西，写在那里的 `[hooks]`
+  永不触发。
+- 一个依赖的 `[hooks]` **一律跳过**，只有根项目的会执行。mcpp 解析的每
+  一份 manifest 都带着这一节，依赖的也带，而没有任何东西去读它 —— 这正是
+  "装一个包"不会变成"在我下次构建时跑包作者的 Shell 命令"的原因。这是
+  设计本身的性质，不是一个等着被打开的默认值。
+- 声明了一个生效的 Hook，就等于让项目放弃空转快路径，因为 `build_start`
+  规定要在准备阶段之后执行。对一个已经是最新状态、又带 Hook 的项目，
+  `mcpp build` 的代价是一次准备，而不是毫秒级。
+
+`[hooks]` 里、以及某个事件表里不认识的**键**都是 warning（`--strict` 下
+为错误），因此为更新版 mcpp 写的 manifest，在这一版仍能加载；不认识的
+**值** —— `cmd` 缺失或不是字符串、`timeout_seconds` 不在 1–86400 之间、
+一个键写给了错误的区间 —— 是 manifest 错误。
+
+> **Hook 是代码，而 `mcpp.toml` 是仓库的一部分。** 构建一个刚克隆下来的
+> 项目，会以执行 `mcpp build` 的那个账户的权限，运行它 `[hooks]` 里写的
+> 任何东西。这与 `build.mcpp`([30 —— build.mcpp](30-build-mcpp.md))
+> 已经要求的信任是同一份；`[hooks]` 扩大的是它的范围，而不是引入了一份
+> 新的信任。
+
+Hook 程序可以作为普通的 xlings 依赖安装。例如，一个音频通知程序可以把
+音频文件内置进自己的可执行文件，不必让 mcpp 处理媒体资源：
 
 ```toml
 [hooks]
@@ -335,45 +360,47 @@ build_finished = "mcpp-hooks-audioplayer niulai-mm"
 build_failed = "mcpp-hooks-audioplayer niulai-niulai"
 side_effect = false
 
-[xlings]
-deps = ["xim:mcpp-hooks-audioplayer@0.0.1"]
+[xlings.workspace]
+"xim:mcpp-hooks-audioplayer" = "0.0.1"
 ```
 
-根据构建成功或失败播放不同提示音。`side_effect = false` 写出来而不是靠默认值:它是
-这份 manifest 自己就想要的值——缺个音频设备不该让构建失败——所以等这个键有了不止
-一个可接受的值之后,它仍然会这么写。
+构建成功或失败播放不同的提示音。`side_effect = false` 被明确写出来，而
+不是留给默认值：它是这份 manifest 自己就想要的值 —— 缺一个音频设备不该
+让构建失败 —— 所以等这个键有了不止一个可接受的值之后，它仍然会这么写。
 
 ## 失败所属的阶段
 
-一次构建要跨过若干阶段,而消息会点名失败的那一段。先读这一点,可以省掉打开错误
-章节的功夫。
+一次构建要跨过若干阶段，而一条消息会点名失败的那一段。先读出这一点，能省
+下打开错误章节的功夫。
 
 | 消息里出现 | 阶段 | 参考章节 |
 |---|---|---|
-| 包名、版本,或「没有候选」 | 解析 | [05](05-dependencies.md)、[11](11-publishing-a-library.md) |
-| 下载、载荷,或版本下界 | 供给 | [20](20-toolchains.md)、[23](23-the-project-environment.md) |
-| 三元组,或「不支持的目标」 | 目标 | [21](21-the-target-triple.md) |
-| 某个模块读不到或没有人提供它 | 模块图 | [30](30-build-mcpp.md) |
+| 一个包名、一个版本，或"没有候选" | 解析 | [05](05-dependencies.md)、[11](11-publishing-a-library.md) |
+| 一次下载、一份载荷，或一条版本下界 | 供给 | [20](20-toolchains.md)、[23](23-the-project-environment.md) |
+| 一个三元组，或"不支持的目标" | 目标 | [21](21-the-target-triple.md) |
+| 一个模块读不到，或没有人提供它 | 模块图 | [30](30-build-mcpp.md) |
 | 工程自己某个文件内部的编译或链接错误 | 一段都不是 | 编译器自己的消息 |
 
-最后一行是有用的那一行:当错误是关于代码本身时,mcpp 的任何一段都没有参与,它的
-文档不会有帮助。
+最后一行是最有用的一行：当错误是关于代码本身时，mcpp 的任何一段都没有
+参与，它的文档不会有帮助。
 
 ## 当前边界
 
 - `mcpp why --format json` 只对 `toolchain` 话题有定义。其余话题报
   `'<topic>' has no machine-readable shape yet` 并以非零退出。
-- `mcpp search` 按子串匹配;没有字段选择器,也没有把搜索限定到单个命名空间的方式。
-- `mcpp clean --stale` 读 `target/.build_cache`,它保存的近期条目数量有上限。一个工程
-  如果构建过的 (目标, profile) 组合多于这个上限,最旧的条目会被挤掉;条目被挤掉的目录
-  随后按未记录处理 —— 在 `--older-than` 之内保留,超出则删除。
+- `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,但这一种取值上不一致。
+  (expected <N>{s,m,h,d})` 被拒绝,而 `mcpp clean --stale --older-than 0`
+  接受同样的值。两个选项共用一个 parser，但这一种取值上不一致。
 
-`mcpp emit xpkg` 写出一个 `mcpp xpkg parse` 不认识的键。对一个自带 `mcpp.toml`
-的包,产出的 `mcpp` 段以 `manifest = "mcpp.toml"` 结尾,而描述符解析器把它报为
-未知键:
+`mcpp emit xpkg` 写出一个 `mcpp xpkg parse` 不认识的键。对一个自带
+`mcpp.toml` 的包，产出的 `mcpp` 段以 `manifest = "mcpp.toml"` 结尾，而
+描述符解析器把它报为未知键：
 
 ```
 error: unknown mcpp-segment key 'manifest' — silently ignored at build time
@@ -382,11 +409,10 @@ error: synthesised manifest missing sources (mcpp segment must declare
        `sources = { ... }`)
 ```
 
-第二个错误由第一个导出:键被忽略,于是没有从它点名的那份 manifest 推导出任何
-源。手工补上 `sources = { … }` 只消掉第二个,消不掉第一个,`mcpp xpkg parse`
-仍然以 1 退出。
-
-`mcpp-index` 里没有任何描述符使用那个键 —— 218 个里 0 个。自带 `mcpp.toml` 的包
-**整个省略 `mcpp` 字段**,由 mcpp 在版本目录下查找那份 manifest。实测于
-2026.9.8.1。
+第二个错误由第一个导出：键被忽略，于是没有从它点名的那份 manifest 推导出
+任何源。手工补上 `sources = { … }` 只能消掉第二个，消不掉第一个，
+`mcpp xpkg parse` 仍然以 1 退出。
 
+`mcpp-index` 里没有任何描述符使用那个键 —— 218 个里 0 个。自带
+`mcpp.toml` 的包**整个省略 `mcpp` 字段**，由 mcpp 在版本目录下查找那份
+manifest。实测于 2026.9.8.1。
diff --git a/docs/zh/10-pack-and-release.md b/docs/zh/10-pack-and-release.md
index b7e22d8d6..f02a56cbe 100644
--- a/docs/zh/10-pack-and-release.md
+++ b/docs/zh/10-pack-and-release.md
@@ -1,156 +1,181 @@
 # 10 —— 发布打包
 
-**读者:**要把一个程序交付到没有 mcpp 的机器上的人。
+**读者：** 要把一个程序交付到没有 mcpp 的机器上的人。
 
-**本章回答的那一个问题:**怎样把一次构建变成另一台机器能运行的东西,以及每种打包
-模式各自携带什么。
+**本章回答的那一个问题：** 一次构建怎样变成另一台机器能运行的东西，以及每一种
+打包模式各自携带什么。
 
-**不在这里:**交付一个供其它包构建时使用的**库**,那是
-[12 —— 分发预编译库](12-binary-distribution.md)。在此之后:
+**不在这里：** 交付一个供其它包在构建时使用的**库**，那是
+[12 —— 分发预构建库](12-binary-distribution.md)。在此之后：
 [11 —— 发布一个库到 mcpp-index](11-publishing-a-library.md)。
 
-> 默认的动态链接 `mcpp build` 产物会把 loader 与 RUNPATH 指向构建沙盒。它是
-> 开发产物,不是交付物。有三条路把它变成交付物 —— **没有一条使用宿主的 C 库**。
+> 本页讲的是打包一个**程序**。若要以「接口 + 预构建二进制」的形式发布一个*库*，
+> 见 [12 —— 分发预构建库](12-binary-distribution.md)。
+>
+> `mcpp pack` 具体做哪一种，由 target 的 `kind` 决定，不由某个 flag 决定：
+> `mcpp pack <name>` 打包 `[targets.<name>]`，一个 `bin` 会变成一个 bundle，
+> 而一个 `lib`/`shared` 会变成一个库包。不给名字时，mcpp 选择唯一可打包的
+> target。
+
+> `mcpp build` 默认产出的动态链接二进制，其 loader 与 RUNPATH 都指向构建
+> 沙盒。它是开发产物，不是交付物。有三条路径能把它变成交付物 —— 没有一条会
+> 用到宿主的 C 库。
 
 ## 三种分发路径
 
-下面每一条产出的产物,其 C 运行时都来自生态,而不是 `/lib64`。这是有意的:
-mcpp 之所以针对私有 glibc 构建,正是为了让产物的行为不取决于底下是哪个发行版;
-如果最后一步又伸手去拿宿主的 libc,前面这件事就白做了。
+下面每一种路径产出的产物，其 C 运行时都来自生态，从不来自 `/lib64`。这是有意
+安排的：mcpp 之所以针对私有 glibc 构建，正是为了让产物的行为不取决于底层是
+哪一个发行版；如果分发的最后一步又伸手去用宿主的 libc，前面这一步做的事就白
+费了。
 
-| | 方式 | 命令 | C 运行时的来源 | 适用条件 |
+| | 路径 | 命令 | C 运行时的来源 | 适用条件 |
 |---|---|---|---|---|
-| **A** | 走生态 | `mcpp emit xpkg` → `xlings install <pkg>` | 目标机自己的 xlings 载荷 | 目标机装了 xlings |
-| **B** | 静态单文件 | `mcpp build --target x86_64-linux-musl` | 不来自任何地方 —— 已链进去 | 想要一个无任何运行时依赖的单文件 |
-| **C** | 自带运行时 | `mcpp pack --mode self-contained` | 随 bundle 一起分发 | 任何 Linux,含比构建机更老的 |
+| **A** | 走生态 | `mcpp emit xpkg` → `xlings install <pkg>` | 目标机自己的 xlings 载荷 | 目标机已装 xlings |
+| **B** | 单个静态文件 | `mcpp build --target x86_64-linux-musl` | 不来自任何地方 —— 已链接进去 | 需要一个没有任何运行时依赖的单文件 |
+| **C** | 自带运行时 | `mcpp pack --mode self-contained` | 随 bundle 一起分发 | 任意 Linux，含比构建机更旧的版本 |
 
-**关于 A。** 刚构建出的二进制中记录的 `PT_INTERP` 指向**构建机**的载荷,因此
-手工复制该文件到另一台机器无法运行 —— 该路径在目标机上不存在。这是「手工复制」
-这一动作的性质,而非产物的性质:经 `xlings` 安装时,包内的 ELF 会在**安装期被
-重指到目标机自己的载荷**。记录的路径属于构建机细节,不属于分发格式。需要在机器
-之间手工复制二进制时,应选择 B 或 C。
+**关于路径 A。** 刚构建出的二进制中记录的 `PT_INTERP` 指向构建机的载荷，因此
+把该文件手工复制到另一台机器上不会运行：那条路径在目标机上不存在。这是「手工
+复制」这个动作的性质，不是产物本身的性质 —— 经 `xlings` 安装时，包内的 ELF 会
+在安装期被重新指向目标机自己的载荷。记录的路径是构建机的细节，不是分发格式的
+一部分。需要在机器间手工搬运二进制时，能存活下来的是路径 B 与 C。
 
-**关于 B。** `--target …-musl` 隐含静态链接,所以没有 loader、没有 RUNPATH、
-运行期不需要找任何东西。它的结果最小也最可移植,在程序不需要 glibc 专有行为
-(NSS 查询、`dlopen` 宿主插件)时应当首选。
+**关于路径 B。** `--target …-musl` 隐含静态链接，因此没有 loader、没有
+RUNPATH，运行期不需要查找任何东西。它的结果最小也最可移植，是程序不需要
+glibc 专有行为（NSS 查询、`dlopen` 宿主插件）时的首选。
 
-**关于 C。** bundle 里带着这套工具链的 glibc 与 loader,因此能在比构建机更老的
-发行版上跑 —— 这是 B 覆盖不了、而又确实需要 glibc 时的那一格。选它之前先读下面
-的 `/proc/self/exe` 一节:经 bundled loader 启动会改变程序对「自己在哪」的认知。
+**关于路径 C。** bundle 内携带这套工具链的 glibc 及其 loader，因此能在比构建机
+更旧的发行版上运行 —— 这是路径 B 覆盖不到、而又确实需要 glibc 时的那一格。选
+它之前先读下面 `/proc/self/exe` 一节：经由内置 loader 启动会改变程序对「自己
+在哪」的认知。
 
-## 两条轴:target(libc) × mode(打包深度)
+## 两条轴：target（libc）× mode（打包深度）
 
-发布有两项正交选择:
+分发有两项正交的选择：
 
-- **libc / static** 是*构建 target* 属性:`--target …-linux-gnu`(glibc) 与
-  `--target …-linux-musl`(musl,static)。`--target …-musl` 隐含 `static`。
-- **打包深度** 是*pack* 属性:产物携带多少共享库闭包,由 `--mode` 选择。
+- **libc / static** 是一项*构建 target* 属性：`--target …-linux-gnu`（glibc）
+  与 `--target …-linux-musl`（musl，静态）。`--target …-musl` 隐含 `static`。
+- **打包深度** 是一项*pack* 属性：产物随身携带多少共享库闭包，由 `--mode`
+  选择。
 
-| 模式 | 宿主必须提供 | 体积 | 使用场景 |
+| Mode | 宿主必须提供 | 体积 | 使用场景 |
 |---|---|---|---|
-| `system` | 所有 `.so`(含第三方) | 最小 | `.deb`/`.rpm`,同发行版集群(包管理器声明依赖) |
-| `vendored`(默认) | libc / libstdc++ / loader | +几 MB | 主流发行版(Ubuntu 22+,Debian 12+,RHEL 9+) |
-| `self-contained` | 无 | +30–50 MB | 任意 Linux(含旧 glibc);携带闭包与 `run.sh` wrapper |
-| `static` | 无(单文件) | +5–10 MB | musl;匹配架构的 Linux x86_64 或 aarch64,Docker scratch,Alpine |
+| `system` | 每一个 `.so`（含第三方） | 最小 | `.deb`/`.rpm`，同发行版机群（由包管理器声明依赖） |
+| `vendored`（默认） | libc / libstdc++ / loader | +几 MB | 主流发行版（Ubuntu 22+、Debian 12+、RHEL 9+） |
+| `self-contained` | 无 | +30–50 MB | 任意 Linux，含较旧的 glibc；携带闭包与 `run.sh` wrapper |
+| `static` | 无（单文件） | +5–10 MB | musl；架构匹配的 Linux x86_64 或 aarch64，Docker scratch，Alpine |
+
+如何选择：
 
-选择建议:
+- 分发格式打包（`.deb`/`.rpm`）或同发行版内部部署 → `system`
+- 面向主流发行版的桌面 / 服务端发布 → `vendored`（默认）
+- 跨发行版，或目标是较旧的 glibc（旧版 CentOS、麒麟等） → `self-contained`
+- 单个便携文件、不依赖宿主 → `static`
 
-- `.deb`/`.rpm` 或同发行版内部部署 → `system`
-- 桌面或服务端发布,目标为主流 Linux 发行版 → `vendored`(默认)
-- 需兼容老旧 CentOS、麒麟等 glibc 版本较低的环境 → `self-contained`
-- 单个便携文件、无宿主依赖 → `static`
+**没有任何 mode 会携带构建机的路径。** 开发构建有意寻址的是本机：它的
+`DT_RPATH` 命名工具链的载荷目录与 SubOS 的库视图（`<subos>/lib`），它的
+`PT_INTERP` 命名一个私有 loader。每一种 mode 都改写这两者 —— `vendored` 与
+`self-contained` 改写为相对 `$ORIGIN` 的路径，`system` 则整个清空搜索路径并
+恢复平台标准的 interpreter。`system` 不是「原样保留构建时的样子」，而是「目标
+机会提供一切」这一断言 —— 这是关于目标机的陈述，不可能用本机的绝对路径拼出
+来。e2e 215 会扫描 bundle 里每一个 ELF，查找任何落在 `$MCPP_HOME` 之下的路径，
+命中即失败。
 
-### 需要宿主提供能力的程序
+### 需要宿主提供某种能力的程序
 
-「自包含」有一个下限。有些库只能来自目标机器:图形驱动的用户态部分与正在运行的
-内核模块版本绑定,而对专有栈而言,再分发是不被允许的。这类依赖应声明为运行期能力
-需求(`docs/zh/04-mcpp-toml.md` §2.11),模式表随之多出一列:
+「自包含」有一个下限。有些库只能来自目标机器：图形驱动的用户态部分与正在
+运行的内核模块版本绑定，而对专有栈而言，再分发是不被允许的。这类依赖应声明为
+运行期能力需求（`docs/04-mcpp-toml.md` §2.11），模式表因此多出一列：
 
 | Mode | 需要宿主提供能力的程序 |
 |---|---|
 | `system` | yes |
-| `vendored`(默认) | **这类程序的正确默认值** |
+| `vendored`（默认） | **对这类程序而言正确的默认值** |
 | `self-contained` | **打包期拒绝** |
 | `static` | **打包期拒绝** |
 
-两处拒绝出自同一个事实:**自带 libc 的 bundle 无法消费宿主提供的库。** 那个 `.so`
-带着它对**目标机 libc** 的要求到达,而该进程没有那份 libc —— 双向实测记录于
-mcpp#392 / mcpp#401:私有 glibc 遇上宿主加载的对象,会在重定位阶段、`main` 之前
-崩溃。此前这两种模式都是链接通过、启动时失败,或静默降级(图形栈的表现是软件
-渲染,而没有任何提示)。
+两处拒绝出自同一个事实：**自带 libc 的 bundle 无法消费宿主提供的库。** 那个
+`.so` 带着它对*目标机* libc 的要求到达，而该进程没有那份 libc —— 双向实测记录
+于 mcpp#392 / mcpp#401：私有 glibc 遇上宿主加载的对象，会在重定位阶段、
+`main` 之前崩溃。此前这两种 mode 的行为要么是链接通过、启动时失败，要么是
+静默降级（就图形栈而言表现为软件渲染，且没有任何提示）。
 
-`vendored` 会打包这类程序,并在 bundle 根目录写出一个 **`HOST-REQUIREMENTS`**
-文件,说明目标机必须提供什么:
+`vendored` 会打包这类程序，并在 bundle 根目录写出一个 **`HOST-REQUIREMENTS`**
+文件，说明目标机必须提供什么：
 
 ```
 capability=opengl.glx.driver discovery=rpath-of-dispatch
 ```
 
-`discovery` 是可行动的那一半 —— 各机制彼此独立,满足其一并不等于满足另一个。
-该文件仅在确有内容时写出:一个空文件等于**声称**什么都不需要。
+`discovery` 是可操作的那一半 —— 各机制彼此独立，满足其一不代表满足另一个。该
+文件只在确有内容需要说明时才写出：一个空文件等于**声称**什么都不需要。
 
-### 模式名兼容性
+### 模式名的兼容性
 
-上表是规范名称。旧名称仍是**永久兼容别名**:`bundle-project` = `vendored`,
-`bundle-all` = `self-contained`。tarball 后缀是被冻结的 wire 格式(由
-`install.sh` 消费),不会跟随名称改变:`vendored` 无后缀,`self-contained` 是
-`-bundle-all`,`static` 是 `-static`,`system` 是 `-system`。
+上表给出规范名称。旧名称仍是**永久性的兼容别名**：`bundle-project` =
+`vendored`，`bundle-all` = `self-contained`。tarball 的文件名后缀是被冻结的
+wire 格式（由 `install.sh` 消费），**不**跟随改名：`vendored` 无后缀，
+`self-contained` 是 `-bundle-all`，`static` 是 `-static`，`system` 是
+`-system`。
 
 ## 命令
 
 ```bash
-mcpp pack                          # 默认 vendored
+mcpp pack                          # vendored by default
 mcpp pack --mode system
 mcpp pack --mode static
-mcpp pack --mode self-contained     # 别名:--mode bundle-all
-mcpp pack --target x86_64-linux-musl   # 等价 --mode static
-mcpp pack --target aarch64-linux-musl  # ARM64 等价写法
-mcpp pack --format dir                 # 输出为目录,不打包 tarball
-mcpp pack --format appimage             # 由图里某个包提供的格式
-mcpp pack -o myapp.tar.gz              # 仅文件名:落到 target/dist/myapp.tar.gz
-mcpp pack -o /abs/path/myapp.tar.gz    # 含目录:按字面路径输出
-mcpp pack --profile dev                # 换一个 profile 构建(默认 release)
-mcpp pack --dev                        # 同上,拼法与 build、run 一致;--profile 优先于它
-mcpp pack --message-format json        # 在 stdout 上输出一个 mcpp.pack 信封(mcpp 2026.9.16.1+)
-mcpp pack --no-strip                   # 按构建原样发货,不剥符号
-mcpp pack --debug-symbols dbg/         # 把分离出的 *.debug 写到 dbg/
-mcpp pack --format msi --features installer   # 为这次打包启用根包 feature
+mcpp pack --mode self-contained        # alias: --mode bundle-all
+mcpp pack --target x86_64-linux-musl   # equivalent to --mode static
+mcpp pack --target aarch64-linux-musl  # ARM64 equivalent
+mcpp pack --format dir                 # output as a directory, no tarball
+mcpp pack --format appimage             # a format a package in the graph provides
+mcpp pack -o myapp.tar.gz              # filename only: lands at target/dist/myapp.tar.gz
+mcpp pack -o /abs/path/myapp.tar.gz    # includes a directory: output to the literal path
+mcpp pack --profile dev                # build with a different profile (default: release)
+mcpp pack --dev                        # the same, as `build` and `run` spell it; --profile wins over it
+mcpp pack --message-format json        # one mcpp.pack envelope on stdout (mcpp 2026.9.16.1+)
+mcpp pack --no-strip                   # ship the artifacts as built
+mcpp pack --debug-symbols dbg/         # write the separated *.debug files under dbg/
+mcpp pack --format msi --features installer   # activate root-package features for the pack
 ```
 
-`--features <LIST>`(mcpp 2026.9.15.2+)为打包执行的每一次构建启用根包 feature:每条
-`--target` 腿,以及分派格式的两次构建。它与 `mcpp build --features` 接受同样的取值,
-因此只为某一种发布才需要的主机工具,可以声明在带 `tools = [...]` 的
-`[feature-deps.<f>]` 下,只由点名 `<f>` 的那次打包构建。
-`mcpp run --format <name> --features <LIST>` 把同样的 feature 交给它执行的那次打包。
+`--features <LIST>`（mcpp 2026.9.15.2+）为打包所执行的每一次构建启用根包
+feature：每一条 `--target` 腿，以及被分派格式的两遍构建。它接受的取值与
+`mcpp build --features` 相同，因此只为某一种发布才需要的宿主工具，可以声明在
+带 `tools = [...]` 的 `[feature-deps.<f>]` 下，只由点名 `<f>` 的那次打包构建
+出来。`mcpp run --format <name> --features <LIST>` 把同样的 feature 交给它
+执行的那次打包。
 
-`--release` 与 `--dev`(mcpp 2026.9.16.1+)是 `build`、`run` 所接受的简写,优先级相同:
-三条命令上都是 `--profile` 优先于它们。
+`--release` 与 `--dev`（mcpp 2026.9.16.1+）是 `build`、`run` 已接受的简写，
+优先级相同：三条命令上都是 `--profile` 优先于它们。
 
-`--message-format json`(mcpp 2026.9.16.1+)在命令结束后于 stdout 上输出一个
-`mcpp.pack` 信封,所有给人读的行都走 stderr。其 `data.artifacts` 列出产出的每个文件或
-目录:绝对路径、`type`(`file` 或 `directory`)、`--format` 取值以及各条腿的三元组;
-`data.stage` 给出暂存树、它的 manifest 以及闭包是否走通
-([50 —— 机器输出](50-machine-output.md))。这条命令上的 `--format` 表示包格式,因此
-机器输出按 `mcpp test` 的方式请求。
+`--message-format json`（mcpp 2026.9.16.1+）在命令结束后于 stdout 上输出一个
+`mcpp.pack` 信封，所有给人看的行都改走 stderr。它的 `data.artifacts` 列出
+产出的每一个文件或目录，带绝对路径、`type`（`file` 或 `directory`）、
+`--format` 取值以及各条腿的三元组；`data.stage` 给出暂存树、它的 manifest，
+以及闭包是否已经走通（见 [50 —— 机器输出](50-machine-output.md)）。这条命令
+上的 `--format` 表示的是包格式，因此机器输出改用 `mcpp test` 请求它的那种
+方式。
 
-### `--format` 是一个轴,引擎只拥有其中两个取值
+### `--format` 只是一根轴，引擎只拥有它的两个取值
 
-`tar` 与 `dir` 回答的问题,和 `msi` 与 `appimage` 回答的问题是同一个 —— 输出取什么
-形状 —— 所以它们是一个 flag 的取值,而不是第二个 flag 的开端。引擎持有什么、包持有
-什么,分界是:
+`tar` 与 `dir` 回答的问题，和 `msi` 与 `appimage` 回答的问题是同一个 ——
+输出取什么形状 —— 所以它们是同一个 flag 的不同取值，而不是第二个 flag 的开端。
+引擎持有什么、包持有什么，分界如下：
 
-> **`mcpp pack` 拥有机制,以及那一种通用格式。其余每一种格式都住在包里,由
-> `mcpp pack` 分派过去。**
+> **`mcpp pack` 拥有机制，以及那一种通用格式。其余每一种格式都住在某个包里，
+> 由 `mcpp pack` 分派过去。**
 
-那种通用格式就是它已经在产出的东西:一个解开就能跑的归档。它「通用」只在这里唯一
-要紧的那个意义上 —— 它不需要知道任何别人的发布。此外的一切都需要。dpkg 的 control
-字段、AppImage 的 runtime、WiX 的 schema、Apple 的公证、Android 的签名方案:其中任何
-一个被绑进引擎,都会把一次 mcpp 的发布耦合到一次 mcpp 并不控制的发布上。这与本项目
-早已为语言做过的论证是同一个 —— Slang 被支持,而引擎里没有它的名字。
+那种通用格式就是它已经在产出的东西：一个解开即可运行的归档。它「通用」只在这
+里唯一要紧的那个意义上成立 —— 它不需要了解任何别人的发布方式。此外的一切都
+需要。dpkg 的 control 字段、AppImage 的 runtime、WiX 的 schema、Apple 的
+公证、Android 的签名方案：其中任何一个被绑进引擎，都会把一次 mcpp 的发布耦合
+到一次 mcpp 并不控制的发布上。这与本项目已经为语言做过的论证是同一个 ——
+Slang 被支持，而引擎里没有它的名字。
 
-所以取值集合是开放的(mcpp 2026.9.11.1+)。`--format <name>` 在解析后的图里找到声明
-了 `<name>` 的那个包,并把暂存树交给它;一个未知的取值会点名**当下确实可用**的那些,
-而不是一份固定清单:
+所以取值集合是开放的（mcpp 2026.9.11.1+）。`--format <name>` 在解析后的图里
+找到声明了 `<name>` 的那个包，并把暂存树交给它；一个未知的取值点名的是
+**当下确实可用**的那些，而不是一份固定清单：
 
 ```
 error: unknown --format 'bogus'.
@@ -160,377 +185,391 @@ error: unknown --format 'bogus'.
   that provides 'bogus' to [build-dependencies] and activate its feature.
 ```
 
-这次拒绝发生在任何东西被编译之前。怎么写这样一个包,见
-[产出可分发物](30-build-mcpp.md#产出可分发物pack_format-与-stage_dir20269111);
-引擎加的三样东西是:一棵 `artifact` action 可以消费的暂存树、`[package]` 的其余字段
-进入构建程序、以及这次分派本身。每一样都与格式无关 —— 而「与格式无关」正是判断某样
-东西该不该进引擎的判据。
+这次拒绝发生在任何东西被编译之前。怎样写这样一个包，见
+[产出可分发物](30-build-mcpp.md#产出可分发物pack_format-与-stage_dir20269111)；
+引擎为此新增的三样东西是：一棵 `artifact` action 可以消费的暂存树、
+`[package]` 里其余字段进入构建程序、以及这次分派本身。每一样都与具体格式无关
+—— 「与格式无关」正是判断某样东西该不该进引擎的判据。
 
-被分派的格式作用于一个**程序** target——`kind = "app"` 也不例外,不论这一行把它
-链接成什么文件(见[04 §2.2](04-mcpp-toml.md))。库包发的是一份接口加上每个三元组
-的预构建产物,没有单独一棵暂存树,所以 `mcpp pack <库> --format <name>` 会被拒绝,
-而不是被忽略。
+被分派的格式作用于一个**程序** target —— `kind = "app"` 也不例外，无论这一行
+把它链接成什么文件（见 [04 §2.2](04-mcpp-toml.md)）。库包发布的是一份接口
+加上按三元组给出的预构建产物，没有单独一棵暂存树，所以
+`mcpp pack <库> --format <name>` 会被拒绝，而不是被忽略。
 
 **产物是共享目标文件的 `kind = "app"` target 可以接受一个以上的 `--target`**
-(mcpp 2026.9.13.2+):在每一行 Android 上,一个应用*就是*平台加载的那个共享库,
-所以 `mcpp pack myapp --target aarch64-linux-android --target x86_64-linux-android`
-会构建并把两条腿暂存进同一棵树里,与库包的多三元组做法完全一致。每条腿落在
-`lib/<abi>/lib<name>.so`(`aarch64` → `arm64-v8a`,`x86_64` → `x86_64`),各自的
-闭包暂存在它旁边(见 [Android](#android应用目标文件与它的闭包在-lib-下)),声明的
-部署文件只暂存一次,随后对这棵合并后的树只跑一次分派——这正是 `dist-apk` 这样的
-成员能构建出一个通用 APK 的原因。只给一个 `--target` 时,今天这种扁平的
-`lib/lib<name>.so` 布局保持不变。产物在任何被请求的一行上是可执行文件的 target,
-第二个 `--target` 依旧被拒绝:为多个三元组打包一个可执行文件需要多个可执行文件,
-那是另一种机制(`lipo` 的通用二进制),不在此列。
-
-`-o` 接受裸文件名时自动归到 `target/dist/`;含目录(相对或绝对)
-时按字面路径输出。
+（mcpp 2026.9.13.2+）：在每一行 Android 上，应用*就是*平台加载的那个共享库，
+因此 `mcpp pack myapp --target aarch64-linux-android --target x86_64-linux-android`
+会构建两条腿并把它们暂存进同一棵树，与库包本已具备的多三元组做法完全一致。
+每条腿落在 `lib/<abi>/lib<name>.so`（`aarch64` → `arm64-v8a`，`x86_64` →
+`x86_64`），各自的闭包暂存在它旁边（见
+[Android](#android应用目标文件与它的闭包在-lib-下)），声明的部署文件只暂存
+一次，随后只对这棵合并后的树跑一次分派 —— 这正是 `dist-apk` 这样的成员能构建
+出一个通用 APK 的原因。只给一个 `--target` 时，今天这种扁平的
+`lib/lib<name>.so` 布局保持不变。产物在任何被请求的一行上是可执行文件的
+target，第二个 `--target` 依旧被拒绝：为多个三元组打包同一个可执行文件需要
+多个可执行文件，那是另一种机制（`lipo` 的通用二进制），不在这份能力之内。
+
+`-o` 接受裸文件名时，输出落在 `target/dist/` 下；含目录（相对或绝对）时，按
+字面路径输出。
 
 完整选项参见 `mcpp pack --help`。
 
-### `mcpp run --format <name>`(mcpp 2026.9.12.3+)
+### `mcpp run --format <name>`（mcpp 2026.9.12.3+）
 
 ```bash
 mcpp run --target x86_64-linux-android --format apk
 mcpp run --target aarch64-ios-sim      --format app
 ```
 
-`--format` 与 `mcpp pack` 用的是同一个 flag,这里复用它来覆盖一种普通 `mcpp run`
-够不到的情形:一个 Android 应用程序是一个 `.apk`,一个已安装的 iOS 应用程序是一个
-`.app`,两者都不是 `mcpp run` 默认执行的链接产物。`mcpp run --format <name>` 先为
-`<name>` 打包——与 `mcpp pack --format <name>` 相同的两遍与暂存树——再运行打包
-报出的那个产物,经由为一个程序解析出的 runner:项目的 `[target.<triple>] runner`,
-其次依赖的 `mcpp::runner(...)`,再次载荷描述文件的。
-
-打包报出的产物是这次请求的**终端**产物:在请求引入的 `artifact` 动作中,没有被其他
-引入动作当作输入的那个输出。提供者常常是一条链(`dist-apk`:链接、加库、对齐、签名),
-链上每个输出都会被核验存在,但只有最后一个是发布物,也只有它以 `Packed` 报出。链的
-末端有两个文件的格式会被 `mcpp run --format` 拒绝并点名两者,因为 runner 只接受一个
-操作数。
-
-未知的 `<name>` 会被拒绝,点名已解析图提供的格式集合,与 `mcpp pack --format
-bogus` 报出的是同一个集合。`--format` 与 `--no-runner` 同时出现会被拒绝——一个
-`.apk` 或已安装的 `.app` 无法被直接执行。在 `kind = "app"` 的形态是一个库的那一行上,
-不带 `--format` 运行它同样被拒绝,点名该旗标与同一个格式集合。`mcpp test` 不受影响:
-测试二进制在每一行上都是程序。
-
-### 打包产物的构建输入与随包内容
-
-与 `mcpp build` 有两点不同,都因为「这个产物要离开本机」:
-
-**profile 的兜底是 `release` 而不是 `dev`。** 其余优先级不变 ——
-`--profile` > `[build] default-profile` > 兜底。只有最后一步不同,所以声明过
-profile 的工程仍然拿到它声明的那个,`mcpp pack` 也不会产出一个 `mcpp build`
-产不出来的 flag 组合。
-
-> 有一条后果要知道:裸 `mcpp build` 与裸 `mcpp pack` 现在会写进**不同的**
-> `target/<triple>/<fingerprint>/` 目录 —— 指纹把 profile 算进去了。手工放到
-> 构建产物旁边的文件(一个 DLL、一份数据)因此只在两条命令解析到同一个
-> profile 时才被 `pack` 看见:把它写进 `[build] default-profile`,或者两条命令
-> 都带 `--profile`。声明式通道(`[runtime] deploy_files`、
-> `runtime_search_dirs`)不受影响。
-
-**调试信息会被剥掉,发布者的路径随之消失。** 未 strip 的产物带着 DWARF,而
-DWARF 带着发布者源码树与构建目录的绝对路径。剥什么取决于产物**是什么** ——
-这是 dh_strip 的分档,而其中归档那一行是要命的:
-
-| 产物 | strip 参数 | 不能更进一步的原因 |
+`--format` 与 `mcpp pack` 用的是同一个 flag，这里复用它是为了覆盖一种普通
+`mcpp run` 够不到的情形：一个 Android 应用程序是一个 `.apk`，一个已安装的 iOS
+应用程序是一个 `.app`，两者都不是 `mcpp run` 默认执行的链接产物。
+`mcpp run --format <name>` 先为 `<name>` 打包 —— 与 `mcpp pack --format
+<name>` 相同的两遍构建与暂存树 —— 再经由为一个程序解析出的 runner 运行打包
+报出的那个产物：先看项目的 `[target.<triple>] runner`，其次看依赖的
+`mcpp::runner(...)`，再次看载荷描述文件的。
+
+打包报出的产物是这次请求的**终端**产物：在这次请求引入的 `artifact` 动作中，
+没有被任何其他被引入的动作当作输入的那一个输出。一个提供者常常是一条链
+（`dist-apk`：链接、加库、对齐、签名），链上每个输出都会被核验存在，但只有
+最后一个是发布物，也只有它以 `Packed` 报出。链的末端产出两个文件的格式会被
+`mcpp run --format` 拒绝并点名两者，因为一个 runner 只接受一个操作数。
+
+未知的 `<name>` 会被拒绝，点名已解析图提供的格式集合，与
+`mcpp pack --format bogus` 报出的是同一个集合。`--format` 与 `--no-runner`
+同时出现会被拒绝 —— 一个 `.apk` 或一个已安装的 `.app` 无法被直接执行。在
+`kind = "app"` 的形态是一个库的那一行上、不带 `--format` 运行它，同样会被
+拒绝，点名该 flag 与同一个格式集合。`mcpp test` 不受影响：测试二进制在每一行
+上都是一个程序。
+
+### 打包产物的构建输入，以及随包内容
+
+与 `mcpp build` 相比有两点不同，都源于同一个原因：「这个产物要离开本机」。
+
+**profile 的兜底值是 `release`，不是 `dev`。** 其余优先级不变 ——
+`--profile` 优先于 `[build] default-profile`，后者优先于兜底值。只有最后
+一步不同，因此已经声明过 profile 的工程仍然拿到它声明的那个，`mcpp pack` 也
+绝不会产出一个 `mcpp build` 在同样条件下产不出来的 flag 组合。
+
+> 有一条后果值得知道：裸 `mcpp build` 与裸 `mcpp pack` 现在会写进**不同的**
+> `target/<triple>/<fingerprint>/` 目录 —— 指纹把 profile 算了进去。手工放到
+> 构建产物旁边的文件（一个 DLL、一份数据）因此只在两条命令解析到同一个
+> profile 时才会被 `pack` 看见：要么把它写进 `[build] default-profile`，要么
+> 两条命令都带上 `--profile`。声明式通道（`[runtime] deploy_files`、
+> `runtime_search_dirs`）不受影响。
+
+**调试信息会被剥离，发布者的路径随之消失。** 未 strip 的产物携带 DWARF，而
+DWARF 携带发布者源码树与构建目录的绝对路径。具体剥离什么取决于产物**是什么**
+—— 这是 dh_strip 的分档方式，而其中归档那一行是要紧的：
+
+| 产物 | strip 参数 | 不能剥得更彻底的原因 |
 |---|---|---|
-| 可执行文件 | `--strip-all` | 没有人链接它 |
+| 可执行文件 | `--strip-all` | 没有谁会链接它 |
 | 共享库 | `--strip-unneeded` | 保留 `.dynsym` —— 那**就是**导出表 |
-| 静态归档 | `--strip-debug --enable-deterministic-archives` | `--strip-all` 会删掉归档的**符号索引**,消费方链接时报 `archive has no index; run ranlib to add one` |
+| 静态归档 | `--strip-debug --enable-deterministic-archives` | `--strip-all` 会删掉归档的**符号索引**，消费方链接时随即报出 `archive has no index; run ranlib to add one` |
 
-三档都会去掉 `.comment` 与 `.note`。段删除按**精确名字**匹配,所以
-`.note.gnu.build-id` 会保留,`--add-gnu-debuglink` 仍然有东西可配对。
+三档都会去掉 `.comment` 与 `.note`。段的删除按**精确名字**匹配，因此
+`.note.gnu.build-id` 会被保留，`--add-gnu-debuglink` 仍然有东西可以配对。
 
-`--no-strip`(或 `[pack] strip = false`)按构建原样发货。
-`--debug-symbols <目录>` 则是分离而不是丢弃:写出 `<目录>/<产物>.debug`,
-并给发货的产物加上指向它的 `.gnu_debuglink` —— 调试器与 `debuginfod` 认这个。
+`--no-strip`（或 `[pack] strip = false`）按构建原样发货。
+`--debug-symbols <dir>` 则是分离而不是丢弃：写出 `<dir>/<产物>.debug`，并给
+发货的产物加上指向它的 `.gnu_debuglink` —— 这正是调试器与 `debuginfod` 所
+遵循的约定。
 
-> `[pack] strip` 不是 `[profile.<name>].strip`。后者是给**链接**加 `-s`,
-> 既碰不到静态归档、也无法分离出任何东西;前者管的是**包里带什么**。
-> 两个不同的决定,两个不同的名字。
+> `[pack] strip` 不是 `[profile.<name>].strip`。后者给**链接**加上 `-s`，
+> 既碰不到静态归档，也无法分离出任何东西；前者管的是**包里带什么**。两个不同
+> 的决定，两个不同的名字。
 
-**图构建出的东西在每条把调试信息放在映像内的行上都会被剥离;来自 store 或宿主的库不会**
-(mcpp 2026.9.16.1+)。规则是 dh_strip 的「包剥离自己构建的东西」,覆盖范围:
+**图构建出来的东西，在每一条把调试信息放在映像内部的行上都会被剥离；来自
+store 或宿主的库不会**（mcpp 2026.9.16.1+）。规则是 dh_strip 的「一个包
+只剥离它自己构建的东西」，覆盖范围如下：
 
 | 暂存的文件 | 是否剥离 | 原因 |
 |---|---|---|
-| 程序 | 是,按可执行文件;在 Android 行上按共享库,因为那里的程序就是共享库 | 本次构建编译了它 |
-| 图中 `SharedLibrary` 链接单元产出的共享库 | 是,`--strip-unneeded` | 本次构建从源码编译了它 |
-| 工具链自身运行时的暂存副本(NDK 的 `libc++_shared.so`) | 是,`--strip-unneeded` | 树里的副本不是共享载荷;Android Gradle 插件剥离同一个文件 |
-| 来自 store、宿主的库,或包部署的预构建库 | 否 | 其字节属于其发布者,供应商的库可能带签名 |
+| 程序 | 是，按可执行文件剥离；在 Android 行上按共享库剥离，因为那里的程序本身就是共享库 | 本次构建编译了它 |
+| 图中 `SharedLibrary` 链接单元产出的共享库 | 是，`--strip-unneeded` | 本次构建从源码编译了它 |
+| 工具链自身运行时的暂存副本（NDK 的 `libc++_shared.so`） | 是，`--strip-unneeded` | 树里的副本不是那份共享载荷本身；Android Gradle 插件也会剥离同一个文件 |
+| 来自 store、宿主，或某个包部署的预构建库 | 否 | 它的字节属于它的发布者，供应商的库可能带着签名 |
 
-Mach-O 与 MSVC PE 的调试信息放在映像之外,因此那里什么都不剥离,`Packing` 行只在确实剥离
-的行上写「stripped」。`--no-strip` 与 `--debug-symbols` 管辖每一个被剥离的文件。自己暂存库的
-构建程序通过 `mcpp::pack_strip()` 与 `mcpp::pack_debug_symbols_dir()` 读到同一个决定
-([30 —— build.mcpp](30-build-mcpp.md))
+Mach-O 与 MSVC 的 PE 把调试信息放在映像之外，因此那里什么都不剥离，`Packing`
+这一行只在确实发生剥离的那一行上写「stripped」。`--no-strip` 与
+`--debug-symbols` 管辖每一个被剥离的文件。自己暂存库的构建程序，通过
+`mcpp::pack_strip()` 与 `mcpp::pack_debug_symbols_dir()` 读到同一个决定
+（[30 —— build.mcpp](30-build-mcpp.md)）。
 
 ## 产物布局
 
-tarball 内容包在一个顶层目录里,该目录的名字与 tarball 文件名(去掉
-`.tar.gz`)保持一致 —— 这样图形界面"右键解压"和命令行 `tar -xzf` 都
-得到同一个自包含的目录,不会把内容散到当前路径。
+tarball 的内容包在一个顶层目录里，该目录的名字与 tarball 文件名（去掉
+`.tar.gz` 后）保持一致 —— 这样图形界面的「右键解压」和命令行的 `tar -xzf`
+都会得到同一个自包含的目录，而不会把内容散落到当前路径下。
 
-**闭包会被记录,不完整的闭包使归档被拒绝**(mcpp 2026.9.14.2+)。暂存树旁边的
-`<tree>.stage-manifest` 列出闭包解析过的每一个库名:树里携带的库给出其暂存路径,
-目标自己提供的库记为 `platform`,哪里都找不到的记为 `unresolved`(行格式见
-[50](50-machine-output.md#暂存清单))。只要有一个名字是 unresolved,
-`--format tar` 与 `--format dir` 就失败并点名它,因为缺了这个库的树在安装处无法启动;
-被分派的格式仍然收到这棵树,并带 `closure = not-walked`。目标提供、而本机没有的库,
-写进 `[pack.bundle-project] also_skip`。不打包任何东西的模式(`system`、`static`)
-不记录闭包。
+**闭包会被记录，一个不完整的闭包会使归档被拒绝**（mcpp 2026.9.14.2+）。
+暂存树旁边的 `<tree>.stage-manifest` 列出闭包解析过的每一个库名：树里携带的
+库给出其暂存路径，目标机自己提供的库记为 `platform`，哪里都找不到的记为
+`unresolved`（行格式见 [50](50-machine-output.md#暂存清单)）。只要有一个名字
+是 unresolved，`--format tar` 与 `--format dir` 就会失败并点名它，因为一棵
+缺了这个库的树在安装处无法启动；被分派的格式仍然会收到这棵树，并带上
+`closure = not-walked`。目标机提供、而本机没有的库，写进
+`[pack.bundle-project] also_skip`。不打包任何东西的 mode（`system`、
+`static`）不记录闭包。
 
 ### Mode `static`
 
 ```
 target/dist/myapp-0.1.0-x86_64-linux-musl-static.tar.gz
 └── myapp-0.1.0-x86_64-linux-musl-static/
-    ├── bin/myapp                ← 全静态 ELF(无 PT_INTERP / RUNPATH)
-    ├── myapp                    ← 顶层入口(thin shell wrapper,可直接执行 ./myapp)
-    ├── README.md                ← 自动从项目根目录拷贝
+    ├── bin/myapp                ← fully static ELF (no PT_INTERP / RUNPATH)
+    ├── myapp                    ← top-level entry point (thin shell wrapper, run ./myapp directly)
+    ├── README.md                ← copied automatically from the project root
     └── LICENSE
 ```
 
-### Mode `vendored`(默认;别名:`bundle-project`)
+### Mode `vendored`（默认；别名：`bundle-project`）
 
 ```
 target/dist/myapp-0.1.0-x86_64-linux-gnu.tar.gz
 └── myapp-0.1.0-x86_64-linux-gnu/
-    ├── bin/myapp                ← 动态链接,RUNPATH=$ORIGIN/../lib
+    ├── bin/myapp                ← dynamically linked, RUNPATH=$ORIGIN/../lib
     │                                PT_INTERP=/lib64/ld-linux-x86-64.so.2
     ├── lib/
-    │   ├── libcurl.so.4         ← 项目第三方依赖
+    │   ├── libcurl.so.4         ← project third-party dependency
     │   ├── libssl.so.3
     │   └── ...
-    ├── myapp                    ← 顶层入口
+    ├── myapp                    ← top-level entry point
     ├── README.md
     └── LICENSE
 ```
 
-跳过列表参考
+跳过列表遵循
 [PEP 600 / manylinux2014](https://peps.python.org/pep-0600/) ——
-`libc`、`libm`、`libstdc++`、`libgcc_s`、`ld-linux-*` 等基础库默认
-假设目标系统已具备,不打包进 tarball。
+默认假定目标系统已经具备 `libc`、`libm`、`libstdc++`、`libgcc_s`、
+`ld-linux-*` 一类基础库，因此不把它们打进 tarball。
 
-### Mode `self-contained`(别名:`bundle-all`)
+### Mode `self-contained`（别名：`bundle-all`）
 
 ```
 target/dist/myapp-0.1.0-x86_64-linux-gnu-bundle-all.tar.gz
 └── myapp-0.1.0-x86_64-linux-gnu-bundle-all/
     ├── bin/myapp
     ├── lib/
-    │   ├── ld-linux-x86-64.so.2  ← 完整 loader 与 libc
+    │   ├── ld-linux-x86-64.so.2  ← complete loader and libc
     │   ├── libc.so.6
     │   ├── libstdc++.so.6
     │   ├── libgcc_s.so.1
-    │   └── ...项目依赖
-    ├── myapp                     ← 双入口之一
-    ├── run.sh                    ← 双入口之二(内容相同)
+    │   └── ...project dependencies
+    ├── myapp                     ← one of two entry points
+    ├── run.sh                    ← the other entry point (identical contents)
     ├── README.md
     └── LICENSE
 ```
 
-`-o foo.tar.gz` 时顶层目录名也会变成 `foo`(包名 - 目录名 始终一致)。
+带 `-o foo.tar.gz` 时，顶层目录名也会变成 `foo`（包名与目录名始终保持一致）。
 
-ELF 规范限制 `PT_INTERP` 不能使用 `$ORIGIN`,因此 `self-contained` 模式
-通过 `run.sh`(及顶层同名 wrapper)以绝对路径方式调用 loader:
+ELF 规范禁止 `PT_INTERP` 使用 `$ORIGIN`，因此在 `self-contained` 模式下，
+loader 经由 `run.sh`（以及顶层的同名 wrapper）以绝对路径的方式被调用：
 
 ```sh
 exec "$here/lib/ld-linux-x86-64.so.2" --library-path "$here/lib" "$here/bin/myapp" "$@"
 ```
 
-上面的布局与 wrapper 以 x86_64 为例。打包器会按 target 推导 loader 名称；aarch64
-对应 `ld-linux-aarch64.so.1`。
+上面的布局与 wrapper 以 x86_64 为例。打包器会按 target 推导 loader 的名字；
+在 aarch64 上它是 `ld-linux-aarch64.so.1`。
 
-#### 经 bundled loader 启动时 `/proc/self/exe` 的取值
+#### 经由内置 loader 启动时 `/proc/self/exe` 的取值
 
-「由 loader 启动」有一个上述布局看不出的后果:内核会把 `/proc/self/exe`
-指向 **loader** 而非目标程序;`/proc/self/cmdline` 中也混入了
-`--library-path`。于是所有「在可执行文件旁边找资源」的逻辑都会解析到 `lib/`
-而不是 bundle 根目录——而且是**静默**的。实际表现是:GUI 框架找不到字体因而
-文字渲染空白、`assets/` 目录看起来不存在、随包分发的辅助二进制定位失败。
-按 `/proc/self/cmdline` 解析 argv 的代码则会拿到混入 loader 参数的结果。
+「由 loader 启动」带来一个上述布局看不出的后果：内核会把 `/proc/self/exe`
+设为指向 **loader**，而不是程序本身；`/proc/self/cmdline` 里也混入了
+`--library-path` 这个参数。于是每一处「到可执行文件旁边找资源」的逻辑，解析
+出来的都是 `lib/` 而不是 bundle 根目录 —— 而且是**静默**发生的。实际表现
+是：GUI 工具箱因为找不到字体而渲染出空白文字、一个 `assets/` 目录看起来像是
+缺失了、随包分发的辅助二进制找不到自己的位置。从 `/proc/self/cmdline` 解析
+`argv` 的代码，拿到的会是混入了 loader 参数的结果。
 
-这只影响 `self-contained`。`vendored`、`system`、`static` 的 `PT_INTERP`
-都能被内核直接使用,`/proc/self/exe` 是正确的。
+这只影响 `self-contained`。`vendored`、`system` 与 `static` 携带的都是内核
+能直接使用的 `PT_INTERP`，`/proc/self/exe` 在那三种模式下是正确的。
 
-wrapper 为此导出 **`MCPP_BUNDLE_DIR`**(bundle 根目录)。优先用它,只在未设置
-时回退:
+wrapper 为此导出了 **`MCPP_BUNDLE_DIR`**（bundle 根目录）。应优先按它解析，
+只在它未设置时才回退：
 
 ```c
-const char *base = getenv("MCPP_BUNDLE_DIR");   /* 由 run.sh 设置 */
+const char *base = getenv("MCPP_BUNDLE_DIR");   /* set by run.sh */
 if (!base) {
-    /* 不是经 wrapper 启动的 —— 此时 /proc/self/exe 可信 */
+    /* not launched through the wrapper — /proc/self/exe is trustworthy */
 }
 ```
 
-如果应用本身改不了(比如第三方 GUI 框架自己做解析),改用 `--mode vendored`:
-它把 `PT_INTERP` 重指到宿主 loader,`/proc/self/exe` 正常,代价是要求宿主
-glibc 不低于构建时所用的那份。
+如果应用本身改不了 —— 比如某个第三方 GUI 框架自己做路径解析 —— 改用
+`--mode vendored`。它把 `PT_INTERP` 重新指向宿主的 loader，代价是要求宿主的
+glibc 版本不低于产物构建时所用的那份。
 
-### WebAssembly(`wasm32-emscripten`):词干家族
+### WebAssembly（`wasm32-emscripten`）：词干家族
 
 ```
 target/dist/myapp-0.1.0-wasm32-emscripten.tar.gz
 └── myapp-0.1.0-wasm32-emscripten/
-    ├── bin/myapp.js              ← 启动器;runner 执行的文件
-    ├── bin/myapp.wasm            ← 链接的隐式输出,随它一起暂存
-    ├── bin/myapp.data            ← 只在链接携带 --preload-file 时出现
+    ├── bin/myapp.js              ← the launcher; the file a runner executes
+    ├── bin/myapp.wasm            ← implicit output of the link, staged with it
+    ├── bin/myapp.data            ← present only when the link carries --preload-file
     ├── README.md
     └── LICENSE
 ```
 
-打包程序暂存启动器,以及同一次链接在它旁边写出的每一个 `myapp.<任意>` ——
-词干家族。`myapp.wasm` 是必需的:链接边把它声明为隐式输出,它的缺席说明
-构建目录与图对不上,`mcpp pack` 因此拒绝,而不是暂存一个没有模块的启动器。
-`myapp.data` 以及 emcc 用同一词干写出的其余文件(`myapp.worker.js`、
-`myapp.wasm.map`)是可选的,链接产出了就跟着走。
+打包器暂存启动器，以及同一次链接在它旁边写出的每一个 `myapp.<任意后缀>` ——
+即词干家族。`myapp.wasm` 是必需的：链接边把它声明为隐式输出，它的缺席说明
+构建目录与图对不上，`mcpp pack` 因此会拒绝，而不是暂存一个没有模块的启动器。
+`myapp.data` 以及 emcc 用同一个词干写出的其余文件（`myapp.worker.js`、
+`myapp.wasm.map`）是可选的，链接产出了才会跟着走。
 
-### Windows(PE):产物为 `.zip`,DLL 与 `.exe` 同目录
+### Windows（PE）：产物是一个 `.zip`，DLL 与 `.exe` 同目录
 
-Windows 目标产出的是 **`.zip`** 而不是 `.tar.gz`,并且是扁平布局:
+一个 Windows target 产出的是一个 **`.zip`**，不是 `.tar.gz`，并且是扁平
+布局：
 
 ```
 target/dist/myapp-0.1.0-x86_64-pc-windows-msvc.zip
 └── myapp-0.1.0-x86_64-pc-windows-msvc/
     ├── myapp.exe
-    ├── vcruntime140.dll        ← 仅在 cxx_runtime = "toolchain-coupled" 时
-    ├── mydep.dll               ← 第三方依赖
+    ├── vcruntime140.dll        ← only under cxx_runtime = "toolchain-coupled"
+    ├── mydep.dll               ← third-party dependencies
     ├── README.md
     └── LICENSE
 ```
 
-没有 `bin/` + `lib/` 的分层,也没有入口 wrapper —— 这两点都不是风格选择。
-Win32 loader 解析 DLL 的第一顺位就是**可执行文件所在目录**,而 PE 没有
-`RUNPATH` 可以指向别处,所以"放在 `.exe` 旁边"**就是** ELF 上
-`$ORIGIN/../lib` 所提供的那个机制。
+没有 `bin/` + `lib/` 的分层，也没有入口 wrapper —— 这两点都不是风格选择。
+Win32 的 loader 从**可执行文件所在目录**解析一个 DLL；PE 没有 `RUNPATH` 可以
+指向别处，因此「放在 `.exe` 旁边」**就是** ELF 上 `$ORIGIN/../lib` 提供的
+那个机制。
 
 **Windows 自己的 DLL 永远不会被打进包里** —— `kernel32.dll`、`ntdll.dll`、
-`ucrtbase.dll`、`api-ms-win-*` API set。带一份系统组件的私有拷贝不是"包变大
-了",而是**程序坏了**(进程里出现了两份本应唯一的东西),而 Microsoft 的再分发
-条款也从另一侧说了同一件事。`[pack.bundle-project] force_bundle` 仍然可以覆盖
-这条,和它覆盖 ELF 跳过表一样。
+`ucrtbase.dll`，以及 `api-ms-win-*` 一族 API set。携带一份操作系统组件的私有
+拷贝，不是让包变大，而是**让程序坏掉**（进程里出现了两份本应唯一的东西），
+Microsoft 的再分发条款也从另一个角度说了同一件事。`[pack.bundle-project]
+force_bundle` 仍然可以覆盖这条规则，就像它能覆盖 ELF 的跳过列表一样。
 
-`vcruntime140.dll` / `msvcp140.dll` **不是** Windows 自己的:它们属于 MSVC
-toolset,就像 `libstdc++.so` 属于 gcc。它们要不要跟着产物走,由 `cxx_runtime`
-决定(见 `docs/zh/04-mcpp-toml.md`),不由这张表决定 —— 而 `mcpp pack` 会拒绝
-那些无法兑现契约的组合:
+`vcruntime140.dll` 与 `msvcp140.dll` **不是** Windows 自己的：它们属于 MSVC
+toolset，正如 `libstdc++.so` 属于 gcc。它们要不要随产物一起走，由
+`cxx_runtime` 决定（见 `docs/04-mcpp-toml.md`），不由上面这张表决定 ——
+而 `mcpp pack` 会拒绝那些无法兑现契约的组合：
 
 ```
-$ mcpp pack --mode system          # 且 cxx_runtime = "toolchain-coupled"
+$ mcpp pack --mode system          # with cxx_runtime = "toolchain-coupled"
 error: cxx_runtime = "toolchain-coupled" and --mode system contradict each other.
 ```
 
-#### 在 Linux / macOS 上给 Windows 打包
+#### 在 Linux 或 macOS 上给 Windows 打包
 
-这是可以的,而且不是什么特殊模式 —— 指定 Windows 目标构建,然后打包即可:
+这是可行的，而且不是什么特殊模式 —— 只需针对 Windows target 构建，然后打包：
 
 ```bash
-mcpp pack --target x86_64-windows-gnu     # 在 Linux 宿主上
+mcpp pack --target x86_64-windows-gnu     # from a Linux host
 ```
 
-`mcpp pack` 以前直接拒绝 Windows。真正的原因不是打包工具:ELF 的依赖闭包是靠
-**把产物跑起来**(`LD_TRACE_LOADED_OBJECTS`)求出来的,所以它既跨不了 OS 也跨
-不了架构。PE 的闭包改为从文件的导入表里**读**出来,于是不需要执行任何东西,
-打包宿主也就自由了。压缩包本身也由 mcpp 自己写,理由相同 —— 没有哪个 zip 工具
-在每个宿主上都存在。
+`mcpp pack` 曾经直接拒绝 Windows。真正的原因不在打包工具：ELF 的依赖闭包是
+靠**把产物跑起来**（用 `LD_TRACE_LOADED_OBJECTS`）求出来的，这既跨不了操作
+系统，也跨不了架构。PE 的闭包改为直接从文件的导入表里**读**出来，因此不需要
+执行任何东西，打包所在的宿主也就自由了。压缩包本身同样由 mcpp 自己写出，理由
+相同 —— 不是每个宿主上都存在某个 zip 工具。
 
-有两点值得知道:
+有两点值得知道：
 
-- 条目是 **stored(不压缩)** 的,所以 Windows 包的体积约等于其内容之和。压缩
-  是体积优化而不是正确性问题,目前尚未实现。
-- 压缩包是**确定性**的:不读取任何时间戳,同一棵树打两次字节一致,公布的校验和
-  才有意义。
+- 条目是**存储而非压缩**的，因此 Windows 包的体积大致等于其内容之和。压缩是
+  体积上的优化，不是正确性问题，目前尚未实现。
+- 压缩包是**确定性的**：不读取任何时间戳，因此同一棵树打两次包字节完全一致，
+  公布出去的校验和才有意义。
 
-反方向 —— 在 Windows 上给 Linux 产物打包 —— 仍然不支持:ELF 程序的闭包要由目标
-自己的动态链接器解析,而 Windows 宿主没有办法运行它。Mach-O 程序的闭包是从文件里
-读出来的,所以 macOS 程序在任何宿主上都能打包。
+反方向 —— 在 Windows 上给 Linux 产物打包 —— 仍然不支持：ELF 程序的闭包要靠
+目标自己的动态链接器解析，而 Windows 宿主没有办法运行它。Mach-O 程序的闭包是
+从文件里读出来的，因此一个 macOS 程序可以在任何宿主上打包。
 
-### macOS(Mach-O):dylib 与程序同目录
+### macOS（Mach-O）：dylib 与程序放在同一目录
 
 ```
 target/dist/myapp-0.1.0-aarch64-macos.tar.gz
 └── myapp-0.1.0-aarch64-macos/
     ├── bin/myapp
-    ├── bin/libmydep.dylib      ← 依赖的 dylib,与程序同目录
-    ├── myapp                   ← 入口 wrapper
+    ├── bin/libmydep.dylib      ← a dependency's dylib, beside the program
+    ├── myapp                   ← entry-point wrapper
     ├── README.md
     └── LICENSE
 ```
 
-Mach-O 程序的闭包从它的 load command 里读出(mcpp 2026.9.14.2+),所以打包时不运行
-任何东西。它的 dylib 暂存在它旁边的 `bin/` 中,而图内构建的 dylib 的消费者链接时带的
-`@loader_path` rpath 本来就指向那里:不编辑任何 load command,不重新签名,也不 strip
-这个程序。
+Mach-O 程序的闭包从它的 load command 里读出（mcpp 2026.9.14.2+），因此打包
+时不运行任何东西。它的 dylib 暂存在它旁边的 `bin/` 下，这也正是一个图内构建的
+dylib 的消费者，其链接所带的 `@loader_path` rpath 本就会查找的位置：不编辑
+任何 load command，不重新签名，也不 strip 这个程序。
 
-一个被需要的名字,在加载器能把它解析到程序所在目录时才会被暂存:
+一个被需要的名字，只有在加载器能把它解析到程序所在目录时才会被暂存：
 
-| 名字 | 处理 |
+| 名字 | 处理方式 |
 |---|---|
-| `/usr/lib/…`、`/System/Library/…` | 不暂存;由操作系统提供 |
-| `@rpath/<file>` | 需要它的映像或程序本身有一条恰为 `@loader_path` 或 `@executable_path` 的 rpath 时暂存 |
-| `@loader_path/<file>`、`@executable_path/<file>` | 暂存到该路径,该路径必须留在程序所在目录之内 |
+| `/usr/lib/…`、`/System/Library/…` | 不暂存；由操作系统提供 |
+| `@rpath/<file>` | 当需要它的映像或程序本身，有一条恰好等于 `@loader_path` 或 `@executable_path` 的 rpath 时暂存 |
+| `@loader_path/<file>`、`@executable_path/<file>` | 暂存到该路径，该路径必须留在程序所在目录之内 |
 
-其他名字都使闭包不完整,`tar` 与 `dir` 拒绝并点名它。最常见的是操作系统目录之外的
-绝对 install name:加载器在每台机器上都从那个路径读取它,不论树里带了什么。
-`--mode system` 与 `--mode static` 在这一行上不打包任何东西,与 PE 相同。
-`kind = "lib"` / `"shared"` 目标走库打包路线,不受影响。
+任何其他名字都会使闭包不完整，`tar` 与 `dir` 会拒绝并点名它。最常见的情形是
+落在操作系统目录之外的绝对 install name：加载器会在每一台机器上都从那个路径
+去读，无论树里携带了什么。`--mode system` 与 `--mode static` 在这一行上不
+打包任何东西，与 PE 相同。`kind = "lib"` / `"shared"` 的 target 走库打包
+路线，不受影响。
 
-### Android:应用目标文件与它的闭包在 `lib/` 下
+### Android：应用目标文件与它的闭包在 `lib/` 下
 
 ```
 target/dist/myapp-0.1.0-x86_64-linux-android/
-├── lib/libmyapp.so             ← 应用目标文件
-├── lib/libmydep.so             ← 依赖的共享库
-├── lib/libc++_shared.so        ← NDK 的 C++ 运行时,目标文件需要它时才有
-└── bin/<to>/…                  ← `[runtime] deploy` 放置的文件
+├── lib/libmyapp.so             ← the application object
+├── lib/libmydep.so             ← a dependency's shared library
+├── lib/libc++_shared.so        ← the NDK's C++ runtime, when the object needs it
+└── bin/<to>/…                  ← files `[runtime] deploy` placed
 ```
 
-在 Android 行上,应用是暂存在 `lib/` 下的共享目标文件,它的闭包从文件里读出并暂存在
-它旁边(mcpp 2026.9.14.2+)。设备提供的名字不暂存:即出现在该 API level 桩目录中的
-名字,这个目录由 mcpp 向这一行自己的编译器询问得到(编译器找到 `libc.so` 的目录)——
-`libc.so`、`libm.so`、`libdl.so`、`liblog.so` 以及其他平台库。其余每个名字都必须在
-链接用过的目录中解析到:构建的输出目录、图中各包的 `[runtime] library_dirs` 与
-`link_library_dirs`,以及编译器的库搜索路径(`libc++_shared.so` 就在其中)。
-哪里都解析不到的名字使 `tar` 与 `dir` 拒绝,并点名它和搜索过的目录。
+在 Android 行上，应用是一个暂存在 `lib/` 下的共享目标文件，它的闭包从文件中
+读出并暂存在它旁边（mcpp 2026.9.14.2+）。设备提供的名字不会被暂存：即出现在
+该 API level 桩目录中的名字，这个目录由 mcpp 向该行自己的编译器询问得到（即
+编译器找到 `libc.so` 的那个目录）—— `libc.so`、`libm.so`、`libdl.so`、
+`liblog.so` 以及其他平台库。其余每一个名字都必须能在链接用过的某个目录中
+解析到：构建的输出目录、图中各包的 `[runtime] library_dirs` 与
+`link_library_dirs`，以及编译器的库搜索路径（`libc++_shared.so` 就在其中）。
+哪里都解析不到的名字会使 `tar` 与 `dir` 拒绝，并点名它以及被搜索过的那些
+目录。
 
-给出多个 `--target` 三元组时,每条腿暂存在 `lib/<abi>/` 下,各带自己的闭包。
-`--mode` 不适用于这一行:设备恰好提供平台库,所以既没有可以留给宿主的库集合,
-也没有需要携带的加载器。
+给出多个 `--target` 三元组时，每条腿暂存在 `lib/<abi>/` 下，各自带着自己的
+闭包。`--mode` 不适用于这一行：设备恰好提供了平台库，因此既没有可以留给宿主
+的库集合，也没有需要携带的 loader。
 
 ## 配置项
 
-打包行为通过 `mcpp.toml` 中的 `[pack]` 节配置,常用字段如下:
+打包行为通过 `mcpp.toml` 中的 `[pack]` 节配置，常用字段如下：
 
 ```toml
 [pack]
-default_mode  = "static"            # 覆盖裸 `mcpp pack` 的正常 vendored 默认值
-strip         = true                # 默认值。false = 按构建原样发货
-debug_symbols = "dist/debug"        # 把调试信息分离到这里,而不是丢弃
-include       = ["share/**", "config/*.toml"]   # 额外打包的文件
+default_mode  = "static"            # override the normal vendored default for bare `mcpp pack`
+strip         = true                # default. false ships the artifacts as built
+debug_symbols = "dist/debug"        # separate the debug info here instead of discarding it
+include       = ["share/**", "config/*.toml"]   # extra files to bundle
 exclude       = ["debug/**"]
 
-# 微调 vendored 的过滤策略。配置键保留既有的 `bundle-project` 拼写。
+# Fine-tune the vendored filtering policy. The configuration key keeps its
+# established `bundle-project` spelling.
 [pack.bundle-project]
-also_skip    = ["libcustom.so"]     # 假定目标系统已具备的库
-force_bundle = ["libfoo.so"]        # 即使命中 PEP 600 名单也强制打包
+also_skip    = ["libcustom.so"]     # libraries assumed to exist on the target system
+force_bundle = ["libfoo.so"]        # bundle even if matched by the PEP 600 list
 ```
 
-`[pack].default_mode` 当前接受既有 manifest 拼写 `static`、`bundle-project` 和
-`bundle-all`; `system` 通过 `mcpp pack --mode system` 显式选择。CLI 输入同时接受
-上文的规范名称和兼容名称。
+`[pack].default_mode` 当前接受既有的 manifest 拼写 `static`、
+`bundle-project` 与 `bundle-all`；`system` 这一 mode 只能通过
+`mcpp pack --mode system` 显式选择。CLI 输入同时接受上文的规范名称与兼容
+名称。
 
-`static` 模式还需在 `[target.<triple>]` 中配置 musl 工具链,完整写法
-参见 [`examples/03-pack-static`](../../examples/03-pack-static/) 的 `mcpp.toml`。
+`static` mode 还需要在 `[target.<triple>]` 下配置一套 musl 工具链；完整写法
+参见 [`examples/03-pack-static`](../../examples/03-pack-static/) 中的
+`mcpp.toml`。
 
 ## 待支持
 
-当前 `.zip` 之外的 Windows DLL 分发在规划中。
-
-`.deb`、`.rpm`、AppImage、`.msi` 这些分发格式**不在**这份清单上,而这是一个决定而不是
-一处遗漏:它们住在包里,经 `--format <name>` 到达用户,理由见上一节。`[pack]` 的内建
-模式不需要再添任何新成员。
+当前 `.zip` 之外的 Windows DLL 分发方式在规划中。
 
-本文档随 `mcpp pack` 实现演进,最新选项以 `mcpp pack --help` 为准。
+`.deb`、`.rpm`、AppImage、`.msi` 这些分发格式**不在**这份清单上，而这是一个
+决定而不是一处遗漏：它们住在各自的包里，经由 `--format <name>` 到达用户，
+理由见上一节。`[pack]` 内建的这几种 mode 不需要再添任何新成员。
 
+本文档随 `mcpp pack` 的实现演进；最新选项以 `mcpp pack --help` 为准。
diff --git a/docs/zh/11-publishing-a-library.md b/docs/zh/11-publishing-a-library.md
index 7c5428f6b..8891333d8 100644
--- a/docs/zh/11-publishing-a-library.md
+++ b/docs/zh/11-publishing-a-library.md
@@ -2,71 +2,71 @@
 
 [English](../11-publishing-a-library.md) | **简体中文**
 
-**读者:**希望自己的包能被别人写进 `[dependencies]` 的库作者。
+**读者：** 希望自己的包能被别人写进 `[dependencies]` 的库作者。
 
-**本章回答的那一个问题:**从打好 tag 到成为一个可解析的包,要走哪些步骤,以及它们
-必须按什么顺序发生。
+**本章回答的那一个问题：** 从打好一个 tag 到成为一个可解析的包，要走过哪些步骤，
+以及它们必须按什么顺序发生。
 
-**不在这里:**什么使两个包成为同一个包 —— [SPEC-001](../specs/package-identity.md);
-以及交付编译产物,那是 [12](12-binary-distribution.md)。在此之前:
-[10 —— 发布打包](10-pack-and-release.md)。
+**不在这里：** 什么使两个包成为同一个包 —— [SPEC-001](../specs/package-identity.md)；
+以及交付编译好的产物，那是 [12](12-binary-distribution.md)。在此之前：
+[10 —— 打包一个应用](10-pack-and-release.md)。
 
-一个库如何变成 `[dependencies]` 可以写出来的东西。这是**库作者**的链路;
-[92 - 发布 mcpp](92-release.md) 讲的是发布 mcpp 自身,
-[10 - 发布打包](10-pack-and-release.md) 讲的是 `mcpp pack` 打包应用。
+一个库如何变成 `[dependencies]` 能够写出来的东西。这是**库作者**的链路；
+[92 —— 发布 mcpp](92-release.md) 讲的是发布 mcpp 自身，
+[10 —— 打包与发布](10-pack-and-release.md) 讲的是 `mcpp pack` 打包一个应用。
 
 ## 发布顺序
 
 ```
-库仓库             merge → git tag → GitHub 自动生成 tag tarball
+the library repo          merge → git tag → GitHub auto-generates the tag tarball
       ↓
-gitcode 镜像       逐字节相同的一份拷贝,供 CN 区
+gitcode mirror     a byte-identical copy, for the CN region
       ↓
-mcpplibs/mcpp-index   pkgs/<x>/<name>.lua —— GLOBAL + CN 双 URL + sha256
-      ↓            publish-artifact.yml 推出内容哈希 artifact
+mcpplibs/mcpp-index   pkgs/<x>/<name>.lua — GLOBAL + CN URLs + sha256
+      ↓            publish-artifact.yml pushes a content-hash artifact
       ↓
-消费方             在自己的 mcpp.toml 里升版本
+consumers          bump the version in their mcpp.toml
 ```
 
-每一支箭头都是一道关。漏掉任何一道都不会当场报错 —— 它会在几小时后,
-以别人构建里的 "dependency not found" 或一个 404 的形式出现。
+每一支箭头都是一道关。漏掉任何一道都不会当场报错，而是在几小时后，以别人构建里
+一句 `dependency not found` 或一个 404 的形式出现。
 
 ## 1. 打 tag
 
-`mcpp.toml` 里的版本必须与 tag 一致。GitHub 会自动生成
-`archive/refs/tags/<tag>.tar.gz`,**那个 tarball 就是产物**,不需要另行上传。
+`mcpp.toml` 里的版本必须与 tag 一致。GitHub 自动生成
+`archive/refs/tags/<tag>.tar.gz`，**那个 tarball 就是产物**，不需要另行上传。
 
 ```bash
 git tag 0.0.48 && git push origin 0.0.48
 curl -fsSL -o pkg-0.0.48.tar.gz \
   https://github.com/<owner>/<repo>/archive/refs/tags/0.0.48.tar.gz
-sha256sum pkg-0.0.48.tar.gz          # ← 索引里要写的摘要
+sha256sum pkg-0.0.48.tar.gz          # ← the digest the index will carry
 ```
 
-tarball 解开是 `<repo>-<tag>/`,mcpp 会在这层包装目录里找 `mcpp.toml`。
-仓库自带 `mcpp.toml` 时,索引条目不需要 `mcpp` 字段。
+tarball 解开后是 `<repo>-<tag>/`，mcpp 在这层包装目录里查找 `mcpp.toml`。仓库自带
+`mcpp.toml` 时，索引条目不需要 `mcpp` 字段。
 
 ## 2. 镜像到 gitcode
 
-CN 条目必须是 GitHub tarball 的**逐字节拷贝**,只改文件名。否则两个区域对同一个
-`sha256` 的理解就不一致了。
+CN 条目必须是 GitHub tarball 的**逐字节拷贝**，只改文件名。否则两个区域对同一个
+`sha256` 的理解就不一致。
 
 ```bash
 gtc release publish mcpp-res/<name> --tag 0.0.48 --asset pkg-0.0.48.tar.gz
 ```
 
-然后**验证**它 —— 上传报成功和资源真的能取到,不是一回事:
+随后验证它，因为上传报告成功，与资源真的能取到，不是同一回事：
 
 ```bash
-# 用 GET,绝不用 HEAD —— gitcode 对 HEAD 返回 401,对 GET 返回 302 → CDN 200
+# GET, never HEAD — gitcode answers HEAD with 401 and GET with 302 → CDN 200
 curl -fsSL -o cn.tar.gz \
   https://gitcode.com/mcpp-res/<name>/releases/download/0.0.48/pkg-0.0.48.tar.gz
-cmp cn.tar.gz pkg-0.0.48.tar.gz      # 必须一致,而不只是"存在"
+cmp cn.tar.gz pkg-0.0.48.tar.gz      # must be identical, not merely present
 ```
 
-## 3. 加索引条目
+## 3. 添加索引条目
 
-在 `mcpplibs/mcpp-index` 的 `pkgs/<首字母>/<name>.lua`:
+在 `mcpplibs/mcpp-index` 的 `pkgs/<首字母>/<name>.lua` 中：
 
 ```lua
 ["0.0.48"] = {
@@ -74,82 +74,83 @@ cmp cn.tar.gz pkg-0.0.48.tar.gz      # 必须一致,而不只是"存在"
         GLOBAL = "https://github.com/<owner>/<repo>/archive/refs/tags/0.0.48.tar.gz",
         CN     = "https://gitcode.com/mcpp-res/<name>/releases/download/0.0.48/pkg-0.0.48.tar.gz",
     },
-    sha256 = "<第 1 步得到的摘要>",
+    sha256 = "<the digest from step 1>",
 },
 ```
 
 **三个平台块都要写** —— `linux`、`macosx`、`windows`。源码 tarball 在每个平台上是
-同样的字节;只写了其中一个,在另外两个平台上会以 "no such version" 失败,
-而那读起来像是消费方 manifest 里打错了字。
+同样的字节；只写在其中一个平台块里，会在另外两个平台上以 `no such version` 失败，
+读起来像是消费方 manifest 里打错了字。
 
 ## 4. 等待 artifact
 
-**索引是 artifact,不是 git clone。** 合进 `main` 还不够:必须等
-`publish-artifact.yml` 跑完并推出内容哈希 artifact,客户端之上还有一层刷新 TTL。
-手改缓存里的 `pkgs/**` 不起任何作用。
+**索引是一个 artifact，不是一次 git clone。** 合进 `main` 还不够：必须等
+`publish-artifact.yml` 跑完并推出一个内容哈希 artifact，客户端之上还叠着一层刷新
+TTL。手改缓存里的 `pkgs/**` 不起任何作用。
 
 ```bash
 gh run list --repo mcpplibs/mcpp-index --workflow publish-artifact.yml --limit 1
-rm -rf ~/.mcpp/registry/data/<namespace>    # 强制客户端刷新
+rm -rf ~/.mcpp/registry/data/<namespace>    # force a client refresh
 ```
 
-## 5. 冷解析验证与消费方升级
+## 5. 从一次冷解析验证，再升消费方
 
-这一步的意义在于:本地那份库的 checkout 会掩盖上面每一个错误。要像一个陌生人那样解析它:
+这一步的意义在于：本地那份库的 checkout 会掩盖上面每一步的错误。要像一个陌生人
+那样解析它：
 
 ```bash
 rm -rf ~/.mcpp/registry/data/xpkgs/<ns>-x-<name>/0.0.48
-mcpp build                            # 必须真的下载并编译 0.0.48
+mcpp build                            # must download and compile 0.0.48
 ```
 
-通过之后,才去升消费方的 `[dependencies]`。
+只有到这时，才去升消费方的 `[dependencies]`。
 
 > **不要**只用
 > `find ~/.mcpp/registry -mindepth 1 -maxdepth 1 ! -name data -exec rm -rf {} +`
-> 去强制刷新。`data/xpkgs` 在第 2 层且名字不是 `data`,再来一遍粗心的清理就会把整个
-> payload 仓(约 800 MB 工具链)删掉。恢复办法是 `mcpp self doctor` 重新 provision,
-> 再 `mcpp update`。
+> 来强制刷新。`data/xpkgs` 位于第 2 层且名字不是 `data`，再来一次粗心的清理就会把
+> 整个 payload 仓（约 800 MB 的工具链）一并删掉。恢复办法是先用 `mcpp self doctor`
+> 重新 provision，再 `mcpp update`。
 
 ## 针对尚未发布版本的测试
 
-在上面这条链还没走完时,可以手工播种 registry,让消费方提前编译:
+在上面这条链还没走完时，可以手工向 registry 播种，让消费方在库发布之前就能编译：
 
 ```bash
 REG=~/.mcpp/registry/data/xpkgs/<ns>-x-<name>/0.0.48
 mkdir -p "$REG"
 git -C /path/to/library archive --format=tar --prefix=<repo>-0.0.48/ HEAD \
   | tar -x -C "$REG"
-touch "$REG/.mcpp_ok"                 # 表示"已解析"的标记
-cp ../0.0.47/.xpkg.lua "$REG/.xpkg.lua"   # 往里加一条 0.0.48 条目
+touch "$REG/.mcpp_ok"                 # the marker that says "resolved"
+cp ../0.0.47/.xpkg.lua "$REG/.xpkg.lua"   # add a 0.0.48 entry to it
 ```
 
-mcpp 的构建沙箱是网络隔离的,`file://` 和 `http://127.0.0.1` 形式的索引 URL 取不到,
-播种缓存才是可行的办法。
+mcpp 的构建沙箱与网络隔离，`file://` 和 `http://127.0.0.1` 形式的索引 URL 都取不到，
+因此播种缓存是唯一可行的办法。
 
-**在相信"真的能用"之前,先把播种的那份删掉。** 播种的 0.0.48 和已发布的 0.0.48
-对构建来说毫无区别 —— 而当发布其实失败了的时候,留在那里的正是播种的那一份。
+**在相信「真的能用」之前，先删掉播种的那一份。** 播种出来的 0.0.48 与已发布的
+0.0.48 对构建而言毫无区别，而当发布实际上已悄悄失败时，留在那里的正是播种的那一份。
 
 ## 需要版本下限的 manifest 键
 
-多数 `[build]` 键在较老的 mcpp 上会干净地降级:它警告该键不受支持、忽略它,
-构建要么照常成功,要么以清晰的信息失败。`build_program_timeout` 属于这一类 ——
-较老的 mcpp 回落到 600 秒默认值,若该值过短会明确报出。
+多数 `[build]` 键在较旧的 mcpp 上会干净地降级：警告该键不受支持、忽略它，构建要么
+照常成功，要么以一条清楚的信息失败。`build_program_timeout` 就属于这一类 ——
+较旧的 mcpp 会回落到 600 秒的默认值，如果这个值太短，也会明确报出。
 
-**`module_extensions` 不属于这一类。** 较老的 mcpp 警告并忽略它,随后把那些文件
-当作普通翻译单元编译 —— 得到的是一个**错误的构建**而不是一次干净的失败:
-模块接口不产生 BMI,故障在更晚的地方浮现,而报错既不点名这条键也不点名该文件。
+**`module_extensions` 不属于这一类。** 较旧的 mcpp 会警告并忽略它，随后把那些文件
+当作普通翻译单元编译 —— 得到的是一个**错误的构建**，而不是一次干净的失败：模块
+接口不产生 BMI，故障在更晚的地方浮现，报错既不点名这条键，也不点名那个文件。
 
-使用 `module_extensions` 的已发布包必须在其索引描述符中声明 mcpp 版本下限。
-下限机制必须**降级**:因客户端过旧而不可用的包,必须被报告为**不可用**,
-绝不能报告为**不存在** —— 被告知「无此包」的客户端会不断刷新索引去找它。
+使用 `module_extensions` 的已发布包，必须在其索引描述符中声明一个 mcpp 版本下限。
+下限机制必须能够**降级**：因客户端过旧而不可用的包，必须被报告为**不可用**，绝不能
+报告为**不存在** —— 被告知「无此包」的客户端会不断刷新索引去找它。
 
 ## 检查清单
 
 - [ ] `mcpp.toml` 版本 == git tag
-- [ ] tag 已推;tarball 可下载,sha256 已记录
-- [ ] gitcode 资源用 **GET** 验证过,且与 GitHub 那份逐字节一致
+- [ ] tag 已推送；tarball 可下载，sha256 已记录
+- [ ] gitcode 资源已用 **GET** 验证，且与 GitHub 那份逐字节一致
 - [ ] 索引条目写进了**三个**平台块
-- [ ] `publish-artifact.yml` 成功
-- [ ] 冷解析(删掉播种拷贝后)能下载并编译
+- [ ] `publish-artifact.yml` 已成功
+- [ ] 冷解析（已删掉播种拷贝）能下载并编译
 - [ ] 消费方已升版本
-
+</content>
diff --git a/docs/zh/12-binary-distribution.md b/docs/zh/12-binary-distribution.md
index 3f1da9c7d..3cdbc82b1 100644
--- a/docs/zh/12-binary-distribution.md
+++ b/docs/zh/12-binary-distribution.md
@@ -2,47 +2,47 @@
 
 [English](../12-binary-distribution.md) | **简体中文**
 
-**读者:**交付编译产物而不是源码的发布方。
+**读者：** 交付编译产物而不是源码的发布方。
 
-**本章回答的那一个问题:**怎样交付二进制,以及消费方的构建如何判断其中哪一个合用。
+**本章回答的那一个问题：** 怎样交付二进制，以及消费方的构建如何判断其中哪一个合用。
 
-**不在这里:**发布源码,那是 [11 —— 发布一个库](11-publishing-a-library.md);以及
-兼容性 tag 的加速器字段,那是 [42 —— 异构硬件构建](42-heterogeneous-builds.md)。
+**不在这里：** 发布源码，那是 [11 —— 发布一个库](11-publishing-a-library.md)；以及
+兼容性 tag 的加速器字段，那是 [42 —— 异构硬件构建](42-heterogeneous-builds.md)。
 
-> 把一个库以**接口 + 预编译二进制**的形式分发,而不是发源码。
-> 适用于闭源分发、离线环境,以及构建产物已在构建农场生成的场景。
+> 把一个库以**接口 + 预编译二进制**的形式分发，而不是发源码。
+> 适用于闭源分发、离线环境，以及构建产物已经由构建农场产出的场景。
 >
-> 相关文档:[10 - 打包应用](10-pack-and-release.md) 说明**程序**的打包;
-> [11 - 发布一个库](11-publishing-a-library.md) 说明源码分发通路。
+> 相关文档：[10 - 打包与发布](10-pack-and-release.md) 说明**应用程序**的打包；
+> [11 - 发布一个库](11-publishing-a-library.md) 是源码分发的路径。
 
 ## 概述
 
-`mcpp pack <target>` 构建一个库目标,产出一个**普通的 mcpp 包** ——
-一份正常的 `mcpp.toml`、消费者要编译的接口、以及它随后链接的二进制。
-消费者用它和用任何依赖一样。**没有新的 manifest 段、没有新的归档格式、
-没有新的解析路径。**
+`mcpp pack <target>` 构建一个库目标，产出一个**普通的 mcpp 包**——一份正常的
+`mcpp.toml`、消费方要编译的接口、以及它随后链接的二进制。消费方使用它的方式与
+使用任何其他依赖完全相同。没有新的 manifest 段，没有新的归档格式，也没有新的
+解析路径。
 
 ```bash
-mcpp pack mathkit                              # 静态库包
-mcpp pack mathkit-shared                       # 动态库包(ELF、Mach-O、PE/MinGW)
+mcpp pack mathkit                              # a static library package
+mcpp pack mathkit-shared                       # a dynamic one (ELF, Mach-O, PE/MinGW)
 mcpp pack mathkit --target x86_64-linux-gnu \
-                  --target aarch64-linux-gnu   # 一个包,两个 target
+                  --target aarch64-linux-gnu   # one package, two legs
 ```
 
 ## 打包内容的决定依据
 
-只由 `[targets.<name>].kind` 决定:
+只由 `[targets.<name>].kind` 决定，没有别的：
 
 | `kind` | `mcpp pack <name>` 产出 | `--mode` |
 |---|---|---|
-| `bin` | 应用 bundle(见 [10](10-pack-and-release.md)) | 四档 |
-| `lib` | **静态库包** | — |
-| `shared` | **动态库包** | — |
+| `bin` | 一个应用 bundle（见 [10](10-pack-and-release.md)） | 四档深度 |
+| `lib` | 一个**静态库包** | — |
+| `shared` | 一个**动态库包** | — |
 
-**没有 `--lib`,也没有 `--artifact static|shared`。** `kind` 本来就是 mcpp
-记录「一个产物是什么」的地方;再加一个开关就是同一件事的第二个说法,
-而两个说法可以互相矛盾。要同时发布两种形态,就声明两个目标 ——
-这本来也是 `mcpp build` 同时产出两者所必需的:
+没有 `--lib` 旗标，也没有 `--artifact static|shared`。`kind` 本来就是 mcpp
+记录「一个产物是什么」的地方；再加一个旗标就是同一件事的第二种说法，而两种
+说法可能互相矛盾。要同时发布两种形态，就声明两个目标——这本来也是
+`mcpp build` 要同时产出两者所必需的：
 
 ```toml
 [targets.mathkit]
@@ -53,100 +53,103 @@ kind   = "shared"
 soname = "libmathkit.so.1"
 ```
 
-省略名字时,`mcpp pack` 选择唯一可打包的目标;存在多个候选时列出它们并要求指名。
+`mcpp pack` 不带名字运行时，会选择唯一可打包的目标；找到多个候选时则列出它们。
 
 ## 两种接口模式
 
-一个包可以同时带两种,消费者用其中一种或两种都用。
+一个包可以同时携带两种，消费方可以只用其中一种，也可以两种都用。
 
 ```
 mathkit-0.1.0-x86_64-linux-gnu-gcc16-libstdcxx16-c++23/
 ├── mcpp.toml
-├── include/          ← 文本接口:#include,永不编译
-├── interface/        ← 模块接口:消费者编译它
-└── lib/<triple>/     ← 产物
+├── include/          ← TEXT interface: #include, never compiled
+├── interface/        ← MODULE interface: the consumer compiles it
+└── lib/<triple>/     ← the artifacts
 ```
 
 | | `include/` | `interface/` |
 |---|---|---|
-| 是谁的输入 | 预处理器 | **编译器** |
-| 消费者要编译吗 | 否 | **是**,编出 BMI |
-| 约束什么 | libc ABI | 编译器、C++ 标准库、C++ 档位 |
-| 能裁剪吗 | **不能**,见下 | **不能**,它是算出来的 |
+| 是谁的输入 | 预处理器的 | **编译器**的 |
+| 消费方要编译它吗 | 否 | **是**，编出 BMI |
+| 约束的是什么 | libc ABI | 编译器、C++ 标准库、C++ 档位 |
+| 能裁剪吗 | **不能**——见下 | **不能**，它是算出来的 |
 
-`lib/` 按**三元组**分目录,不按 OS 分:MinGW 与 MSVC 同为 Windows,
-一个产 `libfoo.a` 一个产 `foo.lib`。
+`lib/` 按**三元组**分目录，不按 OS 分。MinGW 与 MSVC 同为 Windows，却分别产出
+`libfoo.a` 与 `foo.lib`。
 
-**共享**包以库的*两个*名字携带它:消费者链接 `lib<target>.so`,加载器随后按
-`SONAME` 查找。声明了 `soname` 时这是两个不同的文件名,只发构建出的那个文件能链接
-成功、随后启动失败。未声明 `soname` 的库把自己的文件名记为 `SONAME`
-(mcpp 2026.9.14.2+),它的两个名字就是同一个文件。
+**共享**库包以库的两个名字*同时*携带它：消费方链接 `lib<target>.so`，加载器随后
+按 `SONAME` 查找。声明了 `soname` 时，这是两个不同的文件名，只发布构建出的
+那个文件，链接能成功而启动会失败。未声明 `soname` 的库把自己的文件名记为它的
+`SONAME`(mcpp 2026.9.14.2+)，于是它的两个名字就是同一个文件。
 
-### 两个集合不可裁剪的原因
+### 两个集合都不可裁剪的原因
 
-同一个包的**源码**分发会把 `include_dirs` 里的每一个头都放到消费者的 include
-路径上。二进制包若只发一部分,**同一个库就会因为分发形式不同而有不同的公开面**。
-而且「哪些头是公开的」布局已经回答了:`include/` 公开,`src/` 不公开。
-一个私有头放在 `include/` 下是工程布局的错误,不是打包选项。
+同一个包的**源码**分发会把它 `include_dirs` 里的每一个头文件都放到消费方的
+include 路径上。若二进制包只发布其中一部分，同一个库的公开面就会因为分发形式
+不同而不同。而且「哪些头文件是公开的」这件事，布局本身已经回答了：`include/`
+公开，`src/` 不公开。一个私有头文件放在 `include/` 下，是工程布局的错误，不是
+一个打包选项。
 
 ## 发布的接口单元
 
-**lib root 的模块闭包** —— 按约定是 `src/<包名尾段>.cppm`,或 `[lib].path`。
-该单元 purview 里 import 到的东西,传递地,都发布;其余都不发。
+**lib root 的模块闭包**——按约定是 `src/<包名尾段>.cppm`，或 `[lib].path` 所
+指的文件。该单元 purview 内传递地 import 到的一切，都会被发布；其余都不发布。
 
 ```
-src/mathkit.cppm    export module mathkit;  export import :api;   → 发布
-src/api.cppm        export module mathkit:api;                    → 发布
-src/secret.cppm     module mathkit:secret;          ← 实现分区
-src/impl.cpp        module mathkit;                               → 不发布
+src/mathkit.cppm    export module mathkit;  export import :api;   → published
+src/api.cppm        export module mathkit:api;                    → published
+src/secret.cppm     module mathkit:secret;         ← implementation partition
+src/impl.cpp        module mathkit;                                → withheld
 ```
 
-`mcpp pack` 会打印两张清单:
+`mcpp pack` 会打印两张清单：
 
 ```
    Interface mathkit.cppm, api.cppm
     Withheld capi.c, impl.cpp, secret.cppm
 ```
 
-**闭源分发要看第二张。**
+**对闭源分发来说，要紧的是第二张清单。**
 
-> **`.m.o` 不是判据。** 实现分区照样产出 BMI 和对象。按「会不会产出 BMI」
-> 来挑发布集,就会把 `secret.cppm` 发出去。
+> **`.m.o` 不是判据。** 实现分区产出的 BMI 与对象，与接口单元完全一样。按
+> 「会不会产出 BMI」来挑选发布集，就会把 `secret.cppm` 一并发布出去。
 
-如果被发布的接口**确实** import 了一个实现分区,消费者没有那份源码就编不出来 ——
-于是 `mcpp pack` 停下来:
+如果被发布的接口**确实** import 了一个实现分区，消费方没有那份源码就编译不出
+来——于是 `mcpp pack` 会停下：
 
 ```
 error: the published interface imports mathkit:secret , which no unit in this
        build provides.
 ```
 
-要么重构让接口够不到它,要么把它改成 `export module` 分区并接受源码被发布。
+要么重构，让接口够不到它；要么把它改成 `export module` 分区，并接受它的源码
+被发布。
 
 ## 兼容性 tag
 
-每个产物都记录它是为哪套工具链编的:
+每一个产物都记录它是为哪一套工具链构建的：
 
 ```
-x86_64-linux-gnu-gcc16-libstdcxx16-c++23      # C++ 模块接口
-x86_64-linux-gnu                              # 纯 extern "C" 接口
+x86_64-linux-gnu-gcc16-libstdcxx16-c++23      # a C++ module interface
+x86_64-linux-gnu                              # an extern "C" interface only
 ```
 
-`<arch>-<os>-<env>`,接口是 C++ 时再加 `<compiler><major>`、
-`<stdlib><major>`、`c++<档位>`。
+即 `<arch>-<os>-<env>`，当接口是 C++ 时再加上 `<compiler><major>`、
+`<stdlib><major>`、`c++<level>`。
 
-**短 tag 是一句真实的声明,不是漏写。** 一个接口全是 `extern "C"` 的库
-只约束 libc ABI、不约束 C++ ABI,所以它发三段就停 —— 于是能链进任何编译器。
-未指定的维度就是不关心,C 库的 tag 数因此是「每个三元组一个」而不是
-「每个三元组 × 每个编译器一个」。**不需要任何开关:形状本身就是声明。**
+**更短的 tag 是一句真实的声明，不是漏写。** 一个接口全是 `extern "C"` 的库，
+只约束 libc ABI、不约束 C++ ABI，所以它只发布三段就停止——并因此能链进任何
+编译器。未命名的维度就是不关心，于是这类库的 tag 是每个三元组一个，而不是每个
+三元组配每个编译器各一个。没有任何东西需要配置：形状本身就是声明。
 
-`c++` 档位按**下限**比对而不是相等:消费者档位更高可以,更低不行。
+`c++` 档位按**下限**比对，不按相等比对：消费方用更高的档位构建没问题，更低则
+不行。
 
 ## 消费端的构建检查
 
-两件事,而且都是不检查就会静默出错的:
+两件事，而且两者都是不检查就会静默出错的：
 
-**接口与二进制仍然配对。**
+**接口仍然与它的二进制配对。**
 
 ```
 error: acme.mathkit@0.1.0: 'interface' does not match what was packaged.
@@ -154,13 +157,13 @@ error: acme.mathkit@0.1.0: 'interface' does not match what was packaged.
   found    fnv1a:fe404d5be85118ff
 ```
 
-这条闸门存在是因为另一种结果被实测过:把随包接口里一个结构体的两个 `int`
-成员互换 —— Itanium ABI 不 mangle 字段顺序 —— 消费者**编译过、链接过、
-运行过、打印出交换后的错数据**,任何工具都没有一句诊断。
-digest 挡不住发布者一开始就发错配对(那只有原子产出能防),
-但它能挡住配对在事后被拆开。
+这道闸门的存在，是因为另一种结果被实测过。把随包发布的接口里一个结构体的两个
+`int` 成员互换——Itanium ABI 不 mangle 字段顺序——消费方编译通过、链接通过、
+运行通过，并打印出被互换的错误数据，而任何工具都不会报出一句诊断。一个摘要
+挡不住发布者一开始就发出一对不匹配的接口与二进制（只有原子式地一次产出两者
+才能防住这一点），但它能挡住这一对配对在事后被拆开。
 
-**二进制是为这套工具链编的。**
+**二进制是为这一套工具链构建的。**
 
 ```
 error: acme.mathkit@0.1.0: no prebuilt artifact matches this toolchain.
@@ -172,38 +175,39 @@ error: acme.mathkit@0.1.0: no prebuilt artifact matches this toolchain.
     stdlib    needs libstdcxx15, this build has libstdcxx16
 ```
 
-诊断里**列出它有哪些 tag** 是刻意的:一句「找不到」会让人去找一个
-就在自己硬盘上的包。
+诊断里列出它**确实拥有**哪些 tag 是刻意的：一句「没找到」会让读者去找一个
+已经在自己磁盘上的包。
 
 ## 消费方式
 
-三种写法,同一条代码路径:
+三种写法，同一条代码路径：
 
 ```toml
-# 一个目录(可直接拷贝分发)
+# a directory (copied directly to a colleague)
 mathkit = { path = "vendor/mathkit-0.1.0-x86_64-linux-gnu-gcc16-libstdcxx16-c++23" }
 
-# 私有 git 仓库
+# a private git repo
 mathkit = { git = "ssh://git@internal/mathkit-dist.git", tag = "v0.1.0" }
 
-# 索引条目 —— 形状与源码包一字不差
+# an index entry — identical in shape to a source package's
 mathkit = "0.1.0"
 ```
 
-消费者的 manifest 里没有任何一处写着「这个是预编译的」。
+消费方的 manifest 里没有任何一处写着「这个是预编译的」。
 
-### 包目录内的直接构建被拒绝
+### 在包目录内直接构建被拒绝
 
 ```
 error: … is a distribution package produced by `mcpp pack`, not a source tree.
 ```
 
-它的 `interface/` 里是声明,定义在旁边的归档里。在那儿构建会把声明编出来、
-产出一个几乎空的库、然后报告成功。
+它的 `interface/` 里是声明，定义在旁边的归档里。在那里构建会把声明编译出来，
+产出一个近乎空的库，并报告成功。
 
-## 单包多 target
+## 单包多个 target
 
-`--target` 可重复。生成的 manifest 每个 target 的产物一个条件块,消费者的构建各选各的:
+`--target` 可重复传递。生成的 manifest 里每个 target 各有一个条件块，消费方的
+构建各自选择自己需要的那一个：
 
 ```toml
 [target.'cfg(all(arch = "x86_64", os = "linux", env = "gnu"))'.build]
@@ -213,44 +217,45 @@ ldflags = ["-Llib/x86_64-linux-gnu", "-lmathkit"]
 ldflags = ["-Llib/x86_64-linux-musl", "-lmathkit"]
 ```
 
-因为选择发生在**消费者的构建期**(那时解析后的 target 已知),
-多 target 包的交叉编译天然正确,**不需要索引侧或安装侧做任何支持**。
+因为这次选择发生在**消费方的构建期**——那时解析出的 target 已知——一个
+多 target 包的交叉编译天然正确，不需要索引侧或安装侧提供任何支持。
 
-> 这些块是 `cfg(...)`,绝不是裸的 `[target.'<三元组>']` 键。
-> 在 mcpp 2026.8.18.1 之前,裸三元组在没有显式 `--target` 时是失效的 ——
-> 用它的包会在 CI 里正常、在开发者机器上静默丢掉 flag。
-> mcpp 生成的是在**所有**客户端上含义一致的那种写法。
+> 这些条件块一律是 `cfg(...)`，从不是裸的 `[target.'<三元组>']` 键。在 mcpp
+> 2026.8.18.1 之前，裸三元组形式在没有显式 `--target` 时是失效的，于是用它的
+> 包会在 CI 里正常工作，却在开发者的机器上静默丢掉这些 flag。mcpp 生成的是
+> 在每一个客户端上含义都一致的那种写法。
 
 ## 依赖
 
-静态归档**不携带**它依赖的代码,所以包会把依赖记下来,由消费者解析:
+一个静态归档**不携带**它所依赖的代码，所以包会把这些依赖记录下来，由消费方
+解析：
 
 ```toml
 [dependencies]
 "compat.zlib" = "1.3.2"
 ```
 
-`path` 与 `git` 依赖会被丢弃:它们指向发布者的磁盘,原样发出去等于
-会给消费者一个在其机器上含义完全不同的地址。若库依赖这类来源,
-要么把它也发布出去,要么在打包前 vendor 掉。
+`path` 与 `git` 依赖会被丢弃：它们指向发布者自己的磁盘，原样重新发布出去，
+等于把一个在消费方机器上含义完全不同的地址交给了对方。一个依赖这类来源的库，
+要么把那个依赖也一并发布，要么在打包前把它 vendor 进来。
 
 ## 旧版本 mcpp 的行为
 
-**能构建。** 生成的 manifest 里每一个键都是既有的,所以老客户端读得懂、
-链得上。它做不到的是执行上面那两道闸门 —— 它无从知道
-`provenance = "mcpp-pack …"` 有什么含义。
+**能构建。** 生成的 manifest 里每一个键都是既有的键，所以旧客户端能读懂这个
+包并把它链接起来。它做不到的是执行上面那两道检查——它无从知道
+`provenance = "mcpp-pack …"` 意味着什么。
 
-这是**降级**而不是变砖,方向是对的。但它意味着**闸门只保护新客户端**,
-面向混合版本用户群发布时,这一条应写进发布说明。
+这是一种降级而不是损坏，而且方向是对的。但这意味着**这道闸门只保护新客户端**，
+面向混合版本用户群发布的任何包，都应当把这一点写进发布说明。
 
 ## 随包内容与刻意排除的部分
 
-发布出去的包必须能在**不是发布者的**机器上工作。两个步骤保证这件事,
-它们作用在打包器暂存的每一个产物上。
+一个已发布的包必须能在不是发布者本人的机器上工作。两个步骤保证这一点，两者
+都作用于打包器暂存的每一个产物。
 
-### 构建机的 loader 搜索路径会被删掉
+### 构建机的加载器搜索路径会被移除
 
-dev 构建会把工具链自己的目录烙进每一个共享对象:
+一次开发构建，会把工具链自己的目录烙进每一个共享对象：
 
 ```text
 DT_RUNPATH = <home>/registry/data/xpkgs/xim-x-glibc/2.44/lib64
@@ -258,97 +263,105 @@ DT_RUNPATH = <home>/registry/data/xpkgs/xim-x-glibc/2.44/lib64
            : <home>/registry/subos/default/lib
 ```
 
-这对 dev 构建是对的,对一个包则是致命的(issue #460),原因是 ELF 装载器的
-一条规则:**一个携带任何 `DT_RUNPATH` 的对象,会让装载器在解析它自己的依赖时
-跳过整条继承来的 `DT_RPATH` 链。** 于是消费方那条 `DT_RPATH` —— 载荷、包目录、
-SubOS farm,全都是在真正要运行它的那台机器上算出来的 —— 根本不被查,程序死在
+这对开发构建来说是对的，对一个包来说却是致命的（issue #460），原因在于 ELF
+加载器的一条规则：**一个携带任何 `DT_RUNPATH` 的对象，会让加载器在解析它自己
+的依赖时，跳过整条继承而来的 `DT_RPATH` 链。** 于是消费方自己那条
+`DT_RPATH`——载荷、包目录、SubOS farm，全都是在真正要运行它的那台机器上算出
+来的——根本不会被查询，程序死于
 
 ```text
 error while loading shared libraries: libstdc++.so.6: cannot open shared object file
 ```
 
-**`$ORIGIN` 不是解药。** 在真实的包上、把构建机的 store 变成不可达之后实测:
+**`$ORIGIN` 不是解法。** 在一个真实的包上、把构建机的 store 变得不可达之后
+实测：
 
-| 发货 `.so` 上的状态 | 消费方 `DT_RPATH` 的继承 | 结果 |
+| 已发布 `.so` 上的状态 | 是否继承消费方的 `DT_RPATH` | 结果 |
 |---|---|---|
 | 失效的绝对路径 `DT_RUNPATH` | 否 | 失败 |
 | **完全没有这条 tag** | **是** | **能跑** |
 | `DT_RUNPATH = $ORIGIN` | 否 | 失败 |
 | `DT_RUNPATH = ""` | 否 | 失败 |
 
-关掉继承的是这条 tag 的**存在**,不是它的内容。所以 `mcpp pack` 删掉这个条目而
-不是改写它 —— 而且删掉不是妥协,它就是正确答案:消费方自己的 `DT_RPATH` 是同一个
-闭包,只不过是在它有意义的那台机器上解析的。
+关掉继承的是这条 tag 的**存在本身**，不是它的内容。所以 `mcpp pack` 删掉这个
+条目，而不是改写它——而删掉并不是一种妥协，它就是正确答案：消费方自己的
+`DT_RPATH` 是同一个闭包，只是在它真正有意义的那台机器上被解析出来的。
 
-路径**字符串**会留在 `.dynstr` 里,没有人再指向它。`.dynstr` 被链接器做了尾部合并,
-一个更短的活字符串可能从这条死字符串的中间开始,删掉这些字节无法被证明是安全的;
-`patchelf --remove-rpath` 留下的残留在尺寸上逐字节相同。**所以这件事的守卫必须读
-动态段的条目,绝不能 `grep` 文件字节** —— 见 `tests/e2e/_elf_tag.sh`。
+那条路径**字符串**仍留在 `.dynstr` 里，只是没有人再指向它。`.dynstr` 会被
+链接器做尾部合并，一个更短的、仍在使用的字符串可能从这条已死字符串的中间
+开始，删掉那些字节因此无法被证明是安全的；`patchelf --remove-rpath` 留下的
+残留，在文件大小上与原来逐字节相同。**所以为这件事写的守卫必须读动态段的
+条目，绝不能对文件字节做 `grep`**——见 `tests/e2e/_elf_tag.sh`。
 
-Mach-O 上打包器会读出 `LC_RPATH` 并在包会携带它时告警;自动改写
-(`install_name_tool -delete_rpath`)尚未做,因为这个套件里还没有任何测试能产出
-一个 `.dylib` 来给这次字节编辑做判据。
+在 Mach-O 上，打包器会读出 `LC_RPATH` 并在包将要携带它时发出警告；自动改写
+（`install_name_tool -delete_rpath`）尚未实现，因为这个套件里目前还没有任何
+测试会产出一个 `.dylib` 来为这次字节级编辑提供判据。
 
-### 调试信息会被剥掉
+### 调试信息会被移除
 
-参数、分档表与 `--debug-symbols` 见 [docs/10](10-pack-and-release.md)。
-对**库**包最要紧的一条:静态归档只做 `--strip-debug`,因为 `--strip-all` 会删掉
-归档的符号索引,消费方链接时会报 `archive has no index; run ranlib to add one`。
+旗标、按产物形态分的表格与 `--debug-symbols`，见
+[docs/10](10-pack-and-release.md)。对**库**包来说最要紧的一条规则是：一个
+静态归档只会被 `--strip-debug`，因为 `--strip-all` 会删掉归档自身的符号索引，
+使消费方的链接失败并报
+`archive has no index; run ranlib to add one`。
 
 ## 当前边界
 
 | | 状态 |
 |---|---|
-| `kind = "lib"`(静态) | 所有 target,三平台都测了 |
-| `kind = "shared"` on Linux/ELF | —— 包里同时带链接名与 SONAME,且不含构建机的 loader 路径 |
-| `kind = "shared"` on PE / MinGW(`*-windows-gnu`) | —— 包里同时带 `.dll` **和它的导入库** |
-| `kind = "shared"` on Mach-O(`*-macos`) | —— install name 是 `@rpath/<file>`,`.dylib` 可重定位。`LC_RPATH` 只报告,尚未改写 |
-| `kind = "shared"` on PE / MSVC(`*-windows-msvc`) | —— mcpp 生成 `.def`;见下 |
+| `kind = "lib"`（静态） | 每个 target，三个平台都测过 |
+| `kind = "shared"` on Linux/ELF | —— 包同时携带链接名与 SONAME，不含构建机的加载器路径 |
+| `kind = "shared"` on PE / MinGW(`*-windows-gnu`) | —— 包同时携带 `.dll` **及其**导入库 |
+| `kind = "shared"` on Mach-O(`*-macos`) | —— install name 为 `@rpath/<file>`，`.dylib` 可重定位。`LC_RPATH` 只被报告，尚未被改写 |
+| `kind = "shared"` on PE / MSVC(`*-windows-msvc`) | —— mcpp 生成 `.def`；见下文 |
 | `kind = "shared"` on `*-musl` | musl target 是静态链接的 |
-| 一个包同时携带同一 triple 的两套 ABI(gcc **与** clang) | leg 选择是 `cfg(arch/os/env)`;一个 ABI 发一个包 |
-| 发布预编译 BMI | 未尝试;BMI 与编译器构建逐位绑定 |
-| 把依赖打包进去 | 改为声明依赖(见上) |
-| 用**原生 `cl.exe`** 消费这种包 | —— 经方言中立的链接意图;见下 |
+| 同一个包为同一个三元组携带两套 ABI(gcc **与** clang) | leg 的选择是 `cfg(arch/os/env)`；每套 ABI 各发布一个包 |
+| 发布预编译 BMI | 未尝试；BMI 与编译器构建逐位绑定 |
+| 把依赖打包进去 | 改为声明依赖（见上文） |
+| 用**原生 `cl.exe`** 消费这种包 | —— 经由方言中立的链接意图；见下文 |
 
 ### MSVC ABI 上的符号导出
 
-MSVC 在源码没有 `__declspec(dllexport)`、也没有 `.def` 列出符号时,DLL 什么都不导出。
-两者皆无时导入库为空,每个消费者都会拿到一堆 unresolved externals,而那些符号
-明明就在对象文件里。MinGW 的链接器会自动导出,把这个问题整个遮住;lld-link 的
-MSVC 形态刻意不这么做,因为 PE 的导出上限是 65535。
+除非源码写了 `__declspec(dllexport)`，或一份 `.def` 文件列出了符号，MSVC 不会
+从一个 DLL 导出任何东西。两者都没有时，导入库会是空的，每个消费方都会因为一批
+明明就在对象文件里的符号拿到 unresolved externals。MinGW 的链接器会自动导出，
+把这个问题整个遮住；lld-link 的 MSVC 形态刻意不这样做，因为 PE 的导出上限是
+65535。
 
-mcpp 从对象生成 `.def` —— 这正是 CMake 的 `WINDOWS_EXPORT_ALL_SYMBOLS` 自 3.4 起
-在做的事。它是一个构建图节点,输入就是链接所消费的那批对象,因此导出面不会与
-「实际编译了什么」发生漂移;而且它**直接读 COFF**,不调 `dumpbin` —— 那个工具在
-Visual Studio 开发者环境里才有,而 mcpp 在 Windows 上的默认工具链是 clang。
+mcpp 从对象文件生成 `.def`——这正是 CMake 的 `WINDOWS_EXPORT_ALL_SYMBOLS`
+自 3.4 起在做的事。它是构建图里的一个节点，输入就是链接所消费的那批对象，
+因此导出面不会与「实际编译了什么」发生漂移；而且它直接读 COFF，不会 shell 出去
+调用 `dumpbin`——那个工具存在于 Visual Studio 的开发者环境里，而 mcpp 在
+Windows 上的默认工具链是 clang。
 
-**有两条限制是任何工具都消不掉的**,与 CMake 为同一机制记录的是同两条:
+**有两条限制是任何工具都消不掉的**，与 CMake 为同一机制记录的正是同样两条：
 
 | | |
 |---|---|
-| 导出的**数据** | 消费者的声明仍需 `__declspec(dllimport)`;否则链接器读到的是调用桩而不是值 |
-| **vtable** 被引用的类 | 整个类都要标注,例如带虚函数的类的委托构造函数 |
+| 导出的**数据** | 消费方的声明上仍需要 `__declspec(dllimport)`；没有它，链接器读到的是一个调用桩，而不是值本身 |
+| **vtable** 被引用的类 | 整个类都要被标注，例如一个带虚函数的类的委托构造函数 |
 
-两者都靠标注解决,而且**标注优先**:对象里若已带 `/EXPORT:` 指令(那正是
-`__declspec(dllexport)` 产生的),mcpp 就让开,不生成任何东西。在其之上再加一份
-列表会把同名符号导出两次(`LNK4197`),更糟的是把其余所有符号也一并导出 ——
-用「全部」替换掉作者选定的公开面。这件事没有任何开关:对象自己说了算。
+两者都靠标注来回答，而且**标注优先**：一个已经带 `/EXPORT:` 指令的对象——那
+正是 `__declspec(dllexport)` 产生的——会让 mcpp 让开，什么都不生成。在其上再
+叠加一份列表，会把同一批符号导出两次（`LNK4197`），还会把其余所有符号也一并
+导出，用「全部」取代作者选定的那个公开面。这件事没有任何东西需要配置：对象
+文件自己说了算。
 
-可导出符号超过 65535 时,mcpp 拒绝而不是截断。被截断的导出表能干净地链接完成,
-随后在「恰好需要那个掉出去的符号」的消费者那里失败。
+超过 65535 个可导出符号时，mcpp 拒绝而不是截断。一个被截断的导出表能干净地
+链接完成，随后在恰好需要那个掉出去的符号的消费方那里失败。
 
-### 包里的链接 flag 是 GNU 拼写
+### 包里的链接旗标是 GNU 拼写
 
-生成的 manifest 按下列形式选择产物:
+生成的 manifest 按下面这种形式为每个 leg 选择产物：
 
 ```toml
 [target.'cfg(all(arch = "x86_64", os = "windows", env = "msvc"))'.build]
 ldflags = ["-Llib/x86_64-windows-msvc", "-lmathkit"]
 ```
 
-mcpp 用到的每个 driver 都吃这一套 —— 包括 Windows 上默认的、面向 MSVC ABI 的
-clang。**原生 `cl.exe` 不吃**:它不认 `-L`。所以包里会把同一句话再写一遍,
-这一遍不带方言:
+mcpp 用到的每一个 driver 都吃这一套——包括 Windows 上默认的、面向 MSVC ABI
+的 clang。**原生 `cl.exe` 不吃这一套**：它不认 `-L`。所以包里会把同一句话再
+写一遍，这一遍不带方言：
 
 ```toml
 [target.'cfg(all(arch = "x86_64", os = "windows", env = "msvc"))'.runtime]
@@ -356,52 +369,62 @@ link_library_dirs = ["lib/x86_64-windows-msvc"]
 libraries         = ["mathkit"]
 ```
 
-mcpp 会按 target 把它们渲染成 `/LIBPATH:` + `<name>.lib` 或 `-L` + `-l<name>`,
-于是 `cl.exe` 的消费者也能链上。这两个键不是新词表 —— `[runtime]` 顶层一直就有,
-这里只是让它们可以按 target 给。
-
-**两种拼写都会写出来,而新版 mcpp 读到中立形式时会丢掉同一条腿的库引用,
-而不是叠加。** 旧版 mcpp 只读 `ldflags` 并静默忽略 `runtime` 段,所以去掉
-`ldflags` 会让所有旧客户端一个链接 flag 都拿不到;而两者都应用又会把 `-L` 送回
-`cl` 的命令行 —— 那正是要避免的事。
-
-有一条腿被刻意排除在外:**PE/MinGW 的动态库腿**链接行是
-`-L… -Wl,-Bdynamic -lmathkit`,而 `-Wl,-Bdynamic` 只有**紧邻它所启用的那个 `-l`**
-时才有效 —— mcpp 给 PE 可执行文件加 `-static`,否则链接器停在纯静态模式并拒绝
-导入库。中立形式没法表达「先切换链接模式」,所以那条腿保留能用的拼写。
-这不付出任何代价:PE/MinGW 的腿不是 MSVC ABI 的腿,`cl.exe` 永远读不到它。
-
-**改成直接写文件路径也不行**(`lib/<triple>/mathkit.lib` 才是每个 driver 都吃的
-拼写):ninja 执行链接命令时 cwd 是**输出目录**,而只有 include 家族前缀
-(`-I`、`-L` …)会被 `normalize_include_flags` 相对包根绝对化 —— 没有前缀的 token
-就会到错误的地方去找:`ld: cannot find lib/x86_64-windows-gnu/libmathkit.a`。
-而 manifest 里写绝对路径就不再可重定位了。要补齐它,需要让条件通道能承载
-`link_library_dirs` / `libraries` —— mcpp 已经能按方言渲染它们,只是只在顶层读。
+mcpp 会按 target 把它们渲染成 `/LIBPATH:` + `<name>.lib`，或者 `-L` +
+`-l<name>`，于是 `cl.exe` 的消费方也能链接这个包。这两个键不是新词表——
+`[runtime]` 顶层一直就带着这两个键，这里只是让它们能够按 target 分开给出。
+
+**两种拼写都会被写出来，而更新版本的 mcpp 会丢掉那一条 leg 的库引用，而不是
+把两者叠加。** 旧版 mcpp 只读 `ldflags`，并静默忽略 `runtime` 块，所以去掉
+`ldflags` 会让所有旧客户端拿不到任何链接 flag；而两者都生效，又会把 `-L` 重新
+送回 `cl` 的命令行——那正是要避免的事。
+
+有一条 leg 被刻意排除在这条规则之外：一条 **PE/MinGW 共享库**的 leg，链接行是
+`-L… -Wl,-Bdynamic -lmathkit`，而 `-Wl,-Bdynamic` 只有紧邻它所启用的那个 `-l`
+时才生效——mcpp 给 PE 可执行文件加了 `-static`，否则链接器会停在纯静态模式，
+拒绝一个导入库。中立形式无法表达「先切换链接模式」，所以这条 leg 保留了能用
+的那种拼写。这不付出任何代价：PE/MinGW 的 leg 不是 MSVC ABI 的 leg，`cl.exe`
+永远读不到它。
+
+改成直接写文件路径（`lib/<triple>/mathkit.lib`）是每个 driver 都能吃的拼写，
+但同样行不通：ninja 执行链接命令时，cwd 是**输出目录**，而只有 include 家族的
+前缀（`-I`、`-L` 等）会相对包根被绝对化，一个不带前缀的 token 就会被到错误的
+地方去找——`ld: cannot find lib/x86_64-windows-gnu/libmathkit.a`。而 manifest
+里写绝对路径，就不再可重定位了。
+
+方言中立的通道确实存在——`[runtime] link_library_dirs` 与 `libraries`，
+mcpp 会依目标把它们渲染成 `/LIBPATH:` + `name.lib` 或 `-L` + `-lname`——但只在
+顶层读取，而一个包需要它**按每条 leg** 分别给出。实测：一个更早版本的 mcpp
+读到 `[target.'cfg(…)'.runtime]` 时不会报错，而是静默忽略它。这对这个用途来说
+是错的那一种容忍——把一条 leg 的链接 flag 移到那里，会让所有旧客户端一个链接
+flag 都拿不到，所以要正确地补上这一块，要么两种拼写都携带（代价是在新客户端上
+把库链接两遍），要么给这类包一个版本下界。
 
 ### 实现分区
 
-`mcpp pack` 把实现分区(`module M:part;` 无 `export`)当私有:**源码留下,
-对象随归档发出去**。
+`mcpp pack` 把实现分区（`module M:part;`，不带 `export`）当作私有的：它的源码
+留下，它的对象文件随归档一起发出去。
 
-如果被发布的接口 **import 了**一个实现分区,消费者没有那份源码就编不出 BMI,
-所以它**会**被发布 —— 而 `mcpp pack` 会说出来:
+如果被发布的接口 *import* 了一个实现分区，消费方没有那份源码就编不出 BMI，
+所以它**会**被发布——而 `mcpp pack` 会说出这件事：
 
 ```
 warning: secret.cppm is an implementation partition, and the published interface
          reaches it — so its SOURCE is being published.
 ```
 
-> 在 mcpp 2026.8.18.1 之前,扫描器把 `module M:part;` 记成**「requires `M:part`、
-> provides 空」** —— 一个文件 requires 自己的名字,于是图里**没有**从「import 分区
-> 的单元」到「定义分区的单元」的边,构建顺序无约束:GCC 与 macOS clang 靠各自的
-> 依赖扫描兜住了,**Windows clang 以 `failed to read compiled module` 失败**。
-> 此前在 Windows 上无法使用实现分区,原因即在于此。
+> 在 mcpp 2026.8.18.1 之前，扫描器把 `module M:part;` 记成**「requires
+> `M:part`，provides 空」**——一个文件 requires 自己的名字，于是图里**没有**
+> 一条从「import 该分区的单元」到「定义该分区的单元」的边，构建顺序因此不受
+> 约束：GCC 与 macOS clang 靠各自的依赖扫描兜住了这一点，**Windows clang 则以
+> `failed to read compiled module` 失败**。此前实现分区在 Windows 上无法使用，
+> 原因即在于此。
 
 ### 类别无法判定的分区
 
-`[scan_overrides."<glob>"]` 说的是文件提供哪些模块,**没有地方能说**那条声明是否
-带 `export`;P1689 扫描器也可能省略 `is-interface`。两种情况下源码都会被发布 ——
-消费者没有它就编不出 BMI;`mcpp pack` 会指出当前属于哪一种情况:
+`[scan_overrides."<glob>"]` 只说明一个文件提供哪些模块，却没有地方能说明那条
+声明是否带 `export`；P1689 扫描器也可能省略 `is-interface`。无论哪种情况，
+源码都会被发布——消费方没有它就编不出 BMI——而 `mcpp pack` 会指出当前属于
+这两种情况中的哪一种：
 
 ```
 warning: secret.cppm provides a module PARTITION and mcpp cannot tell which kind:
@@ -409,35 +432,36 @@ warning: secret.cppm provides a module PARTITION and mcpp cannot tell which kind
          whether the declaration carries `export`, …
 ```
 
-> 在 2026.8.18.1 之前,这种情况以「它是接口」到达 —— 那个**不产生任何警告**的答案 ——
-> 于是这样声明的实现分区被一声不响地发布了。**发布得太少**会让消费者编译失败并点名
-> 模块;**发布得太多**会把私有源码发出去,而什么都不会失败。未知必须出声。
+> 在 2026.8.18.1 之前，这种情况会得到「它是接口」这个答案——恰恰是**不产生
+> 任何警告**的那个答案——于是这样声明的实现分区被一声不响地发布了出去。
+> 发布得太少，会让消费方编译失败并点名那个模块；发布得太多，会把私有源码
+> 发布出去，而什么都不会失败。未知的情况必须发出声音。
 
 ## 验证范围
 
-e2e 套件按宿主能力给每条测试开门,所以「套件是绿的」和「这条跑了」是两句不同的话。
-实际跑在哪里:
+e2e 套件按宿主能力为每条测试开门，所以「套件是绿的」与「这一条确实跑了」是两句
+不同的话。实际跑在哪里：
 
-| 说法 | linux | macOS | windows |
+| 断言 | linux | macOS | windows |
 |---|---|---|---|
-| 布局、两种接口模式、闭包、两道闸门、workspace 根、指名 target、`sources = []`、裸三元组谓词 | yes | | yes |
-| 多 target 包,两个 target 的产物**同一个**产物名(`gnu` + `musl`) | yes | *不可能* | — |
-| 多 target 包,两个 target 的产物**两个**产物名(`msvc` + `mingw`) | — | *不可能* | yes |
-| 跨 OS 边界的多 target 包(含一个 PE target) | yes | — | — |
-| `lib.exe /REMOVE:` 真的删掉了 | — | — | yes |
-| PE 共享库:产出、打包、链接、运行 | (wine) | — | — |
-| Mach-O 共享库离开构建树仍可加载 | — | yes | — |
-| MSVC 以「导出」为理由拒绝 `kind = "shared"` | — | — | yes |
-| 已发布的 mcpp 消费本版产出的包 | 仅本机 | 仅本机 | 仅本机 |
-| 打包出的 `.so` 不含构建机 loader 路径,**且把缺陷放回去时守卫看得见** | yes | — | — |
-| strip 过的静态归档仍可链接、strip 过的共享库仍可加载,`--no-strip` / `[pack] strip` / `--debug-symbols` 两侧都钉 | yes | — | — |
-| ELF 编辑器在 ELF32 与大端上的行为 | 单测 | 单测 | 单测 |
-
-*不可能* 不是缺口:macOS 宿主只能服务一个 target(`host_can_serve`,
-`registry.cppm`),那里根本产不出两个 target 的产物的包。
-
-最后一行如实记录一个真的洞:每个 CI job 都从一份已发布的 mcpp 自举,但那个入口是
-xvm 的 **shim**,在 e2e 套件改过的环境里它回答「未安装」。所以老客户端检查的
-**静态那半**(生成的 manifest 不含任何旧 mcpp 读不了的段)到处都跑,而**真实那半** ——
-用上一版发布的 mcpp 去构建这个包 —— 是**手工跑的,不是 CI 跑的**。
-
+| 布局、两种接口模式、闭包、两道检查、workspace 根、指名 target、`sources = []`、裸三元组谓词 | yes | | yes |
+| 多 target 包，两条 leg 共用**同一个**产物名（`gnu` + `musl`） | yes | *不可能* | — |
+| 多 target 包，两条 leg 各自**不同**的产物名（`msvc` + `mingw`） | — | *不可能* | yes |
+| 跨越操作系统边界的多 target 包（含一条 PE leg） | yes | — | — |
+| `lib.exe /REMOVE:` 确实移除了 | — | — | yes |
+| PE 共享库：构建、打包、链接、运行 | (wine) | — | — |
+| Mach-O 共享库离开构建树后仍可重定位 | — | yes | — |
+| MSVC 因导出原因拒绝 `kind = "shared"` | — | — | yes |
+| 一个已发布的 mcpp 消费本版本产出的包 | 仅本机 | 仅本机 | 仅本机 |
+| 打包出的 `.so` 不携带构建机的加载器路径，**且把这个缺陷放回去时守卫能看见** | yes | — | — |
+| 被 strip 过的静态归档仍可链接；被 strip 过的共享库仍可加载；`--no-strip` / `[pack] strip` / `--debug-symbols` 两侧都测过 | yes | — | — |
+| ELF 编辑器在 ELF32 与大端序上的行为 | 单测 | 单测 | 单测 |
+
+*不可能*不是一个缺口：一台 macOS 宿主只能服务一个 target(`host_can_serve`，
+`registry.cppm`)，所以两条 leg 的包在那里根本产不出来。
+
+最后一行如实记录了一个真实的空白：每个 CI job 都从一份已发布的 mcpp 自举，但
+那个入口是 xvm 的一个 **shim**，在 e2e 套件的环境下它会回答「未安装」。因此
+旧客户端检查的**静态那一半**（生成的 manifest 不含任何旧版 mcpp 读不懂的段）
+在每个平台上都跑过，而**真实的那一半**——用上一个已发布版本的 mcpp 去构建
+这个包——是手工跑的，不是由 CI 跑的。
diff --git a/docs/zh/20-toolchains.md b/docs/zh/20-toolchains.md
index aaaaedcc8..e426272f0 100644
--- a/docs/zh/20-toolchains.md
+++ b/docs/zh/20-toolchains.md
@@ -1,110 +1,114 @@
 # 20 —— 工具链管理
 
-**读者:**在意「哪个编译器在跑」的人 —— 版本下界、第二套工具链,或者一台不许用
-自带编译器的机器。
+**读者：** 在意「哪个编译器在跑」的人——一条版本下界、第二套工具链，或者一台
+不许用自带编译器的机器。
 
-**本章回答的那一个问题:**这个工程会被哪个编译器构建、它怎样被安装、以及怎样换成
-另一个。
+**本章回答的那一个问题：** 这个工程会被哪个编译器构建、它怎样被安装、以及怎样
+换成另一个。
 
-**不在这里:**这套解析是怎么实现的,那是 [91 —— 工具链机制内幕](91-toolchain-internals.md);
-以及目标怎么命名,那是 [21 —— 目标三元组](21-the-target-triple.md)。
+**不在这里：** 这套解析是怎么实现的，那是
+[91 —— 工具链机制内幕](91-toolchain-internals.md)；以及 target 怎样命名，那是
+[21 —— 目标三元组](21-the-target-triple.md)。
 
-> mcpp 维护一个独立的工具链沙盒,与系统 PATH 完全隔离。
+> mcpp 维护一个独立的工具链沙盒，与系统 PATH 完全隔离。
 
 ## 设计动机
 
-C++23 模块对编译器版本较为敏感,不同版本的 GCC / Clang 在模块语义
-处理上存在明显差异。系统包管理器提供的版本通常滞后,且多版本共存
-存在维护成本。mcpp 将工具链统一安装在沙盒目录
-(`~/.mcpp/registry/data/xpkgs/`)中,允许项目按需选择版本,且不会
-影响系统环境。
+C++23 模块对编译器版本相当敏感，不同版本的 GCC / Clang 在模块语义的处理上
+存在明显差异。系统包管理器提供的版本通常滞后，而多版本共存又带来维护负担。
+mcpp 把所有工具链装进同一个沙盒目录（`~/.mcpp/registry/data/xpkgs/`），让每个
+工程按需选择自己需要的版本，而不触碰系统环境。
 
 ## 自动安装
 
-首次运行 `mcpp build` 时,若尚未配置工具链,mcpp 会安装并持久化一对与当前
-宿主匹配的默认值:
+首次运行 `mcpp build` 且尚未配置工具链时，mcpp 会为当前宿主安装并持久化一对
+默认值。这个选择是按宿主区分的：
 
-- Linux x86_64 使用面向原生 glibc ABI 的 `gcc@16.1.0`,X11、OpenGL 与系统库
-  可直接链接。
-- 其他 Linux 架构使用 `gcc@15.1.0-musl`,这是自包含的全静态工具链。
+- Linux x86_64 使用面向原生 glibc ABI 的 `gcc@16.1.0`，X11、OpenGL 与系统库
+  因此可以直接使用。
+- 其他 Linux 架构使用 `gcc@15.1.0-musl`，这是一套自包含的全静态工具链。
 - macOS 使用 `llvm@20.1.7`。
-- Windows 存在可用 MSVC 时使用面向 MSVC ABI 的 `llvm@20.1.7`;没有可用 MSVC
-  时使用 `gcc@16.1.0` 和 `x86_64-windows-gnu` target(MinGW-w64,默认 static)。
+- Windows 上存在可用 MSVC 时使用面向 MSVC ABI 的 `llvm@20.1.7`；没有可用
+  MSVC 时使用 `gcc@16.1.0`，target 为 `x86_64-windows-gnu`（MinGW-w64，默认
+  静态链接）。
 
-在 Linux 宿主上,全静态 musl 产物始终只差一个参数:
+在 Linux 宿主上，全静态的 musl 产物始终只差一个参数：
 `mcpp build --target x86_64-linux-musl`。
 
-后续构建不再触发该流程。
+后续构建不会再次触发这个流程。
 
 > [!TIP]
-> 在 CI 中可设置 `MCPP_NO_AUTO_INSTALL=1` 只关闭工具链自动安装。需要完整
-> 离线时,使用 `mcpp --offline` 或 `MCPP_OFFLINE=1`;它们还会禁止索引刷新和下载。
+> 在 CI 中，设置 `MCPP_NO_AUTO_INSTALL=1` 可以只关闭工具链自动安装。需要
+> 完全离线的命令时，使用 `mcpp --offline` 或 `MCPP_OFFLINE=1`；它们同时也会
+> 阻止索引刷新与下载。
 
-## 身份模型:Toolchain × Target
+## 身份模型：Toolchain × Target
 
-一切命名由两条正交轴构成:
+一切命名由两条正交轴构成：
 
-- **toolchain** = `family@version`,family ∈ `gcc | llvm | msvc | emsdk | android-ndk` ——*用谁编*
-- **target** = 三段 triple `arch-os[-env]`(如 `x86_64-linux-musl`、
-  `x86_64-windows-gnu`、`aarch64-macos`)——*产出给谁*
+- **toolchain** = `family@version`，`family` ∈ `gcc | llvm | msvc | emsdk |
+  android-ndk`——即*由谁编译*
+- **target** = 一个三段三元组 `arch-os[-env]`（例如 `x86_64-linux-musl`、
+  `x86_64-windows-gnu`、`aarch64-macos`）——即*产出给谁用*
 
-变体(`gnu | musl | msvc`)在 target 的 `env` 段里,永远不进工具链名字;
-"cross" 也不是名字——它只是 `host ≠ target` 这一关系,原生与交叉是同一条
-命令。旧拼写(`musl-gcc`、`gcc@15.1.0-musl`、`mingw`、`mingw-cross`、
-`clang`、`x86_64-w64-mingw32`)作为别名**永久接受**,归一到该模型并打印
-一行 `note:` 提示。
+变体（`gnu | musl | msvc`）存在于 target 的 `env` 段里，永远不进工具链名字。
+「cross」同样不是一个名字——它只是 `host ≠ target` 这一层关系，原生构建与
+交叉构建用的是同一条命令。旧拼写（`musl-gcc`、`gcc@15.1.0-musl`、`mingw`、
+`mingw-cross`、`clang`、`x86_64-w64-mingw32`）作为别名被**永久接受**，归一到
+这套模型并打印一行 `note:` 提示。
 
 ## 手动安装
 
 ```bash
-mcpp toolchain install gcc 16.1.0           # host target(Linux 上为 GNU libc)
-mcpp toolchain install llvm 20.1.7          # LLVM/Clang,macOS 与有可用 MSVC 的 Windows 默认工具链
-mcpp toolchain install gcc 16 --target x86_64-linux-musl    # musl target 的链
-mcpp toolchain install --target x86_64-windows-gnu          # 省略 family →
-                                            # 取该 target 的约定 pin(gcc@16.1.0)
+mcpp toolchain install gcc 16.1.0           # host target (GNU libc on Linux)
+mcpp toolchain install llvm 20.1.7          # LLVM/Clang, default on macOS and Windows with usable MSVC
+mcpp toolchain install gcc 16 --target x86_64-linux-musl    # musl target payload
+mcpp toolchain install --target x86_64-windows-gnu          # family omitted → the
+                                            # target's convention pin (gcc@16.1.0)
 ```
 
-显式安装主要用于 CI 缓存预热与离线准备——`mcpp build --target <triple>`
-会自动安装该 target 所需的一切。
+显式安装主要用于 CI 缓存预热与离线准备——`mcpp build --target <triple>` 会
+自动安装该 target 所需的一切。
 
-版本号支持部分匹配:
+版本号支持部分匹配：
 
 ```bash
-mcpp toolchain install gcc 15               # 安装 15.x.y 中的最高版本(15.1.0)
-mcpp toolchain install gcc@16               # 同样支持 @ 形式
+mcpp toolchain install gcc 15               # installs the highest 15.x.y version (15.1.0)
+mcpp toolchain install gcc@16               # the @ form works too
 ```
 
 ## 切换默认工具链
 
-默认值是一*对*——toolchain 轴 + target 轴(省略 target = host):
+默认值是一*对*——toolchain 轴 + target 轴（省略 target 即宿主）：
 
 ```bash
 mcpp toolchain default gcc@16.1.0
-mcpp toolchain default gcc 15               # 部分版本时,从已安装的版本中选择最高
-mcpp toolchain default gcc@16 --target x86_64-linux-musl   # "默认就要全静态 musl"
+mcpp toolchain default gcc 15               # partial version → highest installed match
+mcpp toolchain default gcc@16 --target x86_64-linux-musl   # "default to fully-static musl"
 ```
 
-这对默认值持久化为 `~/.mcpp/config.toml` 中的
-`[toolchain] default = "gcc@16.1.0"` + `default_target = "x86_64-linux-musl"`。
-(存量 config 里 `default = "gcc@15.1.0-musl"` 这类合并拼写原样可用。)
+这一对默认值持久化为 `~/.mcpp/config.toml` 中的
+`[toolchain] default = "gcc@16.1.0"` 加上
+`default_target = "x86_64-linux-musl"`。（存量配置里 `default =
+"gcc@15.1.0-musl"` 这类合并拼写原样可用，不受影响。）
 
 ### 一次构建的编译器选定
 
-有五种来源会给它命名。它们是分级的,而这套分级正是让工程能写下的那两条压过
-mcpp 自己保管的一切的原因:
+有五种来源可以给它命名。它们分级排列，而正是这套分级，让工程能够写下的那两条
+压过 mcpp 自己保管的一切：
 
 | | 来源 | mcpp 可否改写 |
 |---|---|---|
-| 1 | `mcpp.toml` 的 `[target.<triple>] toolchain` | 否 |
-| 2 | `mcpp.toml` 的 `[toolchain] default`(或 `MCPP_TOOLCHAIN`) | 否 |
-| 3 | 依赖的 `requires = ["mcpp:compiler=<族>"]` | — |
-| 4 | 目标行的 pin(当该行的载荷供给目标侧时) | 是 |
-| 5 | `mcpp toolchain default`,以及 mcpp 的首次运行默认值 | 是 |
+| 1 | `mcpp.toml` 里的 `[target.<triple>] toolchain` | 否 |
+| 2 | `mcpp.toml` 里的 `[toolchain] default`（或 `MCPP_TOOLCHAIN`） | 否 |
+| 3 | 依赖给出的 `requires = ["mcpp:compiler=<族>"]` | — |
+| 4 | target 行自身的 pin（当该行的载荷供给 target 侧时） | 是 |
+| 5 | `mcpp toolchain default`，以及 mcpp 首次运行时的默认值 | 是 |
 
-**依赖可以要求一个编译器族。** 一份 C++ 运行时是为某一个族 configure 过的,
-并把这份配置记在它所发布的头文件里,因此供给它的包会说明自己是为哪个编译器构建
-的。当这条要求与第 4、5 级 —— mcpp 自己推导出来的答案 —— 不同时,mcpp 就为这次
-构建取用被要求的那个族:
+**一个依赖可以要求一个编译器族。** 一份 C++ 运行时是为某一个族 configure
+过的，并把这份配置记在自己发布的头文件里，因此提供它的包会说明自己是为哪个
+编译器构建的。当这条要求与第 4、5 级——mcpp 自己推导出来的答案——不同时，
+mcpp 就为这次构建取用被要求的那个族：
 
 ```
 $ mcpp build
@@ -114,16 +118,17 @@ $ mcpp build
              not your gcc@16.1.0 — this project only
 ```
 
-**不写任何东西。** 不写 `~/.mcpp/config.toml`,也不写工程的 `mcpp.toml`。
-这条要求是**这次构建**的性质,就只作用于这次构建;这台机器的默认值保持原样,对
-其他每一个工程都是。版本取自已经装好的那些 —— 与 `mcpp toolchain default <族>`
-走的是同一条解析 —— 只有该族一个都没装时,才取生态自己的 pin。这个 pin 取自载荷正是
-要求所指的那个载荷的行:`llvm` 取 `llvm@…` 的 pin,而不取 Android NDK 或 emsdk 的 ——
-它们是别的载荷里的 llvm 族编译器;`mcpp:compiler=emsdk` 或
-`mcpp:compiler=android-ndk` 取它自己载荷的 pin(mcpp 2026.9.15.2+)。
+**什么都不写。** 不写 `~/.mcpp/config.toml`，也不写工程自己的 `mcpp.toml`。
+这条要求是**这次构建**的性质，所以只作用于这次构建；这台机器的默认值对其他
+每一个工程都保持原样。版本取自已经装好的那些——走的是与
+`mcpp toolchain default <族>` 相同的解析——只有该族一个版本都没装时，才取
+生态自己的 pin。这个 pin 取自载荷正是要求所指的那一行：`llvm` 取
+`llvm@…` 的 pin，不取 Android NDK 或 emsdk 的——它们是其他载荷里的 llvm 族
+编译器；`mcpp:compiler=emsdk` 或 `mcpp:compiler=android-ndk` 取它自己载荷的
+pin(mcpp 2026.9.15.2+)。
 
-**工程写下的编译器不会被改写。** 第 1、2 级上工程已经说明了它用什么构建,依赖
-与之不一致就是一次真实的矛盾:
+**工程自己写下的编译器不会被改写。** 在第 1、2 级上，工程已经说明了自己用
+什么构建，依赖与之不一致就是一次真实的矛盾：
 
 ```
 error: `openkal-llvm-runtime@0.1.3` requires the compiler to be `llvm`.
@@ -135,9 +140,9 @@ error: `openkal-llvm-runtime@0.1.3` requires the compiler to be `llvm`.
        compiler the graph requires and changes no configuration to do it.
 ```
 
-**两个依赖要求不同的族是错误,不是一次挑选。** 一次构建只有一个编译器;按图的
-遍历顺序来定,等于让作者既不书写也无法预测的顺序做决定,并且会满足其中一个包而
-让另一个在它自己的头文件里失败。
+**两个依赖要求不同的族是一个错误，不是一次挑选。** 一次构建只有一个编译器；
+按图的遍历顺序来决定，等于让一个作者既写不出来也预测不了的顺序做主，而且会
+满足其中一个包，让另一个包在自己的头文件里失败。
 
 ## 查看工具链状态
 
@@ -145,7 +150,7 @@ error: `openkal-llvm-runtime@0.1.3` requires the compiler to be `llvm`.
 mcpp toolchain list
 ```
 
-输出分两块——每条轴一块:
+输出分两块——每条轴各一块：
 
 ```
 Toolchains:
@@ -166,140 +171,142 @@ Available toolchains (run `mcpp toolchain install <family> <version>`):
      llvm 20.1.7
 ```
 
-`*` 标记当前的默认对。Targets 块是 target 词汇表的实时视图,共四种状态:
+`*` 标记当前的默认对。Targets 块是 target 词汇表的实时视图，共有四种状态：
 
 | 状态 | 含义 | 后续步骤 |
 |---|---|---|
 | `installed` | 本机已有的载荷就能产出它 | 无 |
-| `available` | 本宿主存在可装的载荷 | `mcpp toolchain install` |
-| `via dependency graph` | 编译器在本机,而目标的系统不在,由包供给 | 依赖一个实现该目标内核接口与 C 库的包 |
-| `planned` | 已登记在词表中,尚未发布 | — |
-
-**不在这个块里的 target,在本机根本构建不了**——而这句话现在比以前更窄。
-mcpp 2026.8.25.2 之前,这个块只列载荷能服务的那些,于是「系统来自依赖图」的
-target 缺席,而同一台机器能为它产出真实的产物。`x86_64-windows-msvc` 与
-`aarch64-macos` 在 Linux 宿主上仍然缺席,这是**对的**:MSVC 与 macOS SDK 是宿主
-专有的,依赖替代不了。
-
-## Windows PE 之 MinGW-w64(`x86_64-windows-gnu`,无需 Visual Studio)
-
-**没装 Visual Studio 时,这就是 Windows 上的默认值。** Windows 自带的只有
-UCRT 运行时 DLL,MSVC STL 与 Windows SDK 都只随 Visual Studio 的
-"Desktop development with C++" 负载安装。而 llvm 在 Windows 上打的是 MSVC ABI,
-两者都需要,所以 mcpp 首跑时会探测机器上是否有可用的 MSVC(STL **与** SDK
-两者齐备 —— 只具备其一才是真正的风险),探测失败则落到这里,并把选择持久化,之后的
-构建不再重复提示。无需任何安装或配置。
-
-同一道检查也会修复既有配置:如果 mcpp 早先自己选定的 `[toolchain] default`
-在这台机器上已经不可用,它会被就地改写,并打印一行说明。但**用户在
-`mcpp.toml` 里显式写下的** `[toolchain]`(或 `[target.X].toolchain`)永远不会
-被推翻——一个需要 MSVC ABI 去链接 vcpkg 预编译 `.lib` 的工程,得到的是一条
-指明替代方案的错误,而不是被静默换掉 ABI。
-
-mcpp 里 "MinGW" 是一个 **target**,不是工具链名:`x86_64-windows-gnu`
-——GCC 产出 Windows PE(GNU CRT)。两种宿主用同一个身份、同一条命令;
-由哪个自包含 payload 来承接是自动分流的(Windows 宿主 → winlibs UCRT
-构建;Linux 宿主 → 从源码构建的 MSVCRT 交叉链,CI 中经 wine 实测):
+| `available` | 本宿主上存在可安装的载荷 | `mcpp toolchain install` |
+| `via dependency graph` | 编译器在本机，而该 target 的系统不在，由包供给 | 依赖一个实现该 target 内核接口与 C 库的包 |
+| `planned` | 已登记在词汇表中，尚未发布 | — |
+
+**不出现在这个块里的 target，在本机根本构建不了**——而这句话现在比以前更窄。
+在 mcpp 2026.8.25.2 之前，这个块只列出载荷能服务的那些，于是「系统来自依赖图」
+的 target 会缺席，即便同一台机器能为它产出真实的产物。`x86_64-windows-msvc`
+与 `aarch64-macos` 在 Linux 宿主上仍然缺席，这是**对的**：MSVC 与 macOS SDK
+是宿主专有的，没有依赖能替代它们。
+
+## Windows PE 之 MinGW-w64(`x86_64-windows-gnu`，无需 Visual Studio)
+
+**没有装 Visual Studio 时，这就是 Windows 上的默认值。** Windows 自带 UCRT
+运行时 DLL，但不带 MSVC STL 或 Windows SDK——两者都只随 Visual Studio 的
+「Desktop development with C++」负载一起安装。由于 Windows 上的 llvm 打的是
+MSVC ABI，两者都需要，所以 mcpp 首次运行时会探测机器上是否有可用的 MSVC
+（STL **与** SDK 两者齐备——只具备其一才是真正的陷阱），探测不到就落回这里，
+并把这个选择持久化，之后的构建不再重复提示。不需要安装或配置任何东西。
+
+同一道检查也会修复既有配置：如果 mcpp 早先自己选定的 `[toolchain] default`
+在这台机器上已经不可用了，它会被就地改写，并打印一行说明。但用户在
+`mcpp.toml` 里显式写下的 `[toolchain]`（或 `[target.X].toolchain`）永远不会
+被推翻——一个需要 MSVC ABI 去链接 vcpkg 预编译 `.lib` 文件的工程，得到的是
+一条指明替代方案的错误，而不是被静默换掉 ABI。
+
+mcpp 里的「MinGW」是一个 **target**，不是工具链名：`x86_64-windows-gnu`——
+GCC 产出带 GNU CRT 的 Windows PE。两种宿主用同一个身份、同一条命令；由哪个
+自包含载荷来承接，是自动分流的（Windows 宿主 → winlibs UCRT 构建；Linux
+宿主 → 从源码构建的 MSVCRT 交叉工具链，在 CI 中经 wine 实测）：
 
 ```bash
-mcpp build --target x86_64-windows-gnu       # Windows 或 Linux 上皆可
+mcpp build --target x86_64-windows-gnu       # from Windows OR Linux
 mcpp toolchain default gcc@16 --target x86_64-windows-gnu
-# 旧拼写仍然接受:mingw@16.1.0、mingw-cross@16.1.0、
+# legacy spellings still accepted: mingw@16.1.0, mingw-cross@16.1.0,
 # --target x86_64-w64-mingw32
 ```
 
-它走常规的 GCC 模块管线(`gcm.cache`、经 libstdc++ `bits/std.cc` 的
-`import std`)。该 target 默认 linkage 为 **static**——产出的 `.exe`
-完全自包含(无需随包分发 `libstdc++-6.dll`,可直接在 wine 下运行);
-要退出请写在 target 段上——`linkage` 只认精确 triple(见
-[mcpp.toml](04-mcpp-toml.md) §2.7),`[build] linkage` 这个键并不存在,写了会被静默忽略:
+它走常规的 GCC 模块管线（`gcm.cache`、经由 libstdc++ 的 `bits/std.cc` 实现
+`import std`）。该 target 的默认 linkage 是**静态**——产出的 `.exe` 完全
+自包含（不需要随包分发 `libstdc++-6.dll`，可以直接在 wine 下运行）。要退出这
+个默认值，写在 target 段上——`linkage` 只认精确三元组（见
+[mcpp.toml](04-mcpp-toml.md) §2.7），`[build] linkage` 这个键并不存在，写了
+会被静默忽略：
 
 ```toml
 [target.x86_64-windows-gnu]
 linkage = "dynamic"
 ```
 
-manifest 中:
+manifest 中：
 
 ```toml
 [toolchain]
-windows = "gcc@16"            # Windows 上的 gcc family = MinGW-w64
-# 旧值 "mingw@16.1.0" 原样可用
+windows = "gcc@16"            # gcc family on Windows = MinGW-w64
+# legacy value "mingw@16.1.0" keeps working
 ```
 
-产物名跟随 **target**;静态库的命名约定分岔点是 triple 的 *env* 段,而不是 OS:
+产物名跟随 **target**，而静态库的命名约定分岔点是三元组的 *env* 段，不是
+OS：
 
 | Target | `kind = "lib"` 产出 |
 |---|---|
-| `x86_64-windows-gnu` | `libfoo.a`(GNU 约定) |
-| `x86_64-windows-msvc` | `foo.lib`(MSVC 约定) |
+| `x86_64-windows-gnu` | `libfoo.a`（GNU 约定） |
+| `x86_64-windows-msvc` | `foo.lib`（MSVC 约定） |
 
-2026.8.3.3 之前,Windows 宿主上的 mingw 构建产出的是 `foo.lib` —— 一个 GNU
-archive 顶着 MSVC 的名字,MSVC 拿不去用。若有脚本按 `*.lib` 收集产物
-`windows-gnu` 的产物,现在要改成 `*.a`。
+2026.8.3.3 之前，Windows 宿主上的 mingw 构建产出的是 `foo.lib`——一个 GNU
+归档顶着 MSVC 的名字，MSVC 拿不去用。若有脚本按 `*.lib` 收集
+`windows-gnu` 构建的产物，现在要改成 `*.a`。
 
-## Windows 上产出 Linux ELF(`x86_64-linux-musl`,无需 WSL)
+## Windows 上产出 Linux ELF(`x86_64-linux-musl`，无需 WSL)
 
-上一节的镜像:一台 Windows 机器直接产出**完全静态的 Linux 二进制**,
-不需要 WSL、不需要容器,也不往系统里装任何东西。
+上一节的镜像：一台 Windows 机器直接产出**完全静态的 Linux 二进制**，不需要
+WSL、不需要容器，也不往系统里装任何东西。
 
 ```bash
-mcpp build --target x86_64-linux-musl        # Windows 或 Linux 上皆可
+mcpp build --target x86_64-linux-musl        # from Windows OR Linux
 ```
 
-两种宿主上这条命令**逐字相同**,因为 "交叉" 在 mcpp 里不是一个名字,
-它只是 `host ≠ target` 这个关系。由哪个 payload 承接目标是自动分流的:
-Linux x86_64 宿主装原生 `musl-gcc`;Windows 宿主装一条 **canadian-cross**
-GCC(以 `x86_64-linux-gnu` 构建 → 运行于 `x86_64-w64-mingw32` → 产出
-`x86_64-linux-musl`)。两者都是 GCC 16.1.0,也都带 `bits/std.cc`,
-所以 `import std` 在两边行为一致。
+两种宿主上这条命令**逐字相同**，因为「cross」在 mcpp 里不是一个名字，它只是
+`host ≠ target` 这一层关系。由哪个载荷承接 target 是自动分流的：Linux x86_64
+宿主安装原生的 `musl-gcc`；Windows 宿主安装一条 **canadian-cross** GCC（以
+`x86_64-linux-gnu` 构建 → 运行于 `x86_64-w64-mingw32` → 产出
+`x86_64-linux-musl`）。两者都是 GCC 16.1.0，也都带 `bits/std.cc`，所以
+`import std` 在两边行为一致。
 
-产物是没有 `PT_INTERP` 的全静态 ELF —— 不挑发行版、不挑 libc,
-这正是 musl 成为第一个被打通的 Linux target 的原因:
+产物是没有 `PT_INTERP` 的全静态 ELF——不挑发行版、不挑 libc，这正是 musl
+成为第一个被打通的 Linux target 的原因：
 
 ```console
 $ file mcpp
 mcpp: ELF 64-bit LSB executable, x86-64, statically linked, stripped
 ```
 
-Windows 上**不支持** `x86_64-linux-gnu`:glibc target 还需要 `xim:glibc`
-与 `xim:linux-headers` 两个 sysroot payload,而它们只为 Linux 宿主发布。
-musl target 自包含,两者都不需要。
+Windows 上**不支持** `x86_64-linux-gnu`：glibc target 还需要 `xim:glibc` 与
+`xim:linux-headers` 两个 sysroot 载荷，而它们只为 Linux 宿主发布。musl
+target 自包含，两者都不需要。
 
-Windows 上也**不支持跨 arch**(如 `aarch64-linux-musl`)—— canadian-cross
-payload 是按宿主 arch 构建的。**macOS 宿主则完全没有面向 Linux 的 payload**,
-任何 Linux target 都不可用。
+Windows 上也**不支持跨架构**（例如 `aarch64-linux-musl`）——canadian-cross
+载荷是按宿主架构构建的。**一台 macOS 宿主完全没有面向 Linux 的载荷**，任何
+Linux target 从那里都够不到。
 
-判据不必靠记:`mcpp toolchain list` 只列出当前宿主真正装得上的 target,
-Targets 一栏里没有的,就是这台机器确实服务不了(实现见
-`toolchain::host_can_serve`)。
+这一切不必靠记忆：`mcpp toolchain list` 只列出当前宿主真正能安装的
+target，Targets 一栏里没有的，就是这台机器确实服务不了（实现见
+`toolchain::host_can_serve`）。
 
 ## MSVC(Windows)
 
-一个 MSVC toolset 有两条路径进入构建,由 **spec 的版本轴**决定是哪一条:
+一个 MSVC toolset 有两条路径进入构建，由 **spec 的版本轴**决定走哪一条：
 
-| Spec | 来源 | 解析到的编译器 |
+| Spec | 来源 | 解析出的编译器 |
 |---|---|---|
-| `msvc@system`(或裸 `msvc`) | 这台机器自己的 Visual Studio | 这里恰好装了什么就是什么 |
-| `msvc@<toolset>`(如 `msvc@14.44.35207`) | mcpp 安装的 xlings payload | 指名的那一个,在每台机器上一致 |
-
-它们不是"二选一",而是回答了不同的问题。`msvc@system` 问的是*"用这位开发者
-已经有的东西"*;`msvc@14.44.35207` 问的是*"用恰好这个编译器构建本工程"*。
-pinned toolset 之间、以及与系统 Visual Studio 之间都可以共存。
-
-> **`@system` 是 MSVC 独有的拼写。** 没有 `gcc@system`,也没有 `llvm@system`,
-> 这是有意的而不是漏了:mcpp 建立在用户态 OS xlings 之上,整条设计就是**把 host
-> 依赖降到最低** —— 工具链来自 manifest 点名的 payload,于是每台机器用同一个
-> 编译器。Windows 是唯一一处"拒绝使用已装好的东西"代价大于收益的地方:
-> Visual Studio 常常已经装了,又不总能重新分发。其它族写 `<family>@system` 会
-> 直接报错,并同时给出两种可能的写法。(不带族的
-> `[toolchain] … = "system"` —— 即 PATH 上的编译器 —— 是另一套、也是有意保留的
-> 逃生口,不受影响。)
+| `msvc@system`（或裸 `msvc`） | 这台机器自己的 Visual Studio | 这里装了什么就是什么 |
+| `msvc@<toolset>`（如 `msvc@14.44.35207`） | mcpp 安装的 xlings 载荷 | 指名的那一个，在每台机器上一致 |
+
+它们不是二选一，而是回答不同的问题。`msvc@system` 问的是「用这位开发者已经
+有的东西」；`msvc@14.44.35207` 问的是「用恰好这个编译器构建本工程」。pinned
+toolset 之间、以及与系统 Visual Studio 之间都可以共存。
+
+> **`@system` 是 MSVC 独有的拼写。** 没有 `gcc@system`，也没有
+> `llvm@system`，这是有意为之，不是遗漏：mcpp 建立在用户态 OS xlings 之上，
+> 整套设计都在把宿主依赖压到最低——工具链来自 manifest 点名的载荷，于是每台
+> 机器都用同一个编译器。Windows 是唯一一处「拒绝使用已经装好的东西」代价大于
+> 收益的地方：Visual Studio 常常已经装了，又不总能重新分发。写
+> `<family>@system` 给其他任何一个族都会直接报错，并同时给出两种可能的意图。
+> （不带族的 `[toolchain] … = "system"`——即 PATH 上的编译器——是另一条、
+> 同样有意保留的逃生口，不受影响。）
 
 ### `[toolchain] … = "system"` —— 拒绝
 
-**mcpp 只用它自己管理的工具链构建。** `PATH` 上现成的编译器不受支持,该配置会被**拒绝**,
-而不是提示:
+**mcpp 只用它自己管理的工具链构建。** 取自 `PATH` 的编译器不受支持，这项配置
+会被拒绝，而不是被提示：
 
 ```
 error: [toolchain] linux = "system" is not supported: mcpp builds only with
@@ -316,45 +323,48 @@ error: [toolchain] linux = "system" is not supported: mcpp builds only with
        see `mcpp toolchain list` for what is available.
 ```
 
-`msvc@system` 是**唯一的例外**,而且是另一种拼法:它点名的是一个**族**,mcpp 负责定位并识别
-其安装 —— 那是唯一一个编译器不能被重新分发的平台。见上一节。
+`msvc@system` 是**唯一的例外**，而且是另一种拼法：它点名的是一个**族**，
+mcpp 负责定位并识别其安装——那是唯一一个编译器无法被重新分发的平台。见上一节。
 
 #### 工具链与库答案不同的原因
 
-mcpp 对 host 依赖的规则并不是各条轴统一的,这个分叉是刻意的:
-
-- **mcpp 自身、以及 mcpp 生态发布的一切,都不依赖任何 host。** 工具链与 payload 都经由
-  xlings 获得 —— xim 索引或 mcpp-index。这正是构建能跨机器、跨 Linux 发行版复现的原因。
-- **工具链属于这份契约,所以它不是工程可以从 host 拿的东西。** mcpp 承诺的每一件事 ——
-  `import std` 可用、运行期闭包可计算、同一份构建在同事机器上和 CI 里一致 —— 都是关于
-  **一个 mcpp 解析出来、叫得出名字的编译器**的陈述。`PATH` 上的编译器让这些全部无法核验,
-  这就是这一条是拒绝的原因。
-- **程序链接哪些库,是程序自己的事。** 工程可以链 host 的库,也可以链自己的 `.so`。mcpp 会
-  说明这样做的代价,并指出受支持的路径 —— 声明该 provider 让它从 mcpp-index 解析;索引尚未
-  收录时,**把包贡献进 mcpp-index** 就是那条路 —— 但只要结果能构建、能运行,就不强行拒绝。
-  产物是开发者的,由他保证。
-
-而"证明跑不起来"的构建在两条轴上都仍然是错误:运行期闭包不可满足时会被拒绝,因为产物根本
-起不来。见[二进制分发](12-binary-distribution.md)。
+mcpp 对宿主依赖的规则，并不是各条轴统一的，这个分叉是刻意的：
+
+- **mcpp 自身、以及 mcpp 生态发布的一切，都不依赖任何宿主。** 工具链与载荷
+  都经由 xlings 获得——xim 索引或 mcpp-index。这正是构建能跨机器、跨 Linux
+  发行版复现的原因。
+- **工具链属于这份契约，所以它不是工程可以从宿主拿的东西。** mcpp 承诺的
+  每一件事——`import std` 可用、运行期闭包可计算、同一份构建在同事机器上和
+  CI 里一致——都是关于一个 mcpp 解析出来、叫得出名字的编译器的陈述。取自
+  `PATH` 的编译器让这一切都无法核验，这正是这一项会被拒绝的原因。
+- **程序链接哪些库，是程序自己的事。** 一个工程可以链接宿主的库，也可以链接
+  自己的 `.so`。mcpp 会说明这样做的代价，并指出受支持的路径——声明该
+  provider，让它从 mcpp-index 解析；索引尚未收录时，把包贡献进
+  mcpp-index 就是那条路——但只要结果能构建、能运行，mcpp 就不强行拒绝。
+  产物属于开发者，由他保证。
+
+而「已证明跑不起来」的构建，在两条轴上都仍然是错误：一个满足不了的运行期
+闭包会被拒绝，因为产物根本起不来。见
+[二进制分发](12-binary-distribution.md)。
 
 ### `msvc@system` —— 机器自己的 Visual Studio
 
-mcpp 只负责定位并识别已安装的 Visual Studio / Build Tools,**从不**安装、
+mcpp 只负责定位并识别已安装的 Visual Studio / Build Tools，**从不**安装、
 升级或卸载它。
 
 ```bash
 mcpp toolchain default msvc
 ```
 
-定位顺序:
+mcpp 按下面这个顺序自动定位：
 
-1. **`VSINSTALLDIR`** —— 由开发者命令提示符或跑过 `vcvarsall` 的 CI 步骤设置。
-   这是一个**回答**而不是猜测,所以排在下面几种探测之前。
-2. `vswhere.exe`(含 prerelease / Insiders 实例)
+1. **`VSINSTALLDIR`**——由开发者命令提示符，或跑过 `vcvarsall` 的 CI 步骤
+   设置。这是一个**声明**而不是一次探测，所以排在下面几种探测之前。
+2. `vswhere.exe`（含 prerelease / Insiders 实例）
 3. `VS*COMNTOOLS`
 4. 标准的 `Program Files\Microsoft Visual Studio\<year>\<edition>` 路径
 
-随后识别涉及的各个版本,并持久化为稳定 spec `msvc@system`:
+随后识别涉及的各个版本，并持久化为稳定的 spec `msvc@system`：
 
 ```
 Detected   msvc 19.44.35211 (VS 2022 BuildTools) (VC tools 14.44.35207)
@@ -363,12 +373,12 @@ Detected   msvc 19.44.35211 (VS 2022 BuildTools) (VC tools 14.44.35207)
 Default    set to msvc@system (was: llvm@20.1.7)
 ```
 
-若机器上没有 Visual Studio,mcpp 会报告该情况并给出两条路径:一个可由 mcpp 安装的
-pinned toolset,或者 Visual Studio Installer /
+如果机器上没有 Visual Studio，mcpp 会报告这一情况，并给出两条路径：一个
+mcpp 可以安装的 pinned toolset，或者 Visual Studio Installer /
 `winget install Microsoft.VisualStudio.2022.BuildTools`。
 
-`mcpp toolchain list` 会把检测到的 MSVC 列在单独的 `System:` 分区,
-`mcpp self doctor` 在 Windows 上会报告它的状态。manifest 里:
+`mcpp toolchain list` 会把检测到的 MSVC 列在单独的 `System:` 分区，
+`mcpp self doctor` 在 Windows 上会报告它的状态。manifest 里：
 
 ```toml
 [toolchain]
@@ -378,98 +388,106 @@ windows = "msvc@system"
 ### `msvc@<toolset>` —— mcpp 安装并 pin 的 toolset
 
 ```bash
-mcpp toolchain list --available msvc     # 可以 pin 哪些
+mcpp toolchain list --available msvc     # what can be pinned
 mcpp toolchain install msvc 14.44.35207
 ```
 
-这在每个方面都和 `gcc@16.1.0` 一样:payload 下载进 mcpp 自己的 store,多个
-toolset 共存,`mcpp toolchain remove msvc@<toolset>` 卸载其中一个,manifest 里
-点名的那个会在首次构建时自动安装。
+这在每个方面都和 `gcc@16.1.0` 一样：载荷下载进 mcpp 自己的 store，多个
+toolset 可以共存，`mcpp toolchain remove msvc@<toolset>` 卸载其中一个，
+manifest 里点名的那个会在首次构建时自动安装。
 
 ```toml
 [toolchain]
 windows = "msvc@14.44.35207"
 ```
 
-**这里的版本是 toolset 目录名**(`14.44.35207` —— 即 `VC\Tools\MSVC\` 下的
-目录名、也是 `-vcvars_ver` 接受的值),**不是** cl banner 版本
-(`19.44.35211`),也不是产品年份。机器上不需要预装任何东西:payload 带来编译器、
-STL,以及通过它的 `xim:windows-sdk` 依赖带来 ucrt/um 的头文件与导入库。
+**这里的版本是 toolset 目录名**（`14.44.35207`——即 `VC\Tools\MSVC\` 下的
+目录名，也是 `-vcvars_ver` 接受的值），**不是** cl banner 的版本
+(`19.44.35211`)，也不是产品年份。机器上不需要预装任何东西：载荷带来编译器、
+STL，以及通过它的 `xim:windows-sdk` 依赖带来的 ucrt/um 头文件与导入库。
 
-> **已变更:** `msvc@19.44` 过去的含义是"用系统 MSVC,并校验其 banner 以 19.44
-> 开头" —— 这条只有 `mcpp toolchain default` 会查,构建则静默忽略。现在版本轴
-> 在所有地方都指 toolset。写成 `19.x` 会得到一条同时给出两种替代写法的错误
-> —— `msvc@system`,或那台机器实际拥有的 toolset 版本。
+> **已变更：** `msvc@19.44` 过去的含义是「用系统 MSVC，并校验它的 banner 以
+> 19.44 开头」——这一条只有 `mcpp toolchain default` 会检查，构建则静默
+> 忽略。现在版本轴在所有地方都指向一个 toolset。写成 `19.x` 会得到一条同时
+> 给出两种替代写法的错误——`msvc@system`，或者那台机器实际拥有的 toolset
+> 版本。
 
 ### 原生 cl.exe 构建
 
-自 0.0.90 起两条来源都可用:mcpp 从 VC tools + Windows SDK 合成 INCLUDE/LIB
-环境(不经 `vcvarsall`),把 `std.ixx`/`std.compat.ixx` staging 成 `.ifc` BMI,
-用 `/interface /TP /ifcOutput` 编译 `.cppm` 模块单元,用 `/scanDependencies`
-扫描,并通过 response file 调 `link.exe`/`lib.exe` 链接。
+自 0.0.90 起，两种来源在这方面都可用：mcpp 从 VC tools + Windows SDK 合成
+INCLUDE/LIB 环境（不经过 `vcvarsall`），把 `std.ixx`/`std.compat.ixx`
+staging 成 `.ifc` BMI，用 `/interface /TP /ifcOutput` 编译 `.cppm` 模块
+单元，用 `/scanDependencies` 扫描依赖，并通过 response file 调用
+`link.exe`/`lib.exe` 完成链接。
 
-**Windows SDK 跟着来源走**,因为两条来源回答的是不同的问题,SDK 也必须如此:
+**Windows SDK 跟随来源走**，因为两种来源回答的是不同的问题，SDK 的选定
+也必须如此：
 
 | 来源 | SDK 的选定方式 |
 |---|---|
-| `msvc@<toolset>` | **随该 toolset 一起装进 mcpp store 的** `xim:windows-sdk` payload。环境里的 `WindowsSdkDir` / `WindowsSdkVersion` 会被**忽略**,并且 mcpp 会打印一行 `note:` 说明。 |
-| `msvc@system` | 先 **`WindowsSdkDir`**(+ `WindowsSdkVersion`),再 `C:\Program Files (x86)\Windows Kits\10`。 |
+| `msvc@<toolset>` | **随该 toolset 一起装进 mcpp store 的** `xim:windows-sdk` 载荷。环境里的 `WindowsSdkDir` / `WindowsSdkVersion` 会被**忽略**，mcpp 会打印一行 `note:` 说明这一点。 |
+| `msvc@system` | 先看 **`WindowsSdkDir`**（与 `WindowsSdkVersion`），没有声明时再看 `C:\Program Files (x86)\Windows Kits\10`。 |
 
-这种不对称正是要点。pin 一个 toolset 是在承诺"两台机器用同一套头文件编同一份
-源码";一个能悄悄改写它的环境变量会把这条承诺降格成偏好。反过来,机器自己的
-SDK 只能靠找,而在那里"明确声明"应当压过"扫描" —— 和 `VSINSTALLDIR` 压过
-`vswhere` 是同一条优先级。
+这种不对称正是要点所在。pin 一个 toolset，是在承诺「两台机器用同一套头文件
+编译同一份源码」；一个能被环境悄悄改写的变量，会把这条承诺降格成一种偏好。
+反过来，机器自己的 SDK 只能靠查找才能确定，而在那里，一个明确的声明应当压过
+一次扫描——与 `VSINSTALLDIR` 压过 `vswhere` 是同一条优先级。
 
-如果一个 pinned toolset 旁边没有 SDK payload(比如较老的安装),mcpp 会退回用
-机器上的 SDK 而不是失败 —— 并且会说出来,因为那次构建已经不可复现,而除此之外
-没有任何东西会记录这件事。
+如果一个 pinned toolset 旁边没有 SDK 载荷（比如一次较老的安装），mcpp 会
+退回使用机器上的 SDK，而不是直接失败——并且会说出来，因为那次构建已经不可
+复现，而除此之外没有任何东西会记录这件事。
 
-一个根目录只有**两半都在**才算 SDK —— `Include\<v>\ucrt\corecrt.h` **且**
-`Lib\<v>\um\<arch>\kernel32.lib`。只有头文件、没有导入库的根会被跳过而不是
-被选中,于是一个只解包了一半的 payload 不会压过机器上完整的 SDK,也就不会在
-构建的最后一刻变成 `LNK1104: cannot open file 'kernel32.lib'`。
+一个根目录只有**两半都在**才算一个 SDK——`Include\<v>\ucrt\corecrt.h`
+**且** `Lib\<v>\um\<arch>\kernel32.lib`。只有头文件、没有导入库的根目录会被
+跳过而不是被选中，于是一个只解包了一半的载荷不会压过机器上完整的 SDK，也就
+不会在构建的最后一刻变成 `LNK1104: cannot open file 'kernel32.lib'`。
 
-解析出的 SDK 版本是这次构建的**运行时身份**(`ucrt@10.0.26100.0`)的一部分,
-因而也进入了给构建缓存做 key 的那个指纹:换 SDK 就换缓存键,和换编译器一样。
-它是一条**兼容性下限声明**,而不是 Linux 上 `glibc@2.39` 那种 payload 绑定 ——
-`ucrtbase.dll` 是 Windows 组件,mcpp 既不分发也不替换它。
+解析出的 SDK 版本是这次构建**运行时身份**的一部分（`ucrt@10.0.26100.0`），
+因而也进入了给构建缓存做 key 的那个指纹：换 SDK 就换缓存键，和换编译器一样。
+它是一条**兼容性下限声明**，而不是 Linux 上 `glibc@2.39` 那种载荷绑定——
+`ucrtbase.dll` 是 Windows 组件，mcpp 既不分发也不替换它。
 
-**CRT 模型。** 默认 `/MD`(host-coupled);下面两者任一都会选 `/MT`:
+**CRT 模型。** 默认是 `/MD`(host-coupled)；下面两者中任意一个都会选中
+`/MT`：
 
 ```toml
 [target.x86_64-windows-msvc]
-linkage     = "static"           # libc 那根轴 —— TARGET 段,或 `--static`
+linkage     = "static"           # the libc axis — TARGET section, or `--static`
 
 [build]
-cxx_runtime = "self-contained"   # C++ 运行时那根轴
+cxx_runtime = "self-contained"   # the C++ runtime axis
 ```
 
-注意这两个键分别属于哪个段:`linkage` 只认精确 triple,**没有 `[build] linkage`
-这个键** —— 写了会得到一条 "unsupported key (ignored)" 警告,而且不会切到静态
-CRT。
-
-toolset 自带的那份可再分发 CRT(`vcruntime140.dll` / `msvcp140.dll`)可以跟着
-产物走 —— 见 `docs/zh/04-mcpp-toml.md` 的 `cxx_runtime = "toolchain-coupled"`。
+注意这两个键分别属于哪个段：`linkage` 只认精确三元组，而且**没有
+`[build] linkage` 这个键**——写了会得到一条「unsupported key (ignored)」
+警告，并且不会切到静态 CRT。（本页在前几节已经明确说过这一点，而这里却给出
+了一个错误的写法。）在 MSVC ABI 上，这两者是同一个物理开关——`/MT`
+从同一个库里链接 C 与 C++ 运行时——所以两种拼写选中的是同一件事，含义相同。
+这是一个**整个工程**级的属性：一个工程只构建一份 `std` 模块，cl 会把
+`_MSVC_MT`/`_MSVC_MD` 烘进这份模块，所以一个按角色给出的覆盖
+（`cxx_runtime = { tests = … }`）会被拒绝，并给出一条说明，而不是在 ucrt
+头文件内部产生一次模块不匹配。
 
-## SDK 工具链(`emsdk`、`android-ndk`)
+## SDK 工具链（`emsdk`、`android-ndk`）
 
-五种工具链拼法里有两种命名的是一个 **SDK** 而不是一个裸编译器:`emsdk` 与
-`android-ndk`。它们的编译器**就是** clang —— 所以它们不是一个独立的编译器 family,
-mcpp 也不假装它们是 —— 而那份归档自带 sysroot、自带 C 库,并且这两者都自带一份
-生成好的 `std` 模块面。本节讲的就是这个差别。
+五种工具链拼法里，有两种命名的是一个 **SDK** 而不是一个裸编译器：`emsdk`
+与 `android-ndk`。它们的编译器*就是* clang——所以它们不是一个独立的编译器
+族，mcpp 也不假装它们是——但那份归档自带 sysroot、自带 C 库，并且这两者都
+自带一份生成好的 `std` 模块面。本节讲的就是这个差别。
 
-### 默认值:该行自己的钉
+### 默认无需声明
 
-一个目标行命名了它自己的载荷,而那个钉就是默认值。这两者都不需要在 `mcpp.toml`
-里写一行:
+一个 target 行命名了它自己的载荷，而那个 pin 就是默认值。下面两者都不需要
+在 `mcpp.toml` 里写一行：
 
 ```bash
-mcpp build --target wasm32-emscripten     # 解析到 emsdk@6.0.9
-mcpp build --target aarch64-linux-android # 解析到 android-ndk@30.0.16248370
+mcpp build --target wasm32-emscripten     # resolves emsdk@6.0.9
+mcpp build --target aarch64-linux-android # resolves android-ndk@30.0.16248370
 ```
 
-载荷在某个目标第一次需要它时**按需安装**,和一个 gcc 或 llvm 载荷完全一样。
-`mcpp toolchain list` 会在行旁边显示那个钉,而构建会报出是哪份归档回答的:
+载荷在某个 target 第一次需要它时**按需安装**，和一个 gcc 或 llvm 载荷完全
+一样。`mcpp toolchain list` 会在那一行旁边显示这个 pin，而构建会报出是哪份
+归档回答的：
 
 ```
 Resolved emsdk@6.0.9 → wasm32-emscripten → …/xim-x-emsdk/6.0.9/emscripten/em++
@@ -478,7 +496,7 @@ Resolved android-ndk@30.0.16248370 → aarch64-linux-android → …/prebuilt/li
 
 ### 也可以显式声明
 
-普通的按目标键照常可用,而点名该行自己的载荷总是被接受:
+普通的按 target 键照常可用，而点名该行自己的载荷总是被接受：
 
 ```toml
 [target.aarch64-linux-android]
@@ -488,17 +506,19 @@ toolchain = "android-ndk@30.0.16248370"
 toolchain = "emsdk@6.0.9"
 ```
 
-用它把版本跨机器钉住,或者选用比该行约定更新的载荷。**版本是自由的** —— 索引里
-发布过的都能解析 —— 所以一个工程就是用它走在默认值之前或留在它之后。
+用它可以把版本跨机器钉住，或者选用比该行约定更新的载荷。**版本是自由的**——
+索引里发布过的都能解析——所以一个工程正是靠这一点走在默认值之前，或者留在
+默认值之后。
 
-### 不可覆盖的部分及其依据
+### 不可覆盖的部分，以及原因
 
-对这两行,那个钉是一个**能力**而不是一个约定:它不是 mcpp 在几个都能服务该目标的
-载荷之间的偏好,而是唯一能服务它的东西。所以载荷的**名字**是固定的,版本是开放的:
+对这两行，那个 pin 是一个**能力**而不是一个约定：它不是 mcpp 在几个都能服务
+该 target 的载荷之间的偏好，而是唯一能服务它的东西。所以载荷的**名字**是
+固定的，版本是开放的：
 
 ```toml
 [target.aarch64-linux-android]
-toolchain = "llvm@22.1.8"        # 被拒绝
+toolchain = "llvm@22.1.8"        # refused
 ```
 
 ```
@@ -508,19 +528,19 @@ error: target 'aarch64-linux-android' cannot be emitted by 'llvm@22.1.8'.
        NDK, and no package adds them to another compiler.
 ```
 
-这次拒绝与代码生成无关。一个普通 clang 发 aarch64 ELF 完全没问题;它拿不出来的是
-**体系**。在声明处就说出来,比解析出 llvm 再在构建深处失败要好 —— 而后者正是这道闸
-存在之前发生的事:先是 `'__config' file not found`,然后是 bionic 自己头文件里的
-`Unversioned target triples are not supported!`,两句都没点名那个服务不了这一行的
-工具链。
+这次拒绝与代码生成无关。一个普通 clang 发 aarch64 ELF 完全没问题；它拿不出
+来的是**体系**。在声明处就说出来，比解析出 llvm 再在构建深处失败要好——而
+后者正是这道闸存在之前会发生的事：先是 `'__config' file not found`，然后是
+bionic 自己头文件里的 `Unversioned target triples are not supported!`，两句
+都没有点名那个服务不了这一行的工具链。
 
-`wasm32-emscripten` 按同一条规则、用它自己的句子拒绝:除了 Emscripten 没有东西发
-WebAssembly。
+`wasm32-emscripten` 按同一条规则、用它自己的句子拒绝：除了 Emscripten，没有
+东西能发 WebAssembly。
 
 ### 属于工程的那一半
 
-工具链是 SDK 的;**部署下限**是工程的,而它按平台各有自己的键 —— 见
-[04 — mcpp.toml](04-mcpp-toml.md) §2.7.3:
+工具链属于 SDK；**部署下限**属于工程，它按平台各自拥有自己的键——见
+[04 —— mcpp.toml](04-mcpp-toml.md) §2.7.3：
 
 ```toml
 [target.aarch64-linux-android]
@@ -532,100 +552,111 @@ min_api_level = 24               # Android
 macos_deployment_target = "14.0" # Apple
 ```
 
-一个 NDK 服务一个 API level 的**区间**,所以级别是工程的决定,而点名
-`android-ndk@<version>` 并不钉住其中任何一个。不写的话,mcpp 读 NDK 自己在
-`meta/platforms.json` 里声明的下限。
+一个 NDK 服务一段 API level 的区间，所以这个级别是工程自己的决定，点名
+`android-ndk@<version>` 并不会钉住其中任何一个。不写这个键时，mcpp 读 NDK
+自己在 `meta/platforms.json` 里声明的下限。
 
 ### 产物的运行方式
 
-模拟器和真机都不属于工具链这根轴。wasm 模块需要的是解释器而不是模拟器,由载荷说出它:
-`xim:emsdk` 在自身旁边写出 `.mcpp-toolchain.json`,其中的 `runner` 键就是它所依赖的
-`xim:node` 载荷里的 `node`。项目与依赖都没有声明 runner 时,`mcpp run` 与 `mcpp test`
-使用这个程序,因此不涉及 PATH 上的 `node`。载荷的 runner 是一个程序,产物路径追加在后;
-它或是载荷内的相对路径,或是持有该载荷的包存储之内的绝对路径,存储之外的路径一律忽略。
-在配方写出这个键之前安装的载荷没有描述文件,其产物仍按自身的 `#!/usr/bin/env node`
-一行运行,与之前相同。要让这样的载荷获得描述文件,先刷新索引再重装:`mcpp index update`,
-然后 `mcpp toolchain remove <spec>` 与 `mcpp toolchain install <spec>`。仅重装会再次按同一份
-配方安装,因为索引只在解析未命中时刷新,而不因配方变化而刷新;这一点在 2026.9.12.2 的沙箱
-验证中实测。在此之前,失败信息来自解释器自身(`/usr/bin/env: 'node': No such file or
-directory`),mcpp 尚未对它作出解释(#621)。
-
-对于产物在别处运行的目标,`runner` 键是一个 argv 前缀,而那个会话属于一个**包**而不属于引擎:
+模拟器和真机都不属于工具链这根轴。wasm 模块需要的是解释器而不是模拟器，由
+载荷说出它是谁：`xim:emsdk` 在自身旁边写出 `.mcpp-toolchain.json`，其中的
+`runner` 键就是它所依赖的 `xim:node` 载荷里的 `node`。项目与依赖都没有声明
+runner 时，`mcpp run` 与 `mcpp test` 使用这个程序，因此不涉及 PATH 上的
+`node`。载荷的 runner 是一个程序，产物路径追加在其后；它或者是载荷内的相对
+路径，或者是持有该载荷的包存储之内的绝对路径，存储之外的路径一律忽略。在
+配方写出这个键之前安装的载荷没有描述文件，其产物仍按自身的
+`#!/usr/bin/env node` 这一行运行，和之前一样。要让这样的载荷获得描述文件，
+先刷新索引再重装：`mcpp index update`，然后 `mcpp toolchain remove <spec>`
+与 `mcpp toolchain install <spec>`。仅仅重装会再次按同一份配方安装，因为
+索引只在解析未命中时刷新，而不因配方变化而刷新；这一点在 2026.9.12.2 的
+沙箱验证中实测过。在此之前，失败信息来自解释器自身
+(`/usr/bin/env: 'node': No such file or directory`)，mcpp 尚未对它作出解释
+(#621)。
+
+对于产物在别处运行的 target，`runner` 键是一个 argv 前缀，而那个会话属于
+一个**包**，不属于引擎：
 
 ```toml
 [target.x86_64-linux-android]
-runner = ["adb-run"]             # 来自 xim:android-platform-tools 的一个程序
+runner = ["adb-run"]             # a program from xim:android-platform-tools
 
 [target.aarch64-ios-sim]
-runner = ["simctl-run"]          # 来自 xim:apple-simulator-tools 的一个程序
+runner = ["simctl-run"]          # a program from xim:apple-simulator-tools
 ```
 
-runner 是一个 argv 前缀,而一次**会话**不是。在一台 iOS 模拟器上运行一个程序意味着:
-挑一台设备、若未启动则启动它、等待启动完成、spawn、并把程序自己的退出状态返回回来。
-清单里的一行没有开始也没有结束,这就是那部分工作住在一个包里的原因。
+runner 是一个 argv 前缀，而一次**会话**不是。在一台 iOS 模拟器上运行一个
+程序意味着：挑一台设备、若未启动则启动它、等待启动完成、spawn，并把程序自己
+的退出状态返回回来。清单里的一行没有开始也没有结束，这正是那部分工作住在
+一个包里的原因。
 
-## Apple 的 SDK 是被定位的,不是被安装的
+## Apple 的 SDK 是被定位的，不是被安装的
 
-三条 iOS 行 —— `aarch64-ios`、`aarch64-ios-sim` 与 `x86_64-ios-sim` —— 是一个平台
-可以取的另一种形状,值得与上面两个 SDK 工具链放在一起读,因为它们回答的是同一个
-问题,只是答法不同。
+三条 iOS 行——`aarch64-ios`、`aarch64-ios-sim` 与 `x86_64-ios-sim`——是一个
+平台可以取的另一种形状，值得与上面两个 SDK 工具链放在一起读，因为它们回答的
+是同一个问题，只是答法不同。
 
-**编译器是我们的;只有 SDK 是 Apple 的。** 任何足够新的 clang 都能为一个 iOS 部署
-目标产出 arm64 Mach-O,所以这三行钉的是 `llvm@22.1.8` —— 那个普通载荷,和
-`aarch64-macos` 用的是同一个。无法打包的是 iPhoneOS 与 iPhoneSimulator 的 SDK:
-它在 Xcode 里且不可再分发。所以 mcpp **定位**它,通过
-`xcrun --sdk <名字> --show-sdk-path`,与它一直以来定位 macOS SDK 的方式完全相同。
+**编译器是我们的；只有 SDK 是 Apple 的。** 任何足够新的 clang 都能为一个
+iOS 部署目标产出 arm64 Mach-O，所以这三行钉的是 `llvm@22.1.8`——那个普通
+载荷，和 `aarch64-macos` 用的是同一个。无法打包的是 iPhoneOS 与
+iPhoneSimulator 的 SDK：它在 Xcode 里，而且不可再分发。所以 mcpp **定位**
+它，通过 `xcrun --sdk <name> --show-sdk-path`，与它一直以来定位 macOS SDK
+的方式完全相同。
 
-这也是这三行不带 `sysroot` 条目的原因。那一列命名的是一个包,而一个被定位的目录
-不是包。
+这也是这三行不带 `sysroot` 条目的原因。那一列命名的是一个包，而一个被定位的
+目录不是包。
 
 ```bash
-mcpp build --target aarch64-ios        # 解析 llvm@22.1.8 + iPhoneOS SDK
-mcpp build --target aarch64-ios-sim    # 解析 llvm@22.1.8 + 模拟器 SDK
+mcpp build --target aarch64-ios        # resolves llvm@22.1.8 + the iPhoneOS SDK
+mcpp build --target aarch64-ios-sim    # resolves llvm@22.1.8 + the Simulator SDK
 ```
 
-## mcpp 保留的宿主面,以及每一项的理由
+## mcpp 保留的宿主面，以及每一项的理由
 
-这个引擎围绕的规矩:**一次构建可复现,当且仅当造它的工具来自下一台机器也能拿到的
-地方。** 所以每一个参与构建的工具都来自依赖图或 xlings,而下面这张表是**不来自**
-那里的全部——每一条都带着它为什么不能。
+这个引擎围绕的那条规矩是：**一次构建可复现，当且仅当造出它的工具来自下一台
+机器也能取得的地方。** 因此每一个参与构建的工具都来自依赖图或 xlings，而
+下表是**不**来自那里的全部——每一条都带着它不属于生态的理由。
 
 | 项 | 到达方式 | 不在生态里的理由 |
 |---|---|---|
-| **xlings 自己** | 随 mcpp 的载荷捆绑(`[xlings] binary = "bundled"`,默认)。`"system"` 才去查 PATH。 | 自举:总得有东西去取第一个包。默认是捆绑的那份,所以走宿主是用户做的一个选择,不是一次兜底。 |
-| **Apple SDK** | 经 `xcrun` **定位**,从不安装 | 不可再分发。没有东西可打包,而拒绝在解析任何载荷之前就点名它。 |
-| **iOS 模拟器运行时** | `simctl`,经 `xim:apple-simulator-tools` | 同上。 |
-| **汇编器(`nasm`)** | 先取钉住的 `xim:nasm`;只有那条路服务不了时才取宿主的,**且被用到时在构建报告里点名** | 一台离线而本来就装了可用汇编器的机器仍然能构建。它此前是反着的——见下。 |
-| **PATH 上的 C++ 编译器(`$CXX`,否则 `g++`)** | 只有 `mcpp doctor` | 那个命令的职责就是报告宿主。构建那条路在每一个到得了这个探针的分支上都从解析出的载荷设定编译器,载荷解析不了时**拒绝**,而不是落到 PATH。 |
-| **命令解释器(`/bin/sh`,Windows 上 `cmd.exe`)** | `[hooks]` 走 `run_shell_deadline`,xlings CLI 走 `run_streaming_bounded`,另有分离式 codegen 命令 | 一条 hook 是**用户自己**用 shell 语法写下的那一行。自带一个 shell 会改变那一行被解读所用的语言,所以这里依赖的不是一个它能打包的工具,而是宿主对那一行含义的约定。 |
-| **MSVC 工具集与 Windows SDK** | 用户点名 `msvc@system`;或一个受管工具集旁边没有 SDK 载荷 | 不可再分发,与 Apple SDK 同类。受管工具集**绑定**自己的 SDK,即使 `WindowsSdkDir` 被设置也不理会——一个环境能覆盖的钉不是钉;回落到机器自己那份能用、不可复现,因此带一句说明(`SdkChoice::note`,调用方必须把它呈现出来)。 |
-
-这张表意在穷举,而它是**推导出来的**,不是回忆出来的。四次扫描就能重新得到它。每一处
-`fs::which` 调用——**恰好五处**,每一处都对应上面的一行:`toolchain/probe` 取 `$CXX`、
-`config` 与 `fallback/xlings_binary` 两处取 xlings、`xlings/xlings` 取汇编器。每一个以
-`/usr`、`/bin`、`/opt`、`/etc` 为根的字符串字面量。每一处 `cmd.exe` 与 `COMSPEC`。
-以及每一个读取宿主工具链所设变量的 `getenv`——`CXX`、`SDKROOT`、`WindowsSdkDir`、
-`WindowsSdkVersion`、`VSINSTALLDIR`、`MACOSX_DEPLOYMENT_TARGET`(其余 `getenv` 读的是
-mcpp 自己的 `MCPP_*` 旋钮与 `HOME`,不指向任何宿主工具)。
-这张表的第一版只做了第一次扫描,因此缺了最后两行;把扫描方式写在这里,是为了让下一个
-读者去**核**这张表而不是**信**它。
-
-其中两条扫描结果值得点名,因为它们指向相反的方向。`mcpp.toolchain.registry` **拒绝**
-一个 `frontend` 写着 `/usr/bin/g++` 或用 `../` 爬出去的载荷描述符——并且是按**字符串**
-校验而不是经 `std::filesystem::path`,因为 `path("/usr/bin/g++").is_absolute()` 在
-Windows 上为假,那道闸恰恰在那台宿主上没有看(2026-09-11 实测)。而 `src/runtime/elf`
-里写下 `/usr/lib` 与 `/usr/lib64`,只是为了**建模**运行期加载器将要搜索的地方,mcpp
-不从那里读任何东西。
-
-其余全部来自图或 xlings,包括最常被当成宿主的那几个:编译器与链接器(载荷)、
-C 库与 C++ 运行时(包)、`ninja` 与 `patchelf`(xlings),以及 `ar` / `strip` /
-`objcopy`(由解析出的工具链自己的目录派生,**从不是一个裸名**——
-`mcpp.toolchain.registry::binutils_tool` 要么返回一个存在的绝对路径,要么什么都不返回)。
-
-**汇编器是唯一指错方向的那一个,值得记下来而不是悄悄掉个头(2026.9.20.1)。**
-`find_usable_nasm` 先问 PATH 再看沙箱。装了汇编器的机器用它的那一份,没装的机器下载
-钉住的那一份。三台机器可以从同一棵源码树产出三份不同的目标文件,而两次构建里都没有
-一行说它用的是哪一个。现在顺序反过来了;当服务的是宿主那一份时,构建会说出来:
+| **xlings 自己** | 随 mcpp 自己的载荷捆绑（`[xlings] binary = "bundled"`，默认值）。`"system"` 才会去查 PATH。 | 自举：总得有东西去取第一个包。默认是捆绑的那份，所以走宿主是用户主动做出的一个选择，不是一次兜底。 |
+| **一个 Apple SDK** | 经 `xcrun` 定位，从不安装 | 不可再分发。没有东西可以打包，而拒绝会在解析任何载荷之前就点名它。 |
+| **iOS 模拟器运行时** | `simctl`，经由 `xim:apple-simulator-tools` | 同上。 |
+| **一个汇编器（`nasm`）** | 先取被钉住的 `xim:nasm`；只有那条路服务不了时才取宿主的，且**在构建报告里点名**用到的是哪一个 | 一台离线、但本来就装了可用汇编器的机器仍然能构建。它此前是反过来的——见下文。 |
+| **PATH 上的 C++ 编译器（`$CXX`，否则 `g++`）** | 只有 `mcpp doctor` | 那个命令的职责就是报告宿主的状况。构建这条路上，在每一个到得了这个探针的分支上都从解析出的载荷设定编译器，载荷解析不了时**拒绝**，而不是落到 PATH。 |
+| **一个命令解释器（`/bin/sh`，Windows 上是 `cmd.exe`）** | `[hooks]` 走 `run_shell_deadline`，xlings CLI 走 `run_streaming_bounded`，还有一个分离式的代码生成命令 | 一条 hook 是**用户自己**用 shell 语法写下的那一行。自带一个 shell 会改变那一行被解读所用的语言，所以这里依赖的不是一个能打包的工具，而是宿主对那一行含义的约定。 |
+| **MSVC 工具集与 Windows SDK** | 用户点名的 `msvc@system`；或者一个受管工具集旁边没有 SDK 载荷时 | 不可再分发，与 Apple SDK 同一类。受管工具集**绑定**自己的 SDK，即使 `WindowsSdkDir` 被设置也不理会——一个环境能覆盖的 pin 就不是 pin；回落到机器自己那份能用，但不可复现，因此会带一句说明（`SdkChoice::note`，调用方必须把它呈现出来）。 |
+
+这张表意在穷举，而它是**推导出来的**，不是靠记忆写出来的。四次扫描 `src/`
+与 `modules/` 就能重新得到它。每一处 `fs::which` 调用——恰好五处，每一处都
+对应上面的一行：`toolchain/probe` 取 `$CXX`，`config` 与
+`fallback/xlings_binary` 里的两处取 xlings，`xlings/xlings` 取汇编器。每一个
+以 `/usr`、`/bin`、`/opt`、`/etc` 为根的字符串字面量。每一处 `cmd.exe` 与
+`COMSPEC` 的使用。以及每一个读取宿主工具链所设变量的
+`getenv`——`CXX`、`SDKROOT`、`WindowsSdkDir`、`WindowsSdkVersion`、
+`VSINSTALLDIR`、`MACOSX_DEPLOYMENT_TARGET`（其余 `getenv` 读的是 mcpp 自己
+的 `MCPP_*` 旋钮与 `HOME`，不指向任何宿主工具）。这张表的第一版只做了第一次
+扫描，因此缺了最后两行；把扫描方式写在这里，是为了让下一个读者去核这张表，
+而不是去信它。
+
+其中两条扫描结果值得点名，因为它们指向相反的方向。`mcpp.toolchain.registry`
+会**拒绝**一个 `frontend` 写着 `/usr/bin/g++` 或者用 `../` 爬出去的载荷
+描述符——而且是按**字符串**校验，不经 `std::filesystem::path`，因为
+`path("/usr/bin/g++").is_absolute()` 在 Windows 上为假，那道闸恰恰在那台
+宿主上没有看到问题（2026-09-11 实测）。而 `src/runtime/elf` 里写下
+`/usr/lib` 与 `/usr/lib64`，只是为了**建模**运行期加载器将要搜索的地方，
+mcpp 不从那里读任何东西。
+
+其余的一切都来自依赖图或 xlings，包括最常被误认为是宿主的那几个：编译器与
+链接器（一个载荷）、C 库与 C++ 运行时（几个包）、`ninja` 与
+`patchelf`(xlings)，以及 `ar` / `strip` / `objcopy`（从解析出的工具链自己的
+目录派生，**从来不是一个裸名**——`mcpp.toolchain.registry::binutils_tool`
+要么返回一个存在的绝对路径，要么什么都不返回）。
+
+**汇编器是唯一指错了方向的一个，值得记录下来，而不是悄悄掉个头
+(2026.9.20.1)。** `find_usable_nasm` 此前先问 PATH，再看沙箱。装了汇编器的
+机器用它自己的那一份，没装的机器则下载被钉住的那一份。三台机器可能从同一棵
+源码树产出三份不同的目标文件，而两次构建都没有一行说出它用的是哪一个
+汇编器。现在这个顺序反过来了；当服务这次构建的是宿主那一份时，构建会说出来：
 
 ```
 warning: the assembler for this build is the host's ('/usr/bin/nasm'), not the one this engine pins
@@ -633,21 +664,22 @@ warning: the assembler for this build is the host's ('/usr/bin/nasm'), not the o
   hint: run `xlings install nasm` so the pinned copy is used
 ```
 
-**一个宿主工具到达构建,本身不是缺陷;一个宿主工具**静默地**到达构建才是。**
-这就是上面是一张表而不是一条禁令的原因:每一条都到得了,每一条都有理由,而每一条都
-在它被用到的地方说出来。
+**一个宿主工具到达构建，本身不是缺陷；一个宿主工具静默地到达构建才是。** 这
+正是上面是一张表而不是一条禁令的原因：每一条都到得了，每一条都有自己的理由，
+而且每一条都会在被用到的地方说出来。
 
-### 这条路新增的宿主面,具名且有界
+### 这条路新增的宿主面，具名且有界
 
-两项,都只在 macOS 上,都落在「一个只存在于它自己那个操作系统上的专有运行时」这一类:
+两项，都只在 macOS 上，都落在「一个只存在于它自己那个操作系统上的专有运行时」
+这一类里：
 
 | 项 | 经由 | 被允许的依据 |
 |---|---|---|
-| iPhoneOS / iPhoneSimulator SDK | `xcrun` | 不可再分发;没有东西可打包 |
-| 模拟器运行时 | `simctl`,经由 `xim:apple-simulator-tools` | 同上 |
+| iPhoneOS / iPhoneSimulator SDK | `xcrun` | 不可再分发；没有东西可以打包 |
+| 模拟器运行时 | `simctl`，经由 `xim:apple-simulator-tools` | 同上 |
 
-其余一切都来自生态:编译器、C++ 运行时、链接器与打包。两项都不是回落到的 ——
-每一项都是被有意请求的,而它的缺失是一次点名它的拒绝:
+其余一切都来自生态：编译器、C++ 运行时、链接器与打包。这两项都不是通过一次
+兜底到达的——每一项都是被有意请求的，而它的缺失会是一次点名它的拒绝：
 
 ```
 error: target aarch64-ios needs the iphoneos SDK, which this machine does not provide.
@@ -658,71 +690,78 @@ error: target aarch64-ios needs the iphoneos SDK, which this machine does not pr
        missing: these rows pin `xim:llvm`, which every other Apple row also uses.
 ```
 
-这次拒绝发生在**任何载荷被解析之前**。一个 Apple SDK 不是依赖能供给的东西,所以
-没有任何后续步骤能学到会改变这个答案的信息 —— 而一台没有 Xcode 的机器不应该先下载
-一个编译器,然后才被告知缺的不是编译器。
+这次拒绝发生在**任何载荷被解析之前**。一个 Apple SDK 不是依赖能供给的东西，
+所以没有任何后续步骤能学到会改变这个答案的信息——而一台没有 Xcode 的机器，
+不应该先下载一个编译器，然后才被告知缺的不是编译器。
 
 ### 这些行上的 C++ 运行时与编译器运行时是包
 
-载荷的静态 libc++ 是 macOS 的目标文件,ld64 拒绝把它链进 iOS 的链接;载荷的资源目录里只有
-`libclang_rt.osx.a`,没有 `ios` 或 `iossim` 的归档。因此这两层都来自依赖图,与裸机行上的
-C 库和 builtins 同一做法:
+这份载荷的静态 libc++ 是一个 macOS 目标文件，ld64 拒绝把它链进一次 iOS
+链接；载荷的资源目录里只有 `libclang_rt.osx.a`，没有 `ios` 或 `iossim` 的
+归档。因此这两层都来自依赖图，与裸机行上的 C 库和 builtins 是同一做法：
 
 ```toml
 [target.'cfg(os = "ios")'.dependencies]
-llvm.libcxx               = "22.1.8.2"   # libc++ 与 libc++abi 的源码,带 std 模块
-llvm.compiler-rt-builtins = "22.1.8.5"   # __isPlatformVersionAtLeast 与通用例程
+llvm.libcxx               = "22.1.8.2"   # libc++ and libc++abi as source, with the std module
+llvm.compiler-rt-builtins = "22.1.8.5"   # __isPlatformVersionAtLeast and the generic routines
 ```
 
-框架声明一次,每个应用通过依赖边继承。报告把两层都记为图里的,链接行带 `-nostdlib++`,
-产物的加载命令不含 `libc++.1.dylib`:翻译单元编译所用的头、导入的模块与链接的目标文件按构造
-是同一个发布版本。
+一个 framework 声明这两行一次，每个应用都继承它们。报告把两层都记为图里的，
+链接行带 `-nostdlib++`，产物的加载命令里不含 `libc++.1.dylib`：一个翻译单元
+编译所依据的头文件、它导入的模块，与最终链接的目标文件，按构造是同一个发布
+版本。
 
-不声明第一行时,运行时是 SDK 的 libc++。不导入 `std` 的程序随之取 SDK 的头文件
-(`-nostdinc++ -isystem <sdk>/usr/include/c++/v1`)并链接 `-lc++`。导入 `std` 的程序仍用载荷的
-模块与头文件配 SDK 的 dylib,与此版本之前每一次 iOS 构建相同;二者是 libc++ 的两个发布版本,
-prepare 报告一次这对搭配并点名上面两行,因为它只在较新头文件里的内联路径没有引用旧 dylib 缺失的
-导出时才能链接。不声明第二行时,prepare 报告一次「载荷没有这个平台的编译器运行时」;从不触及
-可用性检查的程序照常链接。
+不声明第一行时，运行时就是 SDK 的 libc++。不导入 `std` 的程序因此也会取
+SDK 的头文件（`-nostdinc++ -isystem <sdk>/usr/include/c++/v1`）并链接
+`-lc++`。导入 `std` 的程序仍然用载荷的模块与头文件，配 SDK 的 dylib，和此
+版本之前每一次 iOS 构建的做法相同；这是 libc++ 的两个不同发布版本，prepare
+会报告一次这个搭配并点名上面两行，因为它只能在较新头文件里的内联路径没有
+引用旧 dylib 缺失的导出时才能链接成功。不声明第二行时，prepare 会报告一次
+「载荷没有这个平台的编译器运行时」；从未触及可用性检查的程序仍照常链接。
 
 ### 部署目标
 
-`[build] ios_deployment_target` 与 `macos_deployment_target` 并列,而两者是两个键
-只有一个理由:`"14.0"` 是一个 macOS 版本号,对一个 iOS SDK 毫无意义。任何一个目标
-上两者只有一个能成立,所以它们共用构建指纹里的同一个槽。
+`[build] ios_deployment_target` 与 `macos_deployment_target` 并列，而两者
+分成两个键只有一个理由：`"14.0"` 是一个 macOS 版本号，对一个 iOS SDK 毫无
+意义。任何一个给定的 target 上，两者只有一个能成立，所以它们共用构建指纹里
+的同一个槽位。
 
 ```toml
 [build]
 ios_deployment_target = "18.0"
 ```
 
-它由**有效三元组**承载,别处都不承载:
+它由**有效三元组**承载，别处都不承载：
 
 ```
 Target aarch64-ios     → arm64-apple-ios18.0
 Target aarch64-ios-sim → arm64-apple-ios18.0-simulator
 ```
 
-这是 Apple 自己的拼法。不发 `-miphoneos-version-min` 标志:三元组已经完全决定了
-平台与最低版本,而一个标志会成为第二个回答三元组已经回答过的问题的地方。不写这个键
-是合法的,含义是定位到的 SDK 自己的版本:mcpp 用 `xcrun --sdk <name> --show-sdk-version`
-读出它并写进同一个槽。clang 对不带版本的 iOS 三元组给的默认比机器上任何 SDK 都旧
-(它拒绝了 libc++abi 用到的线程局部存储;在 Xcode 16.4 上实测),所以三元组在驱动看到
-之前就带上了版本。Android 的差别在另一个方向:bionic 会直接拒绝一个不带版本的三元组。
+这是 Apple 自己的拼法。不会发出 `-miphoneos-version-min` 标志：三元组已经
+完全决定了平台与最低版本，一个标志只会成为第二个回答三元组已经回答过的问题
+的地方。不写这个键是合法的，含义是取定位到的 SDK 自身的版本：mcpp 用
+`xcrun --sdk <name> --show-sdk-version` 读出它，并写进同一个槽位。clang 对
+一个不带版本的 iOS 三元组给出的默认值，比机器上任何 SDK 都旧（它拒绝了
+libc++abi 用到的线程局部存储；在 Xcode 16.4 上实测过），所以三元组在驱动
+看到它之前就已经带上了版本。Android 的差别在另一个方向：bionic 会直接拒绝
+一个不带版本的三元组。
 
 ### 模拟器的形状与它的边界
 
-模拟器是两行,而不是设备行上的一个标志。一次模拟器构建有它自己的 SDK,产出的对象
-命名它自己的平台(`LC_BUILD_VERSION` 报告 `IOSSIMULATOR` 而不是 `IOS`),并取一个
-不同的部署目标段。两个架构都存在,因为模拟器跑的是**宿主**的架构:一台 Apple 芯片
-的机器需要 `aarch64-ios-sim`,一台 Intel 的需要 `x86_64-ios-sim`。
+模拟器是两行，而不是设备行上的一个标志。一次模拟器构建有它自己的 SDK，产出
+的对象命名它自己的平台（`LC_BUILD_VERSION` 报告 `IOSSIMULATOR` 而不是
+`IOS`），并取一个不同的部署目标段。两个架构都存在，是因为模拟器跑的是
+**宿主**的架构：一台 Apple 芯片的机器需要 `aarch64-ios-sim`，一台 Intel 的
+需要 `x86_64-ios-sim`。
 
-设备行的 `runner` 保持未设。没有开发者自己拥有的签名,一个产物无法在一台 iOS 设备
-上被运行,而那不是一个构建工具能供给的东西。
+设备行的 `runner` 保持未设置。没有开发者自己拥有的签名，一个产物无法在一台
+iOS 设备上运行，而那不是一个构建工具能供给的东西。
 
 ## 项目级版本锁定
 
-若项目需固定特定版本而不依赖全局默认,可在项目的 `mcpp.toml` 中声明:
+若工程需要锁定某个特定版本，而不依赖全局默认值，可在工程自己的 `mcpp.toml`
+中声明：
 
 ```toml
 [toolchain]
@@ -731,24 +770,24 @@ linux   = "gcc@16.1.0"
 macos   = "llvm@20.1.7"
 ```
 
-项目级声明优先于全局默认配置。
+工程级声明优先于全局默认配置。
 
 ## Target 与交叉构建
 
 ```bash
-mcpp build --target x86_64-linux-musl        # 全静态 ELF
-mcpp build --target aarch64-linux-musl       # 跨 arch(x86_64 上出 aarch64)
-mcpp build --target x86_64-windows-gnu       # Linux 上出 Windows PE
+mcpp build --target x86_64-linux-musl        # fully static ELF
+mcpp build --target aarch64-linux-musl       # cross-arch (aarch64 on x86_64)
+mcpp build --target x86_64-windows-gnu       # Windows PE from Linux
 ```
 
-`--target` 会对已知 target 词汇表做校验(README 平台表与之同源):打错
-字是**硬错误并附建议**(`did you mean 'x86_64-linux-musl'?`)——绝不会
-静默退回宿主构建。词汇表之外的自定义 triple,在 `mcpp.toml` 中显式声明
-`[target.<triple>]` 节即可放行(逃生舱)。
+`--target` 会对照已知的 target 词汇表做校验（README 的平台表与之同源）：
+拼错是**硬错误并附带建议**(`did you mean 'x86_64-linux-musl'?`)——绝不会
+静默退回到宿主构建。词汇表之外的自定义三元组，在 `mcpp.toml` 中显式声明
+`[target.<triple>]` 段即可放行。
 
-每个已知 target 自带约定:pin 的工具链(按需自动安装)与默认 linkage
-(`*-linux-musl` 与 `x86_64-windows-gnu` 默认 static)。显式的
-`[target.<triple>]` 节可同时覆盖两者:
+每个已知 target 自带一个约定：被钉住的工具链（按需自动安装）与默认
+linkage（`*-linux-musl` 与 `x86_64-windows-gnu` 默认静态）。一个显式的
+`[target.<triple>]` 段可以同时覆盖两者：
 
 ```toml
 [target.x86_64-linux-musl]
@@ -756,11 +795,11 @@ toolchain = "gcc@16.1.0"
 linkage   = "static"
 ```
 
-### 约定可以被推翻,能力不行
+### 约定可以被推翻，能力不行
 
-**有宿主**那一行的 pin 回答的是*哪个载荷供给这个目标的 C 库*,所以一个自己供给
-C 库的工程可以写任何编译器 —— 整个 openkal 生态就建立在这道口子上。不能做的是
-写另一个编译器而什么都不供给:
+**有宿主**的那一行，它的 pin 回答的是「哪个载荷供给这个 target 的 C
+库」，所以一个自己供给 C 库的工程可以写任何编译器——整个 openkal 生态就建立
+在这道口子上。它不能做的是写一个不同的编译器、却什么都不供给：
 
 ```
 $ mcpp build --target x86_64-linux-musl        # [toolchain] default = "llvm@…"
@@ -768,36 +807,36 @@ error: target 'x86_64-linux-musl' takes its C library from the 'gcc@16.1.0'
        payload, and 'llvm@22.1.8' has none here.
 ```
 
-有两类行回答的是另一个问题,它们的 pin 根本不可被推翻:
+有两类行回答的是另一个问题，它们的 pin 根本不可能被推翻：
 
 | 行 | 原因 |
 |---|---|
-| 所有 `*-none-elf` | 不存在按宿主分的交叉载荷;clang 与 lld 按构造就是交叉编译器,gcc 不是 |
-| `x86_64-windows-musl` | 没有任何 gcc 载荷发得出 PE + musl —— mingw 载荷发的是 PE + MinGW CRT,那是隔壁 `-gnu` 那一行 |
+| 所有 `*-none-elf` | 不存在按宿主分的交叉载荷；clang 与 lld 按构造就是交叉编译器，gcc 不是 |
+| `x86_64-windows-musl` | 没有任何 gcc 载荷能发出 PE + musl C 库的组合——mingw 载荷发出的是 PE + MinGW CRT，那是隔壁 `-gnu` 那一行 |
 
 ```
 $ mcpp build --target riscv64-none-elf         # [toolchain] default = "gcc@…"
 error: target 'riscv64-none-elf' cannot be emitted by 'gcc@16.1.0'.
 ```
 
-**两处拒绝都发生在做出决定的地方**,而不是留给编译器。2026.8.26.1 之前,前者
-会跑完整个构建然后死在链接上,报 `crtbeginT.o (bare name)`;后者给出
-`g++: error: unrecognized argument in option '-mabi=lp64d'` —— 一条关于选项的
-消息,而决定在一百行之前。
+**两处拒绝都发生在做出决定的地方**，而不是留给编译器。在 2026.8.26.1
+之前，前者会跑完整个构建，然后死在链接上，报 `crtbeginT.o (bare name)`；
+后者则给出 `g++: error: unrecognized argument in option '-mabi=lp64d'`——
+一条关于选项的消息，而决定在一百行之前就已经做出。
 
-要给这些结果分类的程序读 `mcpp why toolchain --format json` 的 `data.reason`
-(`convention-unreplaced` / `capability-pin`),而不是那句话 ——
-见[第 11 章](50-machine-output.md)。
+给这些结果分类的程序，读的是 `mcpp why toolchain --format json` 里的
+`data.reason`(`convention-unreplaced` / `capability-pin`)，而不是那句话
+本身——见[第 50 章](50-machine-output.md)。
 
-项目还可以声明自己的*默认*构建 target——"本项目发布全静态"这类语义
-就该放在这里(全静态是产物属性,不是编译器家族属性):
+一个工程还可以声明自己的*默认* build target——「本工程发布全静态产物」这
+类语义就该放在这里（全静态是产物的属性，不是编译器族的属性）：
 
 ```toml
 [build]
-target = "x86_64-linux-musl"                 # ≙ cargo 的 build.target
+target = "x86_64-linux-musl"                 # ≙ cargo's build.target
 ```
 
-配合 `mcpp pack --mode static` 即可产出全静态发布包,完整示例参见
+配合 `mcpp pack --mode static`，即可产出一个全静态的发布包；完整示例参见
 [`examples/03-pack-static`](../../examples/03-pack-static/)。
 
 ## 卸载
@@ -809,67 +848,68 @@ mcpp toolchain remove gcc@16.1.0
 ## 重置沙盒
 
 ```bash
-rm -rf ~/.mcpp                              # 删除整个沙盒
-mcpp build                                  # 后续构建将再次触发首次安装
+rm -rf ~/.mcpp                              # remove the entire sandbox
+mcpp build                                  # the next build triggers first-run installation again
 ```
 
 ## 环境变量
 
-mcpp 的运行行为可通过以下环境变量调整:
+mcpp 的运行行为可以通过下列环境变量调整：
 
 | 变量 | 用途 |
 |---|---|
-| `MCPP_HOME` | 覆盖沙盒位置(默认 `~/.mcpp/`),绝对路径优先级最高 |
-| `MCPP_NO_AUTO_INSTALL=1` | 禁用工具链自动安装,适用于 CI 与离线环境 |
-| `MCPP_OFFLINE=1` | 完全不访问网络,等价于全局 `--offline` |
+| `MCPP_HOME` | 覆盖沙盒位置（默认 `~/.mcpp/`）；绝对路径优先级最高 |
+| `MCPP_NO_AUTO_INSTALL=1` | 禁用工具链自动安装，适用于 CI 与离线环境 |
+| `MCPP_OFFLINE=1` | 完全不访问网络，等价于全局 `--offline` |
 | `MCPP_NO_COLOR=1` / `NO_COLOR=1` | 禁用彩色输出 |
 | `MCPP_LOG_LEVEL=debug\|info\|warn\|error\|off` | 日志级别 |
 
-未显式设置 `MCPP_HOME` 时,mcpp 将基于二进制所在目录的上一级路径
-自动定位沙盒位置(release tarball 解压至 `~/.mcpp/` 后,`~/.mcpp/`
-即为 home),因此 release 版本无需任何环境变量配置即可运行。
-
+未显式设置 `MCPP_HOME` 时，mcpp 会基于二进制所在目录的上一级路径自动定位
+沙盒（一份 release tarball 解压到 `~/.mcpp/` 之后，`~/.mcpp/` 就是 home），
+所以 release 版本不需要任何环境变量配置即可运行。
 
 ## ABI 能力强制
 
-依赖可声明 `abi:<name>` 能力(如 `compat.glfw` 声明 `abi:glibc`)。解析出的
-工具链 ABI 不满足任一依赖的 abi 要求时,构建会**尽早失败**并给出修复建议
-(例如 musl-static 工具链遇到 abi:glibc 依赖),取代深层的链接/头文件报错。
-查看:`mcpp why toolchain`。
+一个依赖可以声明 `abi:<name>` 能力（例如 `compat.glfw` 声明
+`abi:glibc`）。当解析出的工具链的 ABI 不满足某个依赖的 abi 要求时，构建会
+**尽早失败**并给出修复建议（例如一个 musl-static 工具链遇到一个
+abi：glibc 依赖），取代更深层的链接或头文件报错。查看方式：
+`mcpp why toolchain`。
 
-## 已知工具链风险:模块接口中的运算符模板(Clang 20+)
+## 已知工具链风险：模块接口中的运算符模板（Clang 20+）
 
-一个导出**替换性运算符模板**的模块,在 Clang 20 或 22 下会毒化所有导入者
-中该运算符的名字查找:任何 `import` 了这个模块、并用到该运算符的 TU
-——**无论作用在什么类型上**——都会让前端崩溃(SIGSEGV)。GCC 16 与
-Clang 18 不受影响,所以这是 Clang 18 到 20 之间的一处回归。
+一个导出**替换性运算符模板**的模块，在 Clang 20 或 22 下会毒化所有导入者
+中该运算符的名字查找：任何 `import` 了这个模块、并用到该运算符的翻译
+单元——**无论作用在什么类型上**——都会让前端崩溃（SIGSEGV）。GCC 16 与
+Clang 18 不受影响，所以这是 Clang 18 到 20 之间的一处回归。
 
 它正好打在 module-package 这个模式上。包装一个运算符是 `static inline`
-模板的上游头文件,再用一个恒真约束镜像它们的签名(跨 TU 包含关系的标准配方),
-恰恰就是踩中它的写法。
+模板的上游头文件，再用一个恒真约束镜像它们的签名（这是跨翻译单元包含关系的
+标准配方），恰恰就是踩中它的写法。
 
-**经验判据:**每个模板形参都应由**第一个**函数实参定死。破坏这一点的形状就是有毒的:
+**经验判据：** 每个模板形参都应由**第一个**函数实参定死。破坏这一点的形状
+就是有毒的：
 
 ```cpp
-// 有毒 —— `n` 与 `l` 不由第 1 个实参决定
+// Poisonous — `n` and `l` are not determined by argument 1
 template<typename T, int m, int n, int l>
 Matx<T, m, n> operator*(const Matx<T, m, l>& a, const Matx<T, l, n>& b);
 
-// 有毒 —— 第二个 typename 只出现在第 2 个实参里
+// Poisonous — second typename appears only in argument 2
 template<typename T1, typename T2, int n>
 Vec<T1, n>& operator+=(Vec<T1, n>& a, const Vec<T2, n>& b);
 
-// 没问题 —— 每个形参都由第 1 个实参定死
+// Fine — every parameter is pinned by argument 1
 template<typename T, int m, int n>
 Matx<T, m, n> operator+(const Matx<T, m, n>& a, const Matx<T, m, n>& b);
 ```
 
-崩溃是**按名字**触发的:一处被毒化的 `operator*` 声明,会让每个导入者里的
-每一个 `x * y` 都崩,哪怕类型完全无关。函数体本身无关紧要。
+崩溃是**按名字**触发的：一处被毒化的 `operator*` 声明，会让每个导入者里
+每一个 `x * y` 都崩溃，即使类型完全无关。函数体本身无关紧要。
 
-**绕法**是整体推导操作数类型再加约束,而不是在形参列表里把它们拆开。
-这样保持调用兼容,跨 TU 语义也仍然成立 —— 上游那个精确匹配的
-`static inline` 更特化,在那边照样胜出:
+**绕过方法**是整体推导操作数类型再加约束，而不是在形参列表里把它们拆开。
+这样保持调用兼容，跨翻译单元的语义也仍然成立——上游那个精确匹配的
+`static inline` 更特化，在那边照样胜出：
 
 ```cpp
 template<typename MA, typename MB>
@@ -882,13 +922,13 @@ inline MA& operator+=(MA& a, const MB& b);
 
 跟踪于 [mcpp#256](https://github.com/mcpp-community/mcpp/issues/256)。
 `tests/e2e/150_clang_module_operator_template.sh` 是一只跑在内置 LLVM
-工具链上的金丝雀 —— 未来某次 Clang 升级修好(或再次弄坏)这一点时,
-它会显式暴露出来,而不是悄悄改变包能表达的东西。
+工具链上的金丝雀——未来某次 Clang 升级修好（或者再次弄坏）这一点时，它会
+显式暴露出来，而不是悄悄改变包能表达的东西。
 
-## 已知工具链风险:宽的可平凡比较类型上的 `std::find`(clang + MSVC STL 14.51)
+## 已知工具链风险：宽的可平凡比较类型上的 `std::find`(clang + MSVC STL 14.51)
 
-编译器是 clang、标准库是 MSVC STL 14.51(Visual Studio 18)时,对宽度超过八字节的
-可平凡复制类型调用 `std::find` 的翻译单元,会在标准库内部编译失败:
+编译器是 clang、标准库是 MSVC STL 14.51（Visual Studio 18）时，对宽度超过
+八字节的可平凡复制类型调用 `std::find` 的翻译单元，会在标准库内部编译失败：
 
 ```text
 xutility:320:23: error: static assertion failed: unexpected size
@@ -896,205 +936,227 @@ xutility:6542:49: note: in instantiation of function template specialization
   'std::_Find_vectorized<const T, T>' requested here
 ```
 
-这正是 mcpp 在 Windows 上默认工具链的形态(clang 面向 `x86_64-pc-windows-msvc`),
-所以即使 mcpp 和程序本身都没有错误,失败也会经由 `mcpp build` 出现。MSVC STL 通过一个
-只在 clang 下生效、且没有尺寸上限的 trait 把该类型放进向量化路径,而它分派到的函数只
-实现了 1、2、4、8 字节的元素;MSVC 自己的前端不走这条路径。同一份源码在
-`windows-2022` 所带的 MSVC STL 14.3x 上可以编译。
+这正是 mcpp 在 Windows 上默认工具链的形态（clang 面向
+`x86_64-pc-windows-msvc`），所以即使 mcpp 和程序本身都没有错误，这个失败也
+会经由 `mcpp build` 出现。MSVC STL 通过一个只在 clang 下生效、且没有尺寸
+上限的 trait，把这个类型纳入了向量化路径，而它分派到的函数只实现了 1、2、
+4、8 字节的元素；MSVC 自己的前端从不走这条路径。同一份源码在 `windows-2022`
+所带的 MSVC STL 14.3x 上可以编译。
 
-缺陷在上游,见 [microsoft/STL#6294](https://github.com/microsoft/STL/issues/6294)。
-下游实测过两种绕过方式:
+缺陷在上游，跟踪于
+[microsoft/STL#6294](https://github.com/microsoft/STL/issues/6294)。
+下游实测过两种绕过方式：
 
-- 为元素类型写一个用户定义的 `operator==`,而不是默认的。该类型因此不再可平凡相等比较,
-  STL 走标量路径。
-- 在 MSVC STL 早于 14.51 的镜像上构建,例如 `windows-2022`。
+- 为元素类型写一个用户定义的 `operator==`，而不是让编译器默认生成。该类型
+  因此不再是可平凡相等比较的，STL 就会走标量路径。
+- 在 MSVC STL 早于 14.51 的镜像上构建，例如 `windows-2022`。
 
-见 [mcpp#609](https://github.com/mcpp-community/mcpp/issues/609)。
+跟踪于 [mcpp#609](https://github.com/mcpp-community/mcpp/issues/609)。
 
-## C++ 运行时契约(`cxx_runtime`)
+## C++ 运行时契约（`cxx_runtime`）
 
-`cxx_runtime` 声明的是**产物对运行它的机器做出的承诺**。它是**分发**属性而非
-构建属性 —— 它描述的是运行期依赖集,而兑现它的 flag 逐平台不同。
+`cxx_runtime` 声明的是产物对运行它的那台机器做出的承诺。它是**分发**属性，
+不是构建属性——它描述的是运行期依赖集，而兑现它的旗标逐平台不同。
 
-> **不含 C++ 的目标没有 C++ 运行时契约需要兑现。** mcpp 用 C 驱动链接它,
-> 并且完全不发 C++ 运行时相关的 flag,因此一个纯 C 的共享库不会平白拿到
-> `libstdc++` / `libc++` 依赖。目标里只要有一个 C++ 翻译单元,整个目标就回到
-> C++ 驱动。这一判定由源码推导,没有对应的配置键。
+> **不含 C++ 的 target 没有 C++ 运行时契约需要兑现。** mcpp 用 C 驱动链接
+> 这样的 target，并完全不发出 C++ 运行时相关的旗标，因此一个纯 C 的共享库
+> 不会平白拿到它用不上的 `libstdc++`/`libc++` 依赖。这个 target 里只要有
+> 一个 C++ 翻译单元，整个 target 就回到 C++ 驱动。这一判定由源码推导得出，
+> 没有对应的配置键。
 
 ```toml
 [build]
-cxx_runtime = "self-contained"          # 作用于所有目标(默认值)
+cxx_runtime = "self-contained"          # applies to every target (the default)
 
-# 或者按角色分别指定:
+# or, per role:
 [build.cxx_runtime]
-default = "self-contained"              # 可执行文件
-tests   = "host-coupled"                # 测试二进制从不离开本机
-shared  = "self-contained"              # 共享库(见下 —— 默认值随目标格式而变)
+default = "self-contained"              # executables
+tests   = "host-coupled"                # test binaries never leave this machine
+shared  = "self-contained"              # shared libraries (see below — the
+                                        # default differs by target format)
 
-# 或者按目标三元组 —— 与 `linkage` 并列,因为它们是同一根轴:
+# or, per target triple — beside `linkage`, which is the same axis:
 [target.x86_64-linux-gnu]
-cxx_runtime = "host-coupled"            # 例如这次构建是为发行版打包
+cxx_runtime = "host-coupled"            # e.g. this build is for a distro package
 ```
 
-| 取值 | 产物运行时需要 | 典型场景 |
+| 取值 | 产物在运行期的需求 | 典型用途 |
 |---|---|---|
-| `self-contained`(默认) | 自身之外不需要任何 C++ 运行时 | 分发二进制 |
-| `toolchain-coupled` | mcpp 装的那份工具链的 C++ 运行时 | 本地迭代 |
-| `host-coupled` | 驱动默认解析到的那份(通常是系统运行时) | 发行版打包;必须与宿主共用同一份运行时的 `dlopen` 插件 |
-
-**默认即自包含(portable by default)**:macOS 上这会静态链入 LLVM 自带的
-libc++/libc++abi —— 系统 libc++ 会把实际可运行版本固定在构建机的 OS(老系统
-缺新符号,如 `std::print` 的支撑符号),只有静态化才能真正兑现
-`macos_deployment_target` 的 floor。Linux/MinGW 上它是 `-static-libstdc++`
-(GCC)或整条链的 `-static`(MinGW);Linux 上的 clang/libc++ 工具链则显式链入
-libc++.a/libc++abi.a/libunwind.a。更低的 macOS floor(11–13)需自建 libc++
-归档(已验证可行,数据级切换,按需提供)。
-
-**共享库是唯一一个默认值随目标格式变化的角色**,因为危害本身随格式变化。
-`.so`/`.dylib`/`.dll` 不是一个小号可执行文件 —— 它被加载**进**一个已经有
-C++ 运行时的进程。
-
-| 目标格式 | `kind = "shared"` 的默认契约 | 原因 |
+| `self-contained`（默认） | 自身之外不需要任何 C++ 运行时 | 分发一个二进制 |
+| `toolchain-coupled` | mcpp 安装的那套工具链自带的 C++ 运行时 | 本地迭代 |
+| `host-coupled` | 驱动默认解析到的那一份（即系统运行时） | 发行版打包；必须与宿主共用同一份运行时的 `dlopen` 插件 |
+
+**默认即自包含（portable by default）**：在 macOS 上，这会静态链接 LLVM
+自带的 libc++/libc++abi——否则系统的 libc++ 会把可运行版本钉死在构建机的
+操作系统上（老系统缺少更新的符号，例如 `std::print` 背后的支撑符号），而
+只有静态链接才能真正兑现 `macos_deployment_target` 的下限。在
+Linux/MinGW 上，它是 `-static-libstdc++`（GCC）或者整条链接的
+`-static`(MinGW)；在 Linux 的 clang/libc++ 工具链上，它显式链接
+libc++.a/libc++abi.a/libunwind.a。更低的 macOS 下限（11–13）需要一份自建
+的 libc++ 归档（已验证可行，是一次数据级的切换，可按需提供）。
+
+**共享库是唯一一个默认值取决于 target 格式的角色**，因为它面对的危害本身就
+随格式变化。一个 `.so`/`.dylib`/`.dll` 不是一个小号可执行文件——它被加载
+**进**一个已经拥有 C++ 运行时的进程。
+
+| target | `kind = "shared"` 的默认值 | 原因 |
 |---|---|---|
-| ELF(Linux 等) | `toolchain-coupled` | ELF 只有一个全局符号命名空间,先加载的定义胜出。静态内嵌了 libstdc++ 的 `.so` 会把它**导出**,链接该库的可执行文件于是把自己的 `std::` 引用绑到那里 —— 它自己的 `self-contained` 契约静默变成空操作,它的 C++ 运行时变成"碰巧加载的那一份该库"。 |
-| Mach-O | `self-contained` | 那里的机制本来就是 `-load_hidden`(hidden 可见性),dyld 不会归一这些符号;而且 macOS 上根本没有 toolchain-coupled 这一档(见下文注)。 |
-| PE(Windows) | `self-contained` | PE 没有全局符号命名空间 —— 导入按 DLL 逐个按名解析,一个 DLL 的私有运行时不可能被别人捡走。 |
-
-在 ELF 上显式写 `shared = "self-contained"` 是支持的,而且就是字面意思:库会内嵌
-运行时。此时 mcpp 会额外发 `-Wl,--exclude-libs`(针对标准库归档),让内嵌的那份
-留在库的动态符号表之外,链接它的任何东西都捡不走。本工程代码产生的模板实例化
-(`std::string` 之类的 weak/COMDAT 符号)仍然会导出 —— 那是 C++ ABI 的预期行为,
-不是这里要防的泄漏。
-
-工程级的 `cxx_runtime = "…"`(或 `static_stdlib = false`)同样作用于共享库:
-有人写下了整个工程的承诺。只有在**没人写**的时候,随格式变化的默认值才生效。
-
-**加载 C++ 共享库的程序**(mcpp 2026.9.16.1+)。在 ELF 上,上面两个默认值会在同一个
-进程里冲突:self-contained 的程序加载 toolchain-coupled 的 C++ 共享库,进程里就同时
-有一份静态 C++ 运行时和一份共享的。可执行文件导出该库引用的运行时符号,库把其中一部分
-绑到程序的那份、其余留给自己,两半对共享状态的认识互不一致;实测 `llvm@22.1.8` 下这样的
-程序在库第一次格式化字符串时以 `std::bad_cast` 中止,`gcc@16.1.0` 下能跑但有 900 个
-libstdc++ 符号被抢占。因此在 ELF 上,没有人声明契约的程序或测试,若直接或经由另一个
-共享库加载本次构建产出的 C++ 共享库,就取该共享库的契约。进程本来就通过库自己的
-`NEEDED` 条目需要那份运行时,所以没有任何部署因此多出依赖;`resolution.json` 在
-`runtime.cxx_runtime_by_role` 下记录最终的契约。
-
-声明过的契约从不改动。**声明了** `self-contained` 的程序或测试,若加载耦合到共享运行时的
-C++ 共享库,会在编译前被拒绝(reason `program-cxx-runtime-split`,见
-[50](50-machine-output.md));出路是删掉这条声明,或用
-`cxx_runtime = { shared = "self-contained" }` 给共享库一份私有副本,让每份运行时留在
-各自的映像里。
-
-**Mach-O 上每个映像各带一份运行时**(mcpp 2026.9.16.1+)。那里每个角色的默认值都是
-self-contained,每个映像以隐藏可见性内嵌载荷的 `libc++.a`,于是标准库类的类型信息每个
-映像各有一份,而 libc++ 按地址比较它。macos-15 实测:按默认值,dylib 里抛出的
-`std::runtime_error` 在程序中不被 `catch (const std::runtime_error&)` 捕获,两个
-`std::error_code` 的 category 比较不相等;所有角色都写 `cxx_runtime = "host-coupled"`
-时两者都成立。默认值不变——它是今天每个 macOS 构建的形态——但程序加载了本次构建的 C++
-dylib 时会被告知一次(`build/cxx-runtime-identity`):当对象以异常、或以按身份比较的
-libc++ 值跨过边界时,为整个进程声明一份运行时。
-
-**C++ 运行时来自图中的包时,依赖的共享库**(mcpp 2026.9.15.2+)。当图中有包提供
-C++ 层(`llvm.libcxx`,见 [22](22-target-side.md)),它的对象被链进程序,并且以隐藏
-可见性编译,于是一个构建为 C++ 共享库的依赖无法解析到程序里的那份。mcpp 在编译前
-拒绝这样的构建(reason `shared-library-cxx-runtime`,见 [50](50-machine-output.md)),
-并给出两条出路:在依赖的边上写 `linkage = "static"` 静态链接它 —— 仅当依赖自己的
-清单没有把它约束为共享形态时才会给出这一条;或者为共享库声明一份私有副本:
+| ELF（Linux 等） | `toolchain-coupled` | ELF 只有一个全局符号命名空间，先加载的定义胜出。一个静态内嵌了 libstdc++ 的 `.so` 会把它**导出**，链接该库的可执行文件于是把自己的 `std::` 引用绑定到那里——它自己的 `self-contained` 契约会静默变成空操作，它的 C++ 运行时变成碰巧加载到的那一份该库。 |
+| Mach-O | `self-contained` | 那里的机制本来就是 `-load_hidden`，即隐藏可见性，dyld 因此从不归一这些符号；而且 macOS 上根本没有 toolchain-coupled 这一档（见下文注记）。 |
+| PE(Windows) | `self-contained` | PE 没有全局符号命名空间——导入按 DLL 逐个按名解析，一个 DLL 的私有运行时不可能被别的东西捡走。 |
+
+在 ELF 上显式写 `shared = "self-contained"` 是支持的，而且就是字面意思：
+库会内嵌运行时。此时 mcpp 会额外为标准库归档传递
+`-Wl,--exclude-libs`，让内嵌的那份留在库的动态符号表之外，链接它的任何
+东西都捡不走。本工程代码产生的模板实例化（`std::string` 之类的
+weak/COMDAT 符号）仍然会导出——那是 C++ ABI 的预期行为，不是这里要防的
+泄漏。
+
+一个工程级的 `cxx_runtime = "…"`（或 `static_stdlib = false`）同样作用于
+共享库：有人已经说明了整个工程的承诺。只有在没人说明的情况下，随格式变化的
+默认值才会生效。
+
+**加载 C++ 共享库的程序**(mcpp 2026.9.16.1+)。在 ELF 上，上面两个默认值
+会在同一个进程里发生冲突：一个 self-contained 的程序加载
+toolchain-coupled 的 C++ 共享库，进程里因此同时存在一份静态 C++ 运行时和
+一份共享的。可执行文件导出该库引用的运行时符号，库把其中一部分绑定到程序的
+那份、其余留给自己，两半对共享状态的认识因而不一致；实测中，用
+`llvm@22.1.8` 构建的这类程序，会在库第一次格式化字符串时以
+`std::bad_cast` 中止，用 `gcc@16.1.0` 构建则能跑，但有 900 个
+libstdc++ 符号被抢占。因此在 ELF 上，一个没有人为它声明契约的程序或测试，
+如果直接或经由另一个共享库加载了本次构建产出的 C++ 共享库，就会取用该
+共享库的契约。进程本来就通过库自己的 `NEEDED` 条目需要那份运行时，所以
+没有任何部署会因此多出一项要求；`resolution.json` 会在
+`runtime.cxx_runtime_by_role` 下记录最终生效的契约。
+
+已声明的契约从不会被改动。一个**声明了** `self-contained` 的程序或测试，
+若加载了耦合到共享运行时的 C++ 共享库，会在编译前被拒绝（reason
+`program-cxx-runtime-split`，见[50](50-machine-output.md)）；出路是删掉
+这条声明，或者用 `cxx_runtime = { shared = "self-contained" }` 给共享库
+一份私有副本，让每份运行时都留在各自的映像里。
+
+**在 Mach-O 上，每个映像各自携带自己的运行时**(mcpp
+2026.9.16.1+)。那里每个角色的默认值都是 self-contained，每个映像以隐藏
+可见性内嵌载荷的 `libc++.a`，于是标准库类的类型信息在每个映像里各有一份，
+而 libc++ 按地址比较它。在 macos-15 上实测：按默认值，dylib 里抛出的
+`std::runtime_error` 不会被程序里的 `catch (const std::runtime_error&)`
+捕获，两个 `std::error_code` 的 category 比较也不相等；当所有角色都写
+`cxx_runtime = "host-coupled"` 时，两者都成立。默认值不变——它是今天每个
+macOS 构建的形态——但当一次构建的程序加载了本次构建产出的 C++ dylib 时，
+会被告知一次（`build/cxx-runtime-identity`）：当对象以异常的形式、或以
+按身份比较的 libc++ 值的形式跨越这条边界时，应当为整个进程声明同一份
+运行时。
+
+**依赖的共享库之上，C++ 运行时是一个包时**(mcpp
+2026.9.15.2+）。当依赖图中有一个包提供 C++ 层（`llvm.libcxx`，见
+[22](22-target-side.md)）时，它的对象会被链进程序，并且以隐藏可见性编译，
+于是一个构建为 C++ 共享库的依赖无法解析到程序里的那一份。mcpp 会在编译前
+拒绝这样的构建（reason `shared-library-cxx-runtime`，见
+[50](50-machine-output.md)），并给出两条出路：在依赖的边上写
+`linkage = "static"` 把它静态链接——只有当依赖自己的 manifest 没有把它
+约束成共享形态时，才会给出这一条；或者为共享库声明一份私有副本：
 
 ```toml
 [build]
 cxx_runtime = { shared = "self-contained" }
 ```
 
-在这条声明下,每个这样的共享库自己链接运行时包的对象。于是每个镜像各有一份运行时
-类的类型信息:共享库里抛出的标准库类异常,在程序里不会被该类捕获,而共享库自己定义
-的类可以。默认值从不选择私有副本,只有这条声明会。在 Mach-O 上,C++ 运行时来自图中包的
-构建里每个单元都以隐藏可见性编译,使运行时的实例化永远不与系统的 libc++ 合并;因此那里
-的共享库只导出源码中标注了 `[[gnu::visibility("default")]]` 的声明。
+在这条声明下，每个这样的共享库都会自己链接运行时包的对象。于是每个映像各自
+持有运行时类的类型信息：一个标准库类的异常在共享库里抛出时，程序里的该类不
+会捕获它，而共享库自己定义的类则会。默认值从不会选中这份私有副本，只有这条
+声明会。在 Mach-O 上，当图中一份构建的 C++ 运行时是一个包时，每个单元都以
+隐藏可见性编译，使得运行时的实例化永远不会与系统的 libc++ 合并；那里的共享
+库因此只导出源码中标注了 `[[gnu::visibility("default")]]` 的声明，别无
+其他。
 
-`static_stdlib` 是旧拼写,仍然有效:`true` 等价于 `self-contained`,`false`
-等价于 `host-coupled`。显式写了 `cxx_runtime` 时以后者为准。
+`static_stdlib` 是较旧的拼写，仍然有效：`true` 等价于
+`self-contained`，`false` 等价于 `host-coupled`。显式写了 `cxx_runtime`
+时，以它为准。
 
-**兑现不了的契约会被报出来,绝不静默降级。** 若工具链不带 `libc++.a`,或某个
-契约在该平台上没有对应机制,构建会打印实际退到了哪一档,而不是悄悄交付一个与
-manifest 所述不同的产物。
+**兑现不了的契约会被报出来，绝不会被静默降级。** 如果工具链不带
+`libc++.a`，或者某个契约在该平台上没有对应的机制，构建会打印它实际退到了
+哪一档，而不是悄悄交付一个与 manifest 所述不同的产物。
 
 ### 在 MSVC 运行时上
 
-这里的机制就是 CRT 模型,而它是**整个工程级**的开关:cl 会把 `_MSVC_MT` /
-`_MSVC_MD` 烘进工程唯一的那份 `std` 模块,所以与工程不一致的按角色契约无法兑现,
-会被报出来而不是被忽略。
+这里的机制就是 CRT 模型，而它是一个**整个工程**级的开关：cl 会把
+`_MSVC_MT`/`_MSVC_MD` 烘进一个工程唯一构建的那份 `std` 模块，所以一个与
+工程不一致的按角色契约无法被兑现，会被报出来，而不是被忽略。
 
 | 取值 | 在 MSVC 上的含义 |
 |---|---|
-| `self-contained` | `/MT`,静态 CRT。`linkage = "static"` 从 libc 那根轴选中的是同一件事。 |
-| `host-coupled`(`/MD` 下的默认) | 由目标机器提供 `vcruntime140.dll` / `msvcp140.dll` —— 即那台机器装了 Visual Studio 或 redistributable。 |
-| `toolchain-coupled` | toolset **自带**的那份 DLL 跟着产物走。 |
-
-`toolchain-coupled` 值得说清楚,因为直觉上的理解是错的。`ucrtbase.dll` **是**
-Windows 组件(Win10 起),mcpp 从不分发它;而 `vcruntime140.dll` /
-`msvcp140.dll` **不是**:每个 MSVC toolset 都在
-`VC\Redist\MSVC\<version>\<arch>\` 下带着它们,和 gcc payload 带着
-`libstdc++.so` 是同一件事。在这个契约下 mcpp 会把它们放到产物旁边 —— 这正是让
-默认的 `/MD` 产物能在"只装了 pinned toolset、根本没有 Visual Studio"的机器上跑
-起来的原因。
-
-调试版 CRT(`debug_nonredist\` 下的 `vcruntime140d.dll` 等)永远不会被放进去:
-它不可再分发。
-
-> **从 2026.8.15 或更早版本升上来?** 这条键在 MSVC ABI 上曾经是**空操作** ——
-> 它会报 `not implemented for the MSVC runtime yet`,写什么都退回 `/MD`。
-> 自 2026.8.16 起它真的生效,于是一份从那个年代带着
-> `cxx_runtime = "self-contained"` 的 manifest **会在升级时换掉 CRT 模型**:
-> 从 `/MD` 变成 `/MT`。它不是同一个模型的更严格版本,而且因为这个值一直是合法的,
-> 切换是**静默**的。若工程是在这条键尚未生效时写下它的,应重新确认所需的取值。
-
-把它和 `/MT` 一起用是**矛盾**而不是缺功能 —— 静态 CRT 根本没有 DLL 可以耦合 ——
-所以会被报出来并落到 `self-contained`。另一半由 `mcpp pack` 兜底:什么都不打包的
-模式(`--mode system`、`--mode static`)兑现不了 `toolchain-coupled`,会直接拒绝。
-
-**MSVC ABI 上的 clang**(`x86_64-windows-msvc` 的 `llvm` 行,记录自 mcpp 2026.9.16.1
-起)。上表描述的是 `cl.exe`,mcpp 只向它传递 CRT 模型。MSVC ABI 上的 clang 使用 GNU
-方言、收不到任何模型,它的驱动链接静态 CRT(`-defaultlib:libcmt`):这一行构建的程序
-不导入 `vcruntime140.dll`、`msvcp140.dll` 或 `api-ms-win-crt-*`,每个 DLL 各带一份 CRT。
-因此这一行无论 `cxx_runtime` 写什么都是 `self-contained`,`resolution.json` 如实记录,
-显式写 `host-coupled` 或 `toolchain-coupled` 会打印这一行兑现不了它。需要在 MSVC ABI
-上使用动态 CRT 的工程,用 `msvc@system` 构建。
-
-**边界。** 该契约只管 C++ 运行时。静态 **libc** 是另一根轴(`linkage = "static"`
-/ `--static`,如 musl 目标),部署下限是第三根轴 —— Apple 目标用 `[package]` 里的
-`macos_deployment_target`,Android 用 `[target.<triple>]` 下的 `min_api_level`。
-两者喂给 `llvm_triple()` 的同一个参数、占构建指纹里的同一个槽:一个目标要么是
-Apple 要么是 Android,而两者回答的是同一个问题。
-另外,`host-coupled` 只承诺 mcpp 不做任何"把 C++ 运行时打进产物"的动作,它不会
-去掉链接因其它原因已经携带的工具链 rpath —— 所以在 ELF 上这类产物仍可能优先
-找到工具链的库。
-
-> **macOS + `self-contained` 与静态初始化次序。** Mach-O 没有按优先级排序的
-> 初始化段,而 libc++ 的 `<iostream>` 也不像 libstdc++ / MSVC STL 那样自带
-> `ios_base::Init` 守卫 —— 于是从 `libc++.a` 里拉出来的流初始化器本来会排在
-> 程序自己的全局构造函数**之后**:一个在构造函数里碰 `std::cout` 的全局对象会
-> 读到尚未构造的流,进程启动即崩。mcpp 会把一个极小的生成对象排在链接最前面
-> 把流顶上去,调用方代码无需改动。详见 mcpp-community/mcpp#336。
-
-`defines` 接受**裸**宏名(不带 `-D`),把每个条目脱糖为 `-D<x>`,同时作用于 C 和
-C++ 编译通道。它覆盖包内每个 TU(含模块接口单元),因此也会进入**编译器自己的**
-P1689 模块扫描。
-
-> **但它不会让被宏保护的 `import` 变得可用。** mcpp 在编译器看到文件之前先跑
-> 自己的词法预扫描,而那个扫描器对**任何** `#if` / `#ifdef` 块内的 `import`
-> 一律拒绝,不求值条件:
+| `self-contained` | `/MT`——静态 CRT。`linkage = "static"` 从 libc 那根轴选中的是同一件事。 |
+| `host-coupled`（`/MD` 下的默认值） | 由目标机器提供 `vcruntime140.dll` / `msvcp140.dll`——即那台机器装了 Visual Studio 或对应的 redistributable。 |
+| `toolchain-coupled` | toolset **自带**的那份 DLL 跟着产物一起走。 |
+
+`toolchain-coupled` 值得说清楚，因为直觉上的理解是错的。`ucrtbase.dll`
+**是**一个 Windows 组件（Windows 10 起），mcpp 从不分发它；而
+`vcruntime140.dll` 与 `msvcp140.dll` **不是**：每个 MSVC toolset 都在
+`VC\Redist\MSVC\<version>\<arch>\` 下带着它们，和一个 gcc 载荷带着
+`libstdc++.so` 是同一件事。在这份契约下，mcpp 会把它们放到产物旁边——这
+正是让一次默认的 `/MD` 构建，能在一台只装了被钉住的 toolset、完全没有
+Visual Studio 的机器上运行起来的原因。
+
+调试版 CRT（`debug_nonredist\` 下的 `vcruntime140d.dll` 等）永远不会被
+放进去：它不可再分发。
+
+> **从 2026.8.15 或更早版本升级时的变化。** 这个键在 MSVC ABI 上曾经是
+> **空操作**——它会报 `not implemented for the MSVC runtime yet`，写任何
+> 值都会退回 `/MD`。自 2026.8.16 起它真的会生效，于是一份从那个年代带着
+> `cxx_runtime = "self-contained"` 的 manifest，**会在升级时换掉 CRT
+> 模型**：从 `/MD` 变成 `/MT`。它不是同一个模型的更严格版本，而且因为
+> 这个值一直是合法的，这次切换是**静默**的。如果一个工程是在这个键尚未
+> 生效时写下它的，应当重新确认所需的取值。
+
+把它和 `/MT` 一起写是一处**矛盾**，而不是缺功能——一份静态 CRT 根本没有
+DLL 可以耦合——所以它会被报出来，并落回 `self-contained`。另一半由
+`mcpp pack` 兜底：一个什么都不打包的模式（`--mode system`、
+`--mode static`）兑现不了 `toolchain-coupled`，会直接拒绝。
+
+**MSVC ABI 上的 clang**（`x86_64-windows-msvc` 的 `llvm` 行，记录自 mcpp
+2026.9.16.1 起）。上表描述的是 `cl.exe`，mcpp 只向它传递 CRT 模型。MSVC
+ABI 上的 clang 使用 GNU 方言，收不到任何模型，它的驱动链接静态 CRT
+(`-defaultlib:libcmt`)：这一行构建出的程序不会导入
+`vcruntime140.dll`、`msvcp140.dll` 或 `api-ms-win-crt-*`，每个 DLL 各自
+带着自己的 CRT。因此这一行无论 `cxx_runtime` 写什么都是
+`self-contained`，`resolution.json` 如实记录这一点，显式写
+`host-coupled` 或 `toolchain-coupled` 会打印这一行兑现不了它。需要在
+MSVC ABI 上使用动态 CRT 的工程，应当用 `msvc@system` 构建。
+
+**边界。** 该契约只管辖 C++ 运行时。静态 **libc** 是另一根轴
+(`linkage = "static"` / `--static`，例如一个 musl target)，部署下限是
+第三根轴——Apple target 用 `[package]` 里的
+`macos_deployment_target`，Android 用 `[target.<triple>]` 下的
+`min_api_level`。两者都喂给 `llvm_triple()` 的同一个参数、占据构建指纹
+里的同一个槽位，因为一个 target 要么是 Apple 的要么是 Android 的，而两者
+回答的是同一个问题。另外，`host-coupled` 只意味着 mcpp 不做任何「把 C++
+运行时打进产物」的动作；它不会去掉链接因其他原因已经携带的工具链
+rpath——所以在 ELF 上，这类产物仍可能优先找到工具链自己的库。
+
+> **macOS + `self-contained` 与静态初始化次序。** Mach-O 没有按优先级
+> 排序的初始化段，而 libc++ 的 `<iostream>` 也不像 libstdc++ 与 MSVC
+> STL 那样自带 `ios_base::Init` 守卫——于是从 `libc++.a` 里拉出来的流
+> 初始化器，本来会排在程序自己的全局构造函数**之后**运行：一个在构造函数
+> 里碰了 `std::cout` 的全局对象，会读到一个尚未构造的流，并在进程启动时
+> 崩溃。mcpp 会把一个极小的生成对象排在链接最前面，把流的初始化顶上去；
+> 调用方代码不需要做任何事。详见 mcpp-community/mcpp#336。
+
+`defines` 接受**裸**的宏名（不带 `-D`），把每个条目脱糖为
+`-D<x>`，同时作用于 C 与 C++ 两条编译通道。它覆盖包内每一个翻译
+单元——包括模块接口单元——因此也会进入编译器自己的 P1689 模块扫描。
+
+> **但它不会让被宏保护的 `import` 变得可用。** mcpp 会在编译器看到文件
+> 之前先跑自己的词法预扫描，而那个扫描器对**任何** `#if` / `#ifdef`
+> 块内的 `import` 一律拒绝，不会对条件求值：
 >
 > ```
 > error: import statement inside conditional preprocessor block (forbidden in M1)
 > ```
 >
-> 所以即使 `FOO` 写在 `defines` 里,`#ifdef FOO` / `import bar;` 仍然会失败。
-> 替代写法是把条件放在全局模块片段的 `#include` 上。见
-> mcpp-community/mcpp#421。
-
-汇编单元同样能拿到。它是普通的构建
-输入,所以 `[target.'cfg(...)'.build]` 也能承载它:
+> 所以即使 `FOO` 写在 `defines` 里，`#ifdef FOO` / `import bar;` 这一对
+> 仍然会失败。替代写法是把条件放在全局模块片段里的一个 `#include` 上。
+> 跟踪于 mcpp-community/mcpp#421。汇编单元同样会拿到它。它是一个普通的
+构建输入，所以 `[target.'cfg(...)'.build]` 也能承载它：
 
 ```toml
 [build]
@@ -1104,61 +1166,65 @@ defines = ["APP_NAME=\"demo\""]
 defines = ["USE_WIN32", "WINVER=0x0A00"]
 ```
 
-选择合适的轴:
+选择合适的轴：
 
-| 想让宏作用于… | 用 |
+| 想让宏作用于…… | 用 |
 |---|---|
-| 本包的每个 TU | `[build].defines`(本节) |
-| 仅某个二进制自己的入口源 | `[targets.<name>].defines` |
-| 指定的一批文件 | `[build].flags` 配 `glob` + `defines` |
-| 本包每个 TU **以及**消费者的 TU | `[features.<name>].defines`(接口贡献) |
+| 本包每一个翻译单元 | `[build].defines`（本节） |
+| 只作用于某个二进制自己的入口源文件 | `[targets.<name>].defines` |
+| 一批指定的文件 | `[build].flags` 配 `glob` + `defines` |
+| 本包每一个翻译单元**以及**消费方每一个翻译单元 | `[features.<name>].defines`（接口层的贡献） |
 
-`[build].defines` 是包私有的:不会传播给消费者。
+`[build].defines` 是包私有的：不会传播给消费方。
 
-`[build]` 下不支持的键会作为警告报出(`--strict` 下为错误),而不是被静默忽略。
+`[build]` 下不受支持的键会作为警告报出（`--strict` 下为错误），而不是被
+静默忽略。
 
-C++ 标准不要通过 `build.cxxflags = ["-std=..."]` 配置。请使用:
+不要通过 `build.cxxflags = ["-std=..."]` 配置 C++ 标准。请改用：
 
 ```toml
 [package]
 standard = "c++26"
 ```
 
-mcpp 会把同一个标准用于普通 C++ 编译、模块扫描、`compile_commands.json` 和 `import std` 的标准库 BMI 构建。
+mcpp 会把同一个标准应用到普通 C++ 编译、模块扫描、
+`compile_commands.json`，以及 `import std` 所需的标准库 BMI 构建。
 
-**glob 排除**(`!` 前缀,mcpp 0.0.4+):
+**glob 排除**(`!` 前缀，mcpp 0.0.4+)：
 
 ```toml
 [build]
 sources = [
     "src/**/*.cpp",
-    "!src/**/*_test.cpp",       # 排除测试文件
-    "!src/**/*_fuzzer.cpp",     # 排除 fuzzer
+    "!src/**/*_test.cpp",       # Exclude test files
+    "!src/**/*_fuzzer.cpp",     # Exclude fuzzers
 ]
 ```
 
-**per-glob 旗标**(mcpp 0.0.95+):`[build] flags` 是**有序**的内联表数组,把额外
-编译旗标只附加到 glob 命中的源文件——SIMD 多档 dispatch TU 与三方代码告警隔离的
-正解:
+**per-glob 旗标**(mcpp 0.0.95+)：`[build] flags` 是一个**有序**的内联
+表数组，把额外的编译旗标只附加到一个 glob 命中的那些源文件上——这是
+SIMD dispatch 翻译单元与三方代码告警隔离的正解：
 
 ```toml
 [build]
 flags = [
-  { glob = "third_party/**",         cflags = ["-w"], cxxflags = ["-w"] },
-  { glob = "src/simd/**/*.avx2.cpp", cxxflags = ["-mavx2"], defines = ["HAVE_AVX2"] },
-  { glob = "src/x86/**/*.asm",       asmflags = ["-DPREFIX"] },
+  { glob = "third_party/**",            cflags = ["-w"], cxxflags = ["-w"] },
+  { glob = "src/simd/**/*.avx2.cpp",    cxxflags = ["-mavx2"], defines = ["HAVE_AVX2"] },
+  { glob = "src/x86/**/*.asm",          asmflags = ["-DPREFIX"] },
 ]
 ```
 
-每条目键:`glob`(相对包根,必填)+ `cflags` / `cxxflags` / `asmflags` /
-`defines`(没有 `ldflags`——链接没有 per-TU 作用域)。声明顺序即应用顺序:靠后
-条目的旗标排在命令行更后,配合 GNU "后旗标胜",窄 glob 放在宽 glob 之后即可覆盖。
-所有命中条目都生效;这些是私有构建旗标,不会传播给消费者。glob 零命中会打印
-warning(打错的 glob 不允许静默无效)。
+每条目的键：`glob`（相对包根，必填），加上 `cflags` / `cxxflags` /
+`asmflags` / `defines`（没有 `ldflags`——链接没有按翻译单元的作用域）。
+声明顺序即应用顺序：靠后的条目，它的旗标排在命令行更后面，配合 GNU「后
+旗标胜」的规则，一个窄 glob 放在一个宽 glob 之后就能覆盖它。所有命中的
+条目都会生效。这些是私有构建旗标——它们不会传播给消费方。一个零命中的
+glob 会打印警告（一个拼错的 glob 不允许静默地什么都不做）。
 
-**生成文件**(mcpp 0.0.95+):`[generated_files]` 把相对路径映射到文件内容(支持
-TOML 多行字符串)。条目在源 glob 展开之前写入工程树——与 index 描述符合成模块
-包装文件是同一机制——内容进指纹,改内容即重建:
+**生成文件**(mcpp 0.0.95+)：`[generated_files]` 把一个相对路径映射到
+文件内容（支持 TOML 多行字符串）。这些条目会在源码 glob 展开之前写入
+工程树——与索引描述符合成模块包装文件用的是同一套机制——内容会进入
+指纹，所以编辑它会触发重建：
 
 ```toml
 [generated_files]
@@ -1169,20 +1235,24 @@ export module wrap;
 """
 ```
 
-路径必须留在工程根之内(`..` / 绝对路径是解析错误)。
+路径必须留在工程根之内（`..` 或绝对路径是解析错误）。
 
-**汇编源**(mcpp 0.0.95+):`.S`/`.s`(GAS——由 C 驱动器预处理,覆盖 ARM 与
-AT&T 语法 x86)和 `.asm`(NASM——Intel 语法 x86)是一等源文件:默认 glob 收录、
-进指纹、增量并行构建、像任何对象一样链接。NASM 的输出格式由目标三元组推导
-(`elf64`/`win64`/`macho64`/...——交叉构建零特判);`nasm` 仅在存在 `.asm` 单元时
-惰性解析:先 `PATH`,再 mcpp 沙箱,再 `xlings install nasm`;找不到 ≥2.16 的
-nasm 则**硬失败**(汇编绝不静默跳过)。限制:`.asm` 仅限 x86 目标(其他目标硬
-报错——用条件 sources 门控)、MSVC 工具链不支持 `.S`、`.asm` 即 NASM 语法
-(MASM 源请用 `!` 排除)。
+**汇编源文件**(mcpp 0.0.95+)：`.S`/`.s`（GAS——由 C 驱动预处理，覆盖
+ARM 与 AT&T 语法的 x86）和 `.asm`（NASM——Intel 语法的 x86）是一等公民的
+源文件：默认被 glob 收录、进入指纹、增量并行构建，并像任何其他对象一样
+被链接。NASM 的输出格式由 target 三元组推导得出
+（`elf64`/`win64`/`macho64`/...——交叉构建天然可用），而 `nasm` 本身只有
+在存在 `.asm` 单元时才会被惰性解析：先看 `PATH`，再看 mcpp 沙盒，再
+`xlings install nasm`；如果哪一处都得不到 ≥2.16 的 nasm，构建会**硬
+失败**（汇编绝不会被静默跳过）。限制：`.asm` 只支持 x86 target（其他
+target 上是硬错误——需要用条件 sources 把这些文件挡在外面），
+`.S` 在 MSVC 工具链上不可用，而 `.asm` 就是指 NASM 语法（MASM 源码应当
+用 `!` 排除）。
 
 ## 当前边界
 
-- **macOS 宿主上完全没有面向 Linux 的载荷**,因此从那里够不到任何 Linux 目标。这是
-  发布边界,不是引擎边界。
-- manifest 里显式写的 `[toolchain]`,或 `[target.X].toolchain`,**永不被推翻**。工程
-  钉了一个、随后遇到这个钉子服务不了的目标时,会被拒绝,而不是悄悄换成另一个编译器。
+- **一台 macOS 宿主完全没有面向 Linux 的载荷**，任何 Linux target 从那里
+  都够不到。这是一条发布边界，不是引擎边界。
+- manifest 里显式写的 `[toolchain]`，或者 `[target.X].toolchain`，
+  **永远不会被推翻**。一个工程钉住了一个编译器，随后遇到这个钉子服务不了
+  的 target 时，会被拒绝，而不是被悄悄换成另一个编译器。
diff --git a/docs/zh/21-the-target-triple.md b/docs/zh/21-the-target-triple.md
index 5db94efb7..3868d4a72 100644
--- a/docs/zh/21-the-target-triple.md
+++ b/docs/zh/21-the-target-triple.md
@@ -1,87 +1,90 @@
 # 21 —— 目标三元组
 
-**读者:**为另一台机器构建的人。
+**读者：** 正在为另一台机器构建的人。
 
-**本章回答的那一个问题:**目标怎样被命名、支持哪些目标、各在什么档位,以及哪些
-构建机能服务它们。
+**本章回答的那一个问题：** 目标如何命名，哪些目标受支持、各处于什么档位，
+以及哪些构建机能服务每一个目标。
 
-**不在这里:**manifest 怎样以目标为条件,那是 [22 —— 目标侧](22-target-side.md);
-以及没有操作系统的目标,那是 [40 —— 裸机](40-baremetal.md)。
+**不在这里：** manifest 如何以目标为条件，那是
+[22 —— 目标侧](22-target-side.md)；没有操作系统的目标，那是
+[40 —— 裸机](40-baremetal.md)。
 
 目标三元组写作 `<arch>-<os>` 或 `<arch>-<os>-<env>`。本章说明每一段的含义、
-第三段何时可以省略,以及为何这个答案在 mcpp 同时支持的两种体系下并不相同。
+第三段何时可以省略，以及为什么这个答案在 mcpp 同时支持的两套体系之间并不
+相同。
 
-## 两种体系,同一套拼写
+## 两套体系，同一套拼写
 
-mcpp 解析目标侧 —— 平台接口、C 库、编译期运行时与 C++ 运行时 —— 有两条路径,
-而一个工程通常在没有显式选择的情况下就落在其中之一。
+mcpp 用两种方式之一解析目标侧 —— 平台接口、C 库、编译器运行时与 C++
+运行时 —— 而一个工程通常落在其中之一，且并不需要显式选择。
 
-**传统预构建体系。** 一份工具链载荷为一个目标而构建,并随身携带那个目标的
-C 库。选中 `x86_64-linux-musl` 就是选中 musl-gcc 载荷,选中
-`x86_64-linux-gnu` 就是选中一份 glibc 的。三元组的第三段在解析期是承重的,
-因为它正是挑选载荷的方式。
+**预构建体系。** 一份工具链 payload 为一个目标构建，并随身携带那个目标的
+C 库。选中 `x86_64-linux-musl` 就是选中 musl-gcc 的 payload，选中
+`x86_64-linux-gnu` 就是选中一份 glibc 的 payload。三元组的第三段在解析期
+是承重的，因为它正是挑选 payload 的方式。
 
-**构建期体系。** 目标侧以包的形式出现在依赖图中,由正在运行的那个编译器
-从源码构建。第三段不选中任何东西,因为图已经决定了。这是
+**构建期体系。** 目标侧以包的形式出现在依赖图中，由正在运行的那个编译器
+从源码编译。第三段不选中任何东西，因为图已经做出了决定。这正是
 [第 15 章](24-openkal-cross.md)所描述的体系。
 
-两者的差别在于第三段**做什么**,而不在于它怎么拼。工程不声明自己属于哪一种;
-由依赖图决定,构建则报告它解析出了什么。
+两者的差别在于第三段**做什么**，而不在于怎么拼。工程不声明自己属于哪
+一种，由依赖图决定，构建随后报告它解析出了什么。
 
 ## 各段
 
 | 段 | 内容 | 例 |
 |---|---|---|
 | `arch` | 指令集 | `x86_64`、`aarch64`、`riscv64`、`wasm32` |
-| `os` | 操作系统,或 `none` | `linux`、`windows`、`macos`、`ios`、`emscripten`、`none` |
-| `env` | 见下 —— 它在每个平台上是不同的轴 | `gnu`、`musl`、`msvc`、`android`、`elf` |
+| `os` | 操作系统，或 `none` | `linux`、`windows`、`macos`、`ios`、`emscripten`、`none` |
+| `env` | 见下文 —— 它在每个平台上是不同的一根轴 | `gnu`、`musl`、`msvc`、`android`、`elf` |
 
-第三段值得留意,因为它在各处命名的并不是同一类东西:
+第三段值得留意，因为它在不同平台上命名的并不是同一类东西：
 
-| 平台 | `env` 命名 | 取值 |
+| 平台 | `env` 命名的对象 | 取值 |
 |---|---|---|
-| `linux` | **C 库** | `gnu`(glibc)、`musl`、`android`(bionic) |
-| `windows` | **对象 ABI** | `gnu`(Itanium C++ ABI)、`msvc`(微软的) |
+| `linux` | **C 库** | `gnu`（glibc）、`musl`、`android`（bionic） |
+| `windows` | **对象 ABI** | `gnu`（Itanium C++ ABI）、`msvc`（微软的） |
 | `none` | **对象格式** | `elf` |
-| `ios` | **真机还是模拟器** | `sim`(模拟器)、缺省(真机) |
-| `macos`、`emscripten` | 无;该平台不带这一段 | — |
-
-`sim` 是 Apple 这一侧唯一带段的行,而它命名的既不是 C 库也不是 ABI:模拟器构建
-有自己的 SDK(`iPhoneSimulator.sdk`)、产出自己的对象,并且取
-`-mios-simulator-version-min` 而真机取 `-miphoneos-version-min`。两个目标,所以
-两个身份。Apple 自己把它拼成 OS 段尾部的 `-simulator`,Rust 拼成
-`aarch64-apple-ios-sim`;两种拼法在这里都能解析,并且都规范化为
+| `ios` | **真机还是模拟器** | `sim`（模拟器）、缺省（真机） |
+| `macos`、`emscripten` | 什么都不命名；该平台不带这一段 | — |
+
+`sim` 是 Apple 这一侧唯一带段的行，而它命名的既不是 C 库也不是 ABI：模拟器
+构建有自己的 SDK（`iPhoneSimulator.sdk`），产出自己的对象，取
+`-mios-simulator-version-min`，而真机取 `-miphoneos-version-min`。两个
+目标，因此两个身份。Apple 把它拼成 OS 段末尾的 `-simulator`，Rust 拼成
+`aarch64-apple-ios-sim`；两种拼法在这里都能解析，并且都规范化为
 `aarch64-ios-sim`。
 
-`android` 是一个 **C 库**,所以它落在 `musl` 落的那个位置上,OS 段仍是 `linux`。
-这个位置就是这处建模决定的全部:内核**就是** Linux,所以 ELF、`unix` family、
-`nasm -f elf64` 全都已经是对的;而一个 `os = "android"` 会让这三样默认全错,并
-且要求在每一处站点给出一个新答案。它与 `gnu` 的差别是 bionic、加载器路径和 SDK
-—— 而这恰好就是 `env` 这一段存在的意义。
+`android` 是一个 **C 库**，因此它落在 `musl` 所在的位置上，OS 段仍是
+`linux`。这个安放方式就是这处建模决定的全部：内核**就是** Linux，所以
+ELF、`unix` family、`nasm -f elf64` 都已经是对的；而一个 `os = "android"`
+会让这三者默认全部出错，并要求在每一处站点都给出一个新答案。它与 `gnu`
+的差别是 bionic、加载器路径与 SDK —— 这正是 `env` 这一段存在的意义。
 
-在 Windows 上这一段经常被读错,因为 `gnu` 这个词暗示了一个并不在场的 C 库。
-对一份按构建期体系为 `x86_64-windows-gnu` 构建的产物实测:
+在 Windows 上这一段经常被读错，因为 `gnu` 这个词暗示了一个并不在场的
+C 库。对一份按构建期体系为 `x86_64-windows-gnu` 构建的产物实测：
 
 | 观测 | 值 |
 |---|---|
-| 导入的库 | `ntdll`、`KERNEL32`、`SHELL32` —— 无 `msvcrt`,无 `ucrtbase` |
-| Itanium 修饰符号(`_Z…`) | 4507 |
-| MSVC 修饰符号(`?…`) | 0 |
+| 导入的库 | `ntdll`、`KERNEL32`、`SHELL32` —— 没有 `msvcrt`，没有 `ucrtbase` |
+| Itanium 修饰符号（`_Z…`） | 4507 |
+| MSVC 修饰符号（`?…`） | 0 |
 
-没有任何 GNU 的东西在场:编译器是 clang,链接器是 lld,编译期运行时是
-compiler-rt,C 库是 musl,C++ 运行时是 libc++,平台是 openkal。`gnu` 是
-LLVM 词表里「非 MSVC 的那套 ABI」的标签,继承自 MinGW,而 clang 需要这个
-拼写来选中正确的内部工具链。mcpp 改不了它。
+没有任何 GNU 的东西在场：编译器是 clang，链接器是 lld，编译器运行时是
+compiler-rt，C 库是 musl，C++ 运行时是 libc++，平台是 openkal。`gnu` 是
+LLVM 词表里「非 MSVC 那套 ABI」的标签，继承自 MinGW，而 clang 需要这个
+拼法来选中正确的内部工具链。mcpp 无法为它改名。
 
-### 对象格式是一个轴,不是一处推导
+### 对象格式是一根轴，不是一次推导
 
-一个三元组的二进制格式过去根本不是任何东西:它在每一处需要它的地方从 `os` 重新
-推导一遍。`is_pe()` 问 `os == "windows"`,产物命名再问一遍,打包器问第三遍。答案
-只有两个取值时,这是负担得起的。
+三元组的二进制格式过去根本不是独立存在的东西：它在每一处需要它的地方从
+`os` 重新推导一遍。`is_pe()` 问一遍 `os == "windows"`，产物命名再问一遍，
+打包器问第三遍。当答案只有两个取值时，这样做还负担得起。
 
-`wasm32` 是 mcpp 词表里第一个格式不属于那两个的目标,而第三个取值会把那些推导变成
-**在每一处这样的站点上的一次添加** —— 而漏掉的那一处不会报错。它会静默地答 ELF,
-因为 ELF 正是这棵树里每一个 `else` 分支所假设的东西。于是格式现在是一个答案:
+`wasm32` 是 mcpp 词表里第一个格式不属于这两者之一的目标，而第三个取值会
+把这些推导变成**每一处这样的站点都要新增一次判断**——而漏掉的那一处
+不会报错，它会静默地答成 ELF，因为 ELF 正是这棵树里每一个 `else` 分支
+所假设的东西。于是格式现在是一个单一答案：
 
 | 目标 | 格式 |
 |---|---|
@@ -90,62 +93,66 @@ LLVM 词表里「非 MSVC 的那套 ABI」的标签,继承自 MinGW,而 clang 
 | `x86_64-windows-gnu`、`x86_64-windows-msvc` | PE |
 | `wasm32-emscripten` | wasm |
 
-它与「有没有一个操作系统可供链接」**不是**同一个问题。一个裸机 RISC-V 映像是 ELF
-且没有 OS;一个 wasm 模块有一层类 OS 的东西(Emscripten 的 POSIX 模拟)而不是
-ELF。把这两个轴并成一个,正是这处改动要消除的那个错误。
+它与「有没有一个操作系统可供链接」**不是**同一个问题。一个裸机 RISC-V
+镜像是 ELF 且没有 OS；一个 wasm 模块有一层类 OS 的东西（Emscripten 的
+POSIX 模拟层）却不是 ELF。把这两根轴合并成一根，正是这处改动所要
+取代的错误。
 
 ## wasm 产物契约
 
-`artifact_naming` 在每一行上是同一句话:可执行文件是**runner 执行的那个文件**,
-按这一行自己的拼法命名。在 `wasm32-emscripten` 上,那个文件是 JavaScript 启动
-器——载荷的 `node` 运行的、浏览器加载的正是它——所以这一行对它的拼法是
-`bin/<name>.js`,而不是 mcpp 2026.9.12.3 之前那种裸的、借用宿主拼法的名字。
-面向 Emscripten 的两套权威构建系统各用一行话钉死了同一个后缀,原因相同:
-Emscripten 自己的 CMake 工具链设置 `CMAKE_EXECUTABLE_SUFFIX ".js"`,Rust 的
-`wasm32-unknown-emscripten` target spec 设置 `exe_suffix: ".js"`。
+`artifact_naming` 在每一行上说的是同一句话：可执行文件是**runner 执行
+的那个文件**，按该行自己的约定命名。在 `wasm32-emscripten` 上，那个
+文件是 JavaScript 启动器 —— payload 的 `node` 运行的、浏览器加载的正是
+它 —— 所以这一行对它的约定是 `bin/<name>.js`，而不是 mcpp 2026.9.12.3
+之前那种裸的、借用宿主约定的名字。面向 Emscripten 的两套权威构建系统
+出于同一个原因，各自钉死了相同的后缀：Emscripten 自己的 CMake 工具链
+设置 `CMAKE_EXECUTABLE_SUFFIX ".js"`，Rust 的 `wasm32-unknown-emscripten`
+target spec 设置 `exe_suffix: ".js"`。
 
 | kind | 文件 | 说明 |
 |---|---|---|
-| `bin`、`app` | `bin/<name>.js` | `bin/<name>.wasm` 是同一条链接边的隐式输出,随它一起暂存。emcc 用同一词干写出的其余文件(`--preload-file` 产生的 `<name>.data`、`<name>.worker.js`、`<name>.wasm.map`)在链接产出了它们时才会出现 |
-| `lib` | `lib/lib<name>.a` | —— |
-| `shared` | 被拒绝,点名 `-sSIDE_MODULE` | wasm 的 side module 需要一种 mcpp 不渲染的链接契约 |
-
-`--no-entry` 不是 mcpp 解释的开关。它是一条普通的
-`[target.'cfg(os = "emscripten")'.build] ldflags` 条目,`main` 仍然只是在每一行
-上都一样地指出一个翻译单元——所以一个模块化的 Web 程序,如果它的页面调用一个
-导出的工厂函数,就是一个 `main` 文件不定义 `main()` 的 `bin` 目标,在自己的
-`ldflags` 里带上 `--no-entry` 链接。
-
-执行 `bin/<name>.js` 的 runner 来自载荷描述文件(`.mcpp-toolchain.json`)、项目的
-`[target.<triple>] runner`,或依赖的 `mcpp::runner(...)`——与每一行相同的解析
-顺序。`.js` 文件没有 shebang,所以一份在它的描述文件获得 `runner` 字段之前就装好
-的 emsdk 载荷,需要先做[第 20 章](20-toolchains.md)说的那次索引刷新,`mcpp run`
-才能找到 runner。
+| `bin`、`app` | `bin/<name>.js` | `bin/<name>.wasm` 是同一条链接边的隐式输出，随它一起暂存。emcc 用同一个词干写出的其余文件（`--preload-file` 产生的 `<name>.data`、`<name>.worker.js`、`<name>.wasm.map`）恰好在链接产出它们时一并出现 |
+| `lib` | `lib/lib<name>.a` | — |
+| `shared` | 被拒绝，点名 `-sSIDE_MODULE` | wasm 的 side module 需要一种 mcpp 不渲染的链接契约 |
+
+`--no-entry` 不是 mcpp 解释的开关，它是一条普通的
+`[target.'cfg(os = "emscripten")'.build] ldflags` 条目，`main` 仍然像
+在每一行上一样只是指名一个翻译单元 —— 因此一个模块化的 Web 程序，如果
+它的页面调用一个导出的工厂函数，就是一个 `main` 文件不定义 `main()` 的
+`bin` 目标，在自己的 `ldflags` 行上带 `--no-entry` 链接。
+
+执行 `bin/<name>.js` 的 runner 来自 payload 描述符
+（`.mcpp-toolchain.json`）、工程的 `[target.<triple>] runner`，或者
+某个依赖的 `mcpp::runner(...)`——与每一行相同的解析顺序。一个 `.js`
+文件不带 shebang，因此一份在它的描述符获得 `runner` 字段之前就已装好
+的 emsdk payload，需要先经过[第 20 章](20-toolchains.md)所述的那次索引
+刷新，`mcpp run` 才能找到 runner。
 
 ## 省略第三段
 
-`<arch>-<os>` 在每个平台上都是一个完整的目标:
+`<arch>-<os>` 在每个平台上都是一个完整的目标：
 
 ```bash
 mcpp build --target x86_64-linux      # = x86_64-linux-gnu
 mcpp build --target x86_64-windows    # = x86_64-windows-gnu
 mcpp build --target riscv64-none      # = riscv64-none-elf
 mcpp build --target aarch64-linux     # = aarch64-linux-musl
-mcpp build --target aarch64-macos     # macOS 本来就没有这一段可省
+mcpp build --target aarch64-macos     # macOS has no segment to decline
 ```
 
-省略它不改变任何身份。输出目录、缓存键与 `cfg()` 谓词的主语都取规范形式,
-因此两种拼法共用一个指纹,第二次构建是缓存命中而不是又一次完整构建。
+省略它不改变任何身份。输出目录、缓存键，以及 `cfg()` 谓词的对象，都取规范
+形式，因此两种拼法共用同一个指纹，第二次构建是缓存命中，而不是又一次
+完整构建。
 
-不同的是**请求被记录成了什么**。三元组既是身份 —— 身份必须完整 ——
-也是请求 —— 请求必须能什么都不说;mcpp 两者都保留:为身份填上那一段,
-同时记住这次填充是一次填充。
+不同的是**请求被记录成了什么**。三元组既充当身份 —— 身份必须完整 ——
+又充当请求 —— 请求必须能够什么都不说；mcpp 两者都保留：为身份填上那一
+段，同时记住这次填充只是一次填充。
 
-### 补全取自词表,不取自一个固定的词
+### 补全取自词汇表，而不是取自一个固定的词
 
 上面第四行正是这两种角色必须分开的理由。把 `aarch64-linux` 按词法填成
-`aarch64-linux-gnu`,而那一行是 `planned` —— `aarch64-linux-musl` 才是
-`verified`。2026.8.26.2 之前,tier 闸问的是填充后的值:
+`aarch64-linux-gnu`，而那一行是 `planned`——`aarch64-linux-musl` 才是
+`verified`。2026.8.26.2 之前，档位闸问的是填充之后的值：
 
 ```
 $ mcpp build --target aarch64-linux
@@ -154,42 +161,47 @@ $ mcpp build --target aarch64-linux-musl
   Finished dev [unoptimized + debuginfo] in 0.99s
 ```
 
-被问的问题是「aarch64 的 Linux」。被回答的问题是「aarch64-linux-**gnu**」,
-而报错引用的三元组在那条命令里根本不存在。`riscv64-linux` 更严重:填充产生的
-那一行完全不在词表里,于是一个**已登记**的目标族被报成 `unknown target`。
+被问的问题是「aarch64，Linux」。被回答的问题却是「aarch64-linux-**gnu**」，
+而报错引用的三元组在那条命令里根本不存在。`riscv64-linux` 更严重：填充
+出来的那一行完全不在词汇表里，于是一个已登记的目标族被报成
+`unknown target`。
 
-省略了这一段的请求,按下列顺序对着已知目标表补全:
+省略了这一段的请求，按下列顺序对着已知目标表补全：
 
-1. 词法默认命中一个受支持的行 —— 用它(`x86_64-linux` → `gnu`);
-2. 该 `(arch, os)` 下恰好一个受支持的行 —— 用它(`aarch64-linux` → `musl`);
-3. 一个受支持的都没有 —— 保留词法形式,并对着**确实存在**的那些行给出诊断
-   (`riscv64-linux` → 「planned;该系统已登记的行:`riscv64-linux-musl`」);
-4. 多个受支持而词法默认不在其中 —— 拒绝并列出候选。今天没有任何
-   `(arch, os)` 是这个形状。
+1. 词法默认值命中一个受支持的行 —— 采用它（`x86_64-linux` → `gnu`）；
+2. 该 `(arch, os)` 下恰好一个受支持的行 —— 采用它（`aarch64-linux` →
+   `musl`）；
+3. 一个受支持的都没有 —— 保留词法形式，并对着**确实存在**的那些行给出
+   诊断（`riscv64-linux` → 「planned；该系统已登记的行：
+   `riscv64-linux-musl`」）；
+4. 多个受支持而词法默认值不在其中 —— 拒绝并列出候选。今天没有任何
+   `(arch, os)` 呈这个形状。
 
-规则 1 排在最前,使这件事能自己退休:`aarch64-linux-gnu` 从 `planned` 升级的
-那一天,词法答案重新胜出,不需要有人回来改任何东西。
+规则 1 排在最前，使这条规则能自己退休：`aarch64-linux-gnu` 从
+`planned` 升级的那一天，词法答案重新胜出，不需要任何人回来修改什么。
 
-**写出这一段就是退出补全。** 写出来的段是请求而不是空缺,因此
-`--target aarch64-linux-gnu` 仍会撞上 `planned` 行的拒绝 —— 那正是用显式
-`[target.<triple>] toolchain` 提前加入某一行的逃生口。
+**写出这一段即是退出补全。** 写出来的段是一次请求而不是一处空缺，因此
+`--target aarch64-linux-gnu` 仍会撞上 `planned` 行的拒绝 —— 那正是用
+显式的 `[target.<triple>] toolchain` 提前加入某一行的逃生口。
 
 ### 采用的拼法
 
-**在构建期体系下,省略它。** 图供给 C 库与各运行时,那一段陈述的是一个
-不会被查询的请求。在这种体系下,`x86_64-windows` 不只是比
-`x86_64-windows-gnu` 短 —— 它更准确,因为并没有任何 GNU 的东西参与。
+**在构建期体系下，省略它。** 图供给 C 库与各运行时，因此那一段陈述的是
+一个不会被查询的请求。在这套体系下，`x86_64-windows` 不只是比
+`x86_64-windows-gnu` 更短 —— 它更准确，因为其中并没有任何 GNU 的东西
+参与。
 
-**在传统预构建体系下,当这个选择有意义时写出它。**
-`x86_64-linux-musl` 与 `x86_64-linux-gnu` 选中不同的载荷、产出不同的产物。
-写出那一段正是作出这个选择的方式。
+**在预构建体系下，当这个选择有意义时写出它。** `x86_64-linux-musl` 与
+`x86_64-linux-gnu` 选中不同的 payload，产出不同的产物。写出那一段正是
+做出这个选择的方式。
 
-**在 Windows 上,想要微软那套 ABI 时写 `msvc`。** `gnu` 是默认填充,
-而 `msvc` 是不同的对象 ABI 而非不同的 C 库,因此那一段在两种体系下都有意义。
+**在 Windows 上，想要微软那套 ABI 时写 `msvc`。** `gnu` 是默认填充值，
+而 `msvc` 是不同的对象 ABI 而非不同的 C 库，因此那一段在两套体系下都
+有意义。
 
-## 构建的报告内容
+## 构建报告
 
-报告以写下的目标为标题,并把它解析为编译器自己的拼写:
+报告以写下的目标为标题，并把它解析成编译器自己的拼法：
 
 ```
       Target x86_64-windows → x86_64-w64-windows-gnu
@@ -198,10 +210,11 @@ $ mcpp build --target aarch64-linux-musl
              c++-abi           libc++         (openkal-llvm-runtime@0.1.2, graph)
 ```
 
-有两条诊断挂在第三段上,适用哪一条由上面那张表决定。
+有两条诊断挂在第三段上，适用哪一条由上面那张表决定。
 
-**当该段命名 C 库、而图供给了另一个时,构建报出这个分歧。** 以图为准,
-所以这是报出而非拒绝 —— 两种写法下产物相同,不准确的只是名字:
+**当该段命名一个 C 库，而图供给的是另一个时，构建报出这个分歧。** 以图
+为准，所以这是一次报告而不是一次拒绝 —— 两种写法下产物相同，不准确的
+只是名字：
 
 ```
 warning: the target name asks for the `gnu` C ABI and the dependency graph supplies `musl`.
@@ -210,23 +223,24 @@ warning: the target name asks for the `gnu` C ABI and the dependency graph suppl
            --target x86_64-linux
 ```
 
-**当该段命名的是别的东西时,报告说出那是什么。** 在那里发警告是错的:
-它会在每一次合法的 MinGW 构建上出现,并且描述了一条名字从未涉及的轴。
-该提示只在使用者主动写出那一段时出现,且命名那套 **ABI 本身**而非任何一层:
+**当该段命名的是别的东西时，报告说出那是什么。** 在那种情形下发警告
+是错的：它会在每一次合法的 MinGW 构建上触发，并且描述了一根名字从未
+涉及的轴。这条提示只在使用者写出了那一段时才出现，并且命名的是 **ABI
+本身**而不是任何一层：
 
 ```
 Target x86_64-windows-gnu → x86_64-w64-windows-gnu   (gnu selects the Itanium C++ ABI, not a C library)
 ```
 
-而它**不对应报告里的任何一行**,这正是要点。五层记录的是每一层
-**由谁供给**;那一段命名的是这些**对象遵循哪套约定**,是若干层必须一致的
-横切事项。把它读成 `c++-abi libc++` 是第二个错误答案,因为 libstdc++
-坐在同一套 ABI 上。
+它**不对应报告里的任何一行**，这正是要点所在。五层记录的是每一层
+**由谁供给**；而那一段命名的是这些**对象所遵循的约定**，是若干层必须
+彼此一致的事项。把它读成 `c++-abi libc++` 是第二个错误答案，因为
+libstdc++ 处在同一套 ABI 之上。
 
-## 三套词表,以及它们不同的原因
+## 三套词汇表，以及它们不同的原因
 
-一个三元组由三方书写,而三方并不共用一套约定;mcpp 在它们之间翻译。
-知道手上这个字符串属于哪一套,第三段带来的困惑就消掉大半。
+一个三元组由三方书写，而三方并不共用一套约定；mcpp 在它们之间翻译。
+弄清手上这个字符串属于哪一套，第三段带来的困惑就消掉了大半。
 
 ### 形状
 
@@ -234,139 +248,145 @@ Target x86_64-windows-gnu → x86_64-w64-windows-gnu   (gnu selects the Itanium
 <arch> - <vendor> - <os> - <env>
 ```
 
-每一段都可省,省掉的由编译器补。`vendor` 是历史遗留,今天几乎不承重 ——
-除非目标有理由说别的,否则一律填 `unknown`:
+每一段都可以省略，缺失的部分由编译器补齐。`vendor` 是历史遗留，今天
+几乎不承载任何信息 —— 除非目标有理由另作声明，否则一律填成
+`unknown`：
 
 ```
 x86_64-linux-gnu   →  x86_64-unknown-linux-gnu
 aarch64-macos      →  aarch64-unknown-macos
 ```
 
-三段写法是四段省掉一段,省的是哪一段由「能否解析」决定。
+三段式的拼法是四段式省掉一段之后的样子，省掉的是哪一段，由「能不能
+解析」决定。
 
-### GCC 与 clang 选目标的方式根本不同
+### GCC 与 clang 选目标的方式并不相同
 
 | | GCC | clang |
 |---|---|---|
-| 目标 | **构建编译器时**就定死 | **运行时**选 |
-| 怎么问 | `-dumpmachine` | `-dumpmachine`,或 `--target=` |
-| 交叉编译 | 换**另一个可执行文件** | 传一个 flag |
+| 目标 | 在编译器**构建**时就已定死 | 在**运行时**选定 |
+| 怎么问 | `-dumpmachine` | `-dumpmachine`，或 `--target=` |
+| 如何交叉编译 | 换一个**不同的可执行文件** | 传一个 flag |
 
-实测:
+实测：
 
 ```
-g++                     →  x86_64-linux-gnu       (只能发这个)
-x86_64-w64-mingw32-g++  →  x86_64-w64-mingw32     (只能发这个)
-clang++                 →  x86_64-unknown-linux-gnu,而 --target= 可改
+g++                     →  x86_64-linux-gnu       (emits nothing else)
+x86_64-w64-mingw32-g++  →  x86_64-w64-mingw32     (emits nothing else)
+clang++                 →  x86_64-unknown-linux-gnu, and --target= changes it
 ```
 
-这就是传统预构建体系**不传 `--target`** 的原因:那份载荷的编译器以它唯一
-能发的目标命名,选目标等于选载荷。也是构建期体系只需要一个编译器的原因。
+这正是预构建体系**不传 `--target`** 的原因：那份 payload 的编译器以它
+唯一能发出的那个目标命名，选目标就等于选 payload。这也是构建期体系
+只需要一个编译器的原因。
 
 ### MinGW 按 GCC 的约定给自己命名
 
-MinGW 自己的三元组是 `x86_64-w64-mingw32`:
+MinGW 自己的三元组是 `x86_64-w64-mingw32`：
 
 | 段 | 值 | 原因 |
 |---|---|---|
 | arch | `x86_64` | |
-| vendor | `w64` | 项目名 `mingw-w64`,用以区别于已停滞的原 `mingw32` 项目 |
-| os | **`mingw32`** | MinGW 把**自己**放在 OS 位 |
-| env | (无) | 三段就是全名 |
+| vendor | `w64` | 项目名是 `mingw-w64`，用以区别于已停滞的原始 `mingw32` 项目 |
+| os | **`mingw32`** | MinGW 把**自己**放在 OS 段 |
+| env | （缺席） | 三段就是全部名字 |
 
-这套约定源自 autoconf 的 `config.guess`,那里 OS 段命名的是目标的运行环境 ——
-而在 GNU 工具链的世界观里 MinGW **就是**一个独立环境:有自己的头文件、
-自己的 C 运行时、自己的 `configure` 分支。名字里的 `32` 是历史遗留,
-`w64` 才表示这是那个支持 64 位的项目。
+这套约定源自 autoconf 的 `config.guess`，其中 OS 段命名的是目标的运行
+环境 —— 而在 GNU 工具链的世界观里，MinGW **就是**一个独立的环境：有
+自己的头文件、自己的 C 运行时，也有自己的 `configure` 分支。名字里的
+`32` 是历史遗留；`w64` 才表明这个名字指的是那个支持 64 位的项目。
 
-LLVM 不接受这个世界观。它认为 OS 是 `windows`,MinGW 只是其上的一种 ABI
-环境,于是把这个名字重拼 —— 实测:
+LLVM 不接受这个世界观。它认定 OS 是 `windows`，MinGW 只是架在其上的
+一种 ABI 环境，因此把这个名字重新拼过 —— 实测：
 
 ```
 x86_64-w64-mingw32  →  x86_64-w64-windows-gnu
 x86_64-pc-mingw32   →  x86_64-pc-windows-gnu
 ```
 
+
 ```
-GCC   x86_64 - w64     - mingw32 - (无)
+GCC   x86_64 - w64     - mingw32 - (none)
                 ^vendor   ^os
 LLVM  x86_64 - unknown - windows - gnu
                 ^vendor   ^os       ^env
 ```
 
-**`mingw32` 从 OS 位被拆成 `windows` 加 `gnu`。** `gnu` 这个取值之所以
-存在,正是因为 LLVM 需要给拆剩下的那一半起个名字。它的含义是
-「MinGW/Itanium 这一支 ABI」,在 Windows 上从来不是「C 库是 glibc」——
-同一个词在不同操作系统下承担不同职责,这是 LLVM 词表的既有事实,
-不是 mcpp 的发明。
+**`mingw32` 从 OS 段被拆成 `windows` 加 `gnu` 两段。** `gnu` 这个取值
+之所以存在，正是因为 LLVM 需要给拆分出来剩下的那一半起一个名字。它的
+含义是「MinGW/Itanium 这一支 ABI」，在 Windows 上从来不意味着「C 库是
+glibc」—— 同一个词在不同操作系统下承担不同的职责，这是 LLVM 词汇表
+既有的事实，不是 mcpp 的发明。
 
 ### mcpp 保留的那一套
 
-| 词表 | 例 | 读者 |
+| 词汇表 | 例 | 读者 |
 |---|---|---|
-| GCC / autoconf | `x86_64-w64-mingw32` | 预构建载荷的编译器,以文件名的形式 |
+| GCC / autoconf | `x86_64-w64-mingw32` | 预构建 payload 的编译器，以文件名的形式读取 |
 | LLVM | `x86_64-w64-windows-gnu` | `clang --target=` |
-| **mcpp** | `x86_64-windows-gnu` | 目标表、输出目录、`cfg()`、打包的 ABI tag |
+| **mcpp** | `x86_64-windows-gnu` | 目标表、输出目录、`cfg()`、打包出的 ABI tag |
 
-mcpp 自己那套必须能映到前两套。构建报告里那个箭头就是这个映射,
-从第三套到第二套:
+mcpp 自己那套拼法必须能映射到另外两套上。构建报告里的那个箭头就是这个
+映射，从第三套词汇表映到第二套：
 
 ```
 Target x86_64-windows-gnu → x86_64-w64-windows-gnu
        ^ mcpp                ^ LLVM
 ```
 
-把第三套词表独立出来,正是 mcpp 能命名 LLVM 命名不了的东西的原因。
-实测 llvm 22.1.8:`windows` 配 `musl` 环境能被三元组解析器接受,
-而编译器会崩:
+让第三套词汇表保持独立，正是 mcpp 能够命名 LLVM 命名不了的东西的原因。
+在 llvm 22.1.8 上实测：`windows` 配一个 `musl` 环境能被三元组解析器
+接受，却会让编译器崩溃：
 
 ```
 clang++ --target=x86_64-pc-windows-musl -c t.cpp
     #5  llvm::MCWinCOFFStreamer::emitCGProfileEntry(...)
 ```
 
-崩点在 **COFF 写出器**:clang 已认定输出是 COFF,却没有一条 Windows-musl
-的路径去把 streamer 需要的状态配齐。它认识的四个非 MSVC Windows 环境 ——
-`gnu`、`cygnus`、`itanium`、`musl` —— 前三个都能编,只有 `musl` 死;
-预定义宏说明了这个环境从未被建模:
+崩溃发生在 **COFF 写出器**里：clang 已经认定输出是 COFF，却没有一条
+Windows-musl 的路径去把 streamer 配置好。它认识的四个非 MSVC 的
+Windows 环境 —— `gnu`、`cygnus`、`itanium`、`musl` —— 前三个都能编译，
+只有 `musl` 会崩溃，而预定义宏说明了这个环境为什么从未被建模：
 
 | 三元组 | 宏 |
 |---|---|
 | `…-windows-gnu` | `__GNUC__` `__MINGW32__` `_WIN32` |
 | `…-windows-msvc` | `_MSC_VER` `_WIN32` |
-| `…-windows-musl` | `__GNUC__` `_WIN32` —— **无 `__MINGW32__`** |
+| `…-windows-musl` | `__GNUC__` `_WIN32` —— **没有 `__MINGW32__`** |
 
-所以 Windows 上的 musl C 库**无法**向 clang 命名,而 mcpp 仍然必须为它命名,
-因为 mcpp 的名字回答的是另一个问题:**C 库是谁**,而 LLVM 的名字回答
-**遵循哪套对象 ABI**。两者都需要,且不是同一个字符串。
+所以 Windows 上的 musl C 库无法向 clang 命名，却仍然必须由 mcpp 命名，
+因为 mcpp 的名字回答的是另一个问题 —— **哪一个 C 库**，而 LLVM 的名字
+回答的是**哪一套对象 ABI**。两者都是必需的，而且不是同一个字符串。
 
-## 编译器与 C 库是两个轴
+## 编译器与 C 库是两根轴
 
-目标命名的是一台机器。它不指定谁来编译,也不指定它的 C 库从哪来 —— 那是另外两个
-选择,而同一个目标字符串在每种选择下都是不同的构建。
+目标命名的是一台机器。它不命名谁来为它编译，也不命名它的 C 库从哪里
+来 —— 那是另外两个选择，同一个目标字符串在每种选择下对应不同的构建。
 
-**「来自载荷」不是某一份固定载荷**,而是所选编译器带来的那一份;gcc 与 clang
-带法不同:gcc 一个目标一份载荷、驱动带三元组前缀,而一个 `clang++` 打它构建时支持
-的每个目标。同一台宿主、同一份源码实测:
+**「来自 payload」并不是某一份固定的 payload**，而是所选编译器带来的
+那一份；gcc 与 clang 带来它的方式并不相同：gcc 一个目标一份 payload，
+驱动带三元组前缀，而一个 `clang++` 就能发出它构建时支持的每一个目标。
+在同一台宿主、同一份源码上实测：
 
-| 工具链 | 目标 | 实际运行的驱动 | c-abi | c++-abi |
+| toolchain | target | driver that ran | c-abi | c++-abi |
 |---|---|---|---|---|
 | `gcc@16.1.0` | `x86_64-linux-musl` | `xim-x-musl-gcc/…/x86_64-linux-musl-g++` | musl | libstdc++ |
 | `gcc@16.1.0` | `x86_64-windows-gnu` | `xim-x-mingw-cross-gcc/…/x86_64-w64-mingw32-g++` | gnu | libstdc++ |
 | `llvm@22.1.8` | `x86_64-linux-musl` | `xim-x-llvm/…/clang++` | musl | libc++ |
 | `llvm@22.1.8` | `x86_64-windows-gnu` | `xim-x-llvm/…/clang++` | gnu | libc++ |
 
-clang 不会去 gcc 的载荷里取 C 库,gcc 也不会去 clang 的载荷里取。各带各的。
+clang 不会伸进 gcc 的 payload 里取 C 库，gcc 也不会伸进 clang 的。
+各带各的。
 
-### 换另一个编译器,就要把另一份 C 库一起换上
+### 换另一个编译器，就要一并供给另一份 C 库
 
-每一行有宿主的目标都写着一个工具链,而那个名字是**约定**不是**能力**:它回答的是
-*哪个载荷供给这个目标的 C 库*,所以一个自己供给 C 库的工程可以写另一个编译器。
-不能做的是写另一个编译器而什么都不供给。
+每一个 hosted 行都写着一个工具链，而这个名字是**约定**而不是**能力**：
+它回答的是*哪一份 payload 供给这个目标的 C 库*，因此一个自己供给 C 库
+的工程可以写另一个编译器。不能做的是写另一个编译器却什么都不供给。
 
 ```toml
 [toolchain]
-default = "llvm@22.1.8"        # x86_64-linux-musl 这一行写的是 gcc
+default = "llvm@22.1.8"        # x86_64-linux-musl's row names gcc
 ```
 
 ```
@@ -375,13 +395,14 @@ error: target 'x86_64-linux-musl' takes its C library from the 'gcc@16.1.0'
        payload, and 'llvm@22.1.8' has none here.
 ```
 
-**2026.8.26.1 之前这会把整个构建跑完,然后在链接上失败**,报
-`crtbeginT.o (bare name — the linker cannot resolve it)`——对症状准确,对决定沉默。
-clang 是可重定向的,自己不带 C 库,于是去够一份 gcc 安装;在恰好装了系统 mingw 的
-机器上,同样写法用于 `x86_64-windows-gnu` 够到的是
-`/usr/lib/gcc/x86_64-w64-mingw32/…`,那比失败更糟。
+**2026.8.26.1 之前，这会把整个构建跑完，才在链接阶段失败**，报出
+`crtbeginT.o (bare name — the linker cannot resolve it)`——对症状的描述
+准确，却对背后的决定只字不提。clang 是可重定向的，自己不带 C 库，于是
+去够一份 gcc 安装；在一台恰好装有系统 mingw 的机器上，同样的写法用于
+`x86_64-windows-gnu` 时，够到的是 `/usr/lib/gcc/x86_64-w64-mingw32/…`，
+这比直接失败更糟。
 
-补上替代者,就是全部的差别:
+补上替代者，就是全部的差别：
 
 ```toml
 [dependencies]
@@ -390,64 +411,71 @@ openkal-llvm-runtime = "0.1.3"   # → openkal-musl → openkal-<os>
 default = "llvm@22.1.8"
 ```
 
-这就是 [`examples/06-openkal-cross`](../../examples/06-openkal-cross),也是那句
-拒绝里为什么点名 openkal。
+这就是 [`examples/06-openkal-cross`](../../examples/06-openkal-cross)，也是
+那条拒绝会在文本里点名 openkal 的原因。
 
-**裸机行与 `x86_64-windows-musl` 行的工具链不是约定**,根本不可被推翻——
-见[第 03 章](20-toolchains.md)。
+**裸机某一行的工具链不是约定，`x86_64-windows-musl` 那一行的也不是**——
+没有任何 gcc payload 能发出带 musl C 库的 PE，因此这些行完全无法被
+覆盖。见[第 03 章](20-toolchains.md)。
 
-### 而依赖图会整个替换这一轴
+### 而依赖图会把这根轴整个替换掉
 
-同样三个目标,图里有 `openkal-musl` 与 `openkal-llvm-runtime` —— 同法实测:
+同样三个目标，图里带有 `openkal-musl` 与 `openkal-llvm-runtime` —— 按
+同样的方式实测：
 
-| 目标 | kernel-abi | c-abi | c++-abi |
+| target | kernel-abi | c-abi | c++-abi |
 |---|---|---|---|
-| `x86_64-linux-musl` | openkal(openkal-linux,图) | musl(图) | libc++(图) |
-| `x86_64-windows-gnu` | openkal(openkal-windows,图) | musl(图) | libc++(图) |
-| `x86_64-windows-musl` | openkal(openkal-windows,图) | musl(图) | libc++(图) |
-
-**看两张表里的 `x86_64-windows-gnu`。** 载荷供给时它的 C 库是 `gnu`,即 MinGW
-CRT;图供给时是 `musl`。一个目标字符串,两个不同的 C 库 —— 而 mcpp 在 2026.8.24.6
-之前无法说清是哪一个:同一条 `--target x86_64-windows-gnu` 产出的东西体积差 16.7
-倍、依赖的 DLL 完全不同。
-
-这就是 `x86_64-windows-musl` 作为独立名字存在的理由。它与 `x86_64-windows-gnu`
-映射到**同一个 LLVM 三元组** —— LLVM 拼不出它 —— 所以两者在编译器那一侧无法区分,
-全部差别就在于用的是哪个 C 库。任何宿主都没有为它准备的载荷;它的系统只能来自依赖
-图,这正是 `toolchain list` 报的 `via dependency graph`。
-
-### 声明的环境能移动编译三元组,移动不了链接三元组(mcpp 2026.9.18+)
-
-`c-abi` 包的 `[c-abi]` 块([22 —— C 环境](22-target-side.md#c-abi-包陈述它呈现的-c-环境mcpp-2026918))
-可以改变一次**编译**收到的 `--target=`——图里的 C 库声明 `presents = "posix"` 时,
-`x86_64-windows-gnu` 按 `x86_64-pc-cygwin` 编译——而不改变本章讲的那个三元组。
-解析出的三元组(`mcpp toolchain list` 打印的拼法、输出目录名、`Target` 报告的
-标题行、**链接**行)照旧是图与工具链解析出的那个;被替换的只是编译命令自己的
-`--target=` 记号,因为环境身份宏与数据模型正是从这里来的。如果在
-`compile_commands.json` 里 grep `--target=` 找到一个本章列表里没有的拼法,看到的
-正是这件事——原因与触发条件见 docs/22。
-
-## 构建机是第三条轴
-
-上面两条轴 —— 用哪个编译器、C 库从哪来 —— 是工程做的选择。第三条不是:它是构建
-运行在哪台机器上。
-
-**这条轴是 mcpp 自己发布的那一组,而且是 (os, arch) 不是 os。**
-`release.yml` 发布四份宿主二进制:
-
-| 构建机 | 发布资产 | CI runner |
+| `x86_64-linux-musl` | openkal（openkal-linux，图） | musl（图） | libc++（图） |
+| `x86_64-windows-gnu` | openkal（openkal-windows，图） | musl（图） | libc++（图） |
+| `x86_64-windows-musl` | openkal（openkal-windows，图） | musl（图） | libc++（图） |
+
+**对照两张表里的 `x86_64-windows-gnu`。** payload 供给时它的 C 库是
+`gnu`—— 也就是 MinGW 的 CRT；图供给时是 `musl`。同一个目标字符串，两个
+不同的 C 库，而直到 2026.8.24.6，mcpp 都没有办法说清是哪一个：同一条
+`--target x86_64-windows-gnu` 产出的产物体积相差 16.7 倍，依赖的 DLL
+也完全不同。
+
+这正是 `x86_64-windows-musl` 作为独立名字存在的理由。它映射到与
+`x86_64-windows-gnu` **相同的 LLVM 三元组**——LLVM 拼不出它——因此两者
+在编译器眼里无法区分，全部的差别就在于用的是哪个 C 库。没有任何宿主
+为它准备了 payload；它的 system 只能来自依赖图，这正是 `toolchain list`
+所报告的 `via dependency graph`。
+
+### 声明的环境能移动编译期三元组，移动不了链接期的那一个（mcpp 2026.9.18+）
+
+一个 `c-abi` 包的 `[c-abi]` 块（[22 —— C 环境](22-target-side.md#c-abi-包陈述它呈现的-c-环境mcpp-2026918)）
+可以改变一次**编译**收到的 `--target=`——当图里的 C 库声明
+`presents = "posix"` 时，`x86_64-windows-gnu` 会按 `x86_64-pc-cygwin`
+编译——但不会改变本章其余部分所讲的那个三元组。解析出的三元组
+（`mcpp toolchain list` 打印的拼法、输出目录名、`Target` 报告的标题行、
+LINK 行）保持不变，仍是图与工具链解析出的那个；被替换的只是编译命令上
+编译器自己的 `--target=` 记号，因为声明的环境身份宏与数据模型正是从
+这里获得。如果有读者在 `compile_commands.json` 里 grep `--target=`，
+找到一个本章从未列出的拼法，看到的正是这件事——触发条件与原因见
+docs/22。
+
+## 构建机是第三根轴
+
+上面两根轴 —— 用哪个编译器、C 库从哪里来 —— 是工程做出的选择。第三根
+不是：它是构建实际运行的那台机器。
+
+**这根轴是 mcpp 自己发布的那一组目标，而且是 (os, arch)，不是 os。**
+`release.yml` 发布四份宿主二进制：
+
+| build host | release asset | CI runner |
 |---|---|---|
 | `linux-x86_64` | `mcpp-<v>-linux-x86_64.tar.gz` | `ubuntu-24.04` |
 | `linux-aarch64` | `mcpp-<v>-linux-aarch64.tar.gz` | `ubuntu-24.04-arm` |
 | `macos-arm64` | `mcpp-<v>-macosx-arm64.tar.gz` | `macos-14` |
 | `windows-x86_64` | `mcpp-<v>-windows-x86_64.zip` | `windows-2022` |
 
-**两台 Linux 不是同一台。** `x86_64-linux-gnu` 需要本机架构的 `xim:glibc` 与
-`xim:linux-headers` 载荷,而它们只为宿主自己的架构存在 —— 所以那一行从
-`linux-x86_64` 够得着,从 `linux-aarch64` 够不着;`aarch64-linux-gnu` 是镜像的
-情形,两台上都是 `planned`。把它们并成 `linux`,一台会把另一台的行覆盖掉。
+**两台 Linux 宿主不是同一台。** `x86_64-linux-gnu` 需要本机架构的
+`xim:glibc` 与 `xim:linux-headers` payload，而它们只为宿主自己的架构
+存在 —— 因此那一行从 `linux-x86_64` 够得着，从 `linux-aarch64` 却够不
+着；`aarch64-linux-gnu` 是镜像的情形，在两台上都是 `planned`。把它们
+合并成 `linux`，会让一台的行覆盖掉另一台的行。
 
-### 构建机与它服务的目标
+### 构建机与它们服务的目标
 
 | target | tier | pin | linux-x86_64 | linux-aarch64 | macos-arm64 | windows-x86_64 |
 |---|---|---|---|---|---|---|
@@ -474,166 +502,192 @@ CRT;图供给时是 `musl`。一个目标字符串,两个不同的 C 库 ——
 | `thumbv8m.main-none-eabihf` | preview | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
 | `armv7a-none-eabi` | verified | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
 | `armv7a-none-eabihf` | verified | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
-| `aarch64-linux-android` | verified | `android-ndk@30.0.16248370` | payload | payload | payload | — |
-| `x86_64-linux-android` | verified | `android-ndk@30.0.16248370` | payload | payload | payload | — |
+| `aarch64-linux-android` | verified | `android-ndk@30.0.16248370` | 载荷 | 载荷 | 载荷 | — |
+| `x86_64-linux-android` | verified | `android-ndk@30.0.16248370` | 载荷 | 载荷 | 载荷 | — |
 | `aarch64-ios` | preview | `llvm@22.1.8` | — | — | SDK | — |
 | `aarch64-ios-sim` | verified | `llvm@22.1.8` | — | — | SDK | — |
 | `x86_64-ios-sim` | preview | `llvm@22.1.8` | — | — | SDK | — |
-| `wasm32-emscripten` | verified | `emsdk@6.0.9` | payload | payload | payload | payload |
+| `wasm32-emscripten` | verified | `emsdk@6.0.9` | 载荷 | 载荷 | 载荷 | 载荷 |
 
-`载荷` 这里有工具链载荷产出它 · `图` 没有载荷,但依赖可以供给系统 ·
-`系统` 在机器上被找到,不是 mcpp 装的 · `SDK` 平台自己的 ·
-`—` 从这台宿主够不着 · `planned` 词表里有,还没有任何东西接线。
+`载荷` 这里有工具链 payload 产出它 · `图` 没有 payload，但依赖能供给
+system · `系统` 在机器上被找到，不是 mcpp 安装的 · `SDK` 平台自己的 ·
+`—` 从这台宿主够不着 · `planned` 词汇表里已登记，还没有任何东西接线。
 
-### 列背后的规则
+### 各列背后的规则
 
 | 目标类别 | 服务它的构建机 | 原因 |
 |---|---|---|
-| `*-linux-musl` | Linux(任意架构)、Windows(仅同架构) | musl 载荷是自足的 |
-| `*-linux-gnu` | Linux,且仅同架构 | 还要本机架构的 `xim:glibc` / `xim:linux-headers` |
-| `x86_64-windows-gnu` | Linux、Windows | 一个身份,只在分发层按宿主分岔 |
+| `*-linux-musl` | Linux（任意架构）、Windows（仅同架构） | musl 的 payload 是自包含的 |
+| `*-linux-gnu` | Linux，且仅同架构 | 还需要本机架构的 `xim:glibc` / `xim:linux-headers` |
+| `x86_64-windows-gnu` | Linux、Windows | 一个身份，只在分发层按宿主拆分 |
 | `x86_64-windows-msvc` | Windows | MSVC 是在机器上被找到的 |
-| `x86_64-windows-musl` | 载荷只在 Windows;走图则任意宿主 | 没有 gcc 发得出 PE+musl,而 LLVM 拼不出这个三元组 |
-| `aarch64-macos` | macOS | SDK 是那台机器的 |
-| `*-none-elf` | 每一台 | clang 与 lld 按构造就是交叉编译器 |
-| `wasm32-emscripten`、`*-linux-android` | 每个宿主 | SDK 自带 sysroot,且上游按宿主发布;一份归档服务每个 guest 架构 |
-
-**一个 `—` 讲的是载荷,不是可能性。** `host_can_serve` 回答的是「这里有没有
-载荷产出它」,而依赖图可以改为供给系统 —— 这就是 `x86_64-windows-musl` 在 Linux
-上显示 `via dependency graph`、并在那里产出真正的 PE32+ 的原因。
-
-**而两个 Android 行在 Windows 上的 `—` 是**索引**的答案,所以
-`mcpp toolchain list` 在那里仍然会显示它们。** Google 确实发布 Windows NDK,它也
-下载得到;它不包含的是 libc++ 的**模块面**(实测:没有 `std.cppm`、没有
-`std/*.inc`,而另两个宿主各有 110 个),所以 `xim:android-ndk` 不声明 windows 表 ——
-一条永远不能服务「模块优先」构建的条目比没有更坏。引擎不把这件事编进来:一个索引
-服务哪些宿主会在没有引擎发布的情况下变化,而把它写成这里的一个常量,正是 wasm 那
-一行自己的历史所展示的会变陈旧的东西。因此 Windows 用户会看到这一行、钉能解析,
-而 xim 在任何东西被下载之前以 `no payload for this platform` 拒绝,并点名那个包。
-
-**两个 Android 行都是 `verified`,而载具不同。** x86_64 的产物在平台自己的模拟器上
-执行。真机那一行的产物在 qemu-user 上、配系统镜像自带的 bionic 跑起来 —— 这是从一台
-x86_64 宿主行得通的路线,而平台模拟器会直接拒绝异构 guest
-(`QEMU2 emulator does not support arm64 CPU architecture`)。一个层级断言的是产物
-被构建**并运行**过,它不断言是哪个模拟器运行的。
-
-在这两行上,`kind = "app"` 链接成一个共享库而不是可执行文件
-(见[04 §2.2](04-mcpp-toml.md))——由 `application_form` 对 `env == "android"`
-给出这个形态,与 `is_android()` 用的是同一个判据。
-
-### 而 CI 把每一台都测了
-
-[`ci-target-matrix.yml`](../../.github/workflows/ci-target-matrix.yml) 在全部四台
-宿主上跑。每台扫描它列出的每一行两遍 —— 只有载荷,以及图里加上
-`openkal-musl` + `openkal-llvm-runtime` —— 与
-[`tests/matrix/expected.tsv`](../../tests/matrix/expected.tsv) 比对,键是
-`(mode, host, target, compiler)`。
-
-每台把什么解析成自己的目标,与它的名字给人的印象并不一致:
+| `x86_64-windows-musl` | payload 只在 Windows 上；图则任意宿主 | 没有 gcc 能发出 PE + musl，且 LLVM 拼不出这个三元组 |
+| `aarch64-macos` | macOS | SDK 是那台机器自己的 |
+| `*-none-elf` | 每一台宿主 | clang 与 lld 按构造就是交叉编译器 |
+| `wasm32-emscripten`、`*-linux-android` | 每一台宿主 | SDK 自带 sysroot，且上游按宿主分别发布；一份归档服务每个 guest 架构 |
+
+**一个 `—` 讲的是 payload，不是可能性。** `host_can_serve` 回答的是
+「这里有没有 payload 能产出它」，而依赖图可以改为供给 system —— 这正是
+`x86_64-windows-musl` 在 Linux 上显示 `via dependency graph`、并在那
+里产出一个真正的 PE32+ 的原因。
+
+**而两个 Android 行在 Windows 上的 `—`，是索引的答案，因此
+`mcpp toolchain list` 在那里仍会显示它们。** Google 确实发布了 Windows
+版的 NDK，也下载得到；它不包含的是 libc++ 的模块面（实测：没有
+`std.cppm`，也没有 `std/*.inc`，而另外两台宿主各有 110 个），因此
+`xim:android-ndk` 不声明 Windows 表 —— 一条永远无法服务「模块优先」
+构建的条目，比没有这条目更糟。引擎不把这件事编码进去：一个索引服务
+哪些宿主，会在没有引擎发布的情况下变化，而把它写成这里的一个常量，
+正是 wasm 那一行自己的历史所展示的、会变陈旧的东西。因此 Windows 用户
+会看到这一行、pin 也能解析，而 xim 在任何东西被下载之前，就以
+`no payload for this platform` 拒绝，并点名那个包。
+
+**两个 Android 行都是 `verified`，但用的是不同的载体。** x86_64 的产物
+在平台自己的模拟器上执行。真机那一行的产物在 qemu-user 上、配系统镜像
+自带的 bionic 运行 —— 这是从一台 x86_64 宿主能走通的路线，因为平台
+模拟器会直接拒绝异构 guest（`QEMU2 emulator does not support arm64 CPU
+architecture`）。一个档位断言的是产物**被构建并运行**过；它不断言是
+哪个模拟器运行的。
+
+在这两行上，`kind = "app"` 链接成一个共享库而不是可执行文件（见
+[04 §2.2](04-mcpp-toml.md)）——由 `application_form` 对
+`env == "android"` 给出这个形态，与 `is_android()` 所用的是同一个判据。
+
+### 而 CI 把每一个都测过
+
+[`ci-target-matrix.yml`](../../.github/workflows/ci-target-matrix.yml) 在
+全部四台宿主上运行。每一台把它列出的每一行都扫描两遍 —— 只有 payload
+一遍，图里加上 `openkal-musl` + `openkal-llvm-runtime` 再一遍 —— 并与
+[`tests/matrix/expected.tsv`](../../tests/matrix/expected.tsv) 比对，
+后者以 `(mode, host, target, compiler)` 为键。
+
+一台 runner 把什么解析成自己的目标，和它的名字给人的印象并不一致：
 
 | runner | 它解析出的宿主目标 |
 |---|---|
 | `ubuntu-24.04` | `x86_64-unknown-linux-gnu` |
 | `ubuntu-24.04-arm` | `aarch64-unknown-linux-gnu` |
-| `macos-14` | `arm64-apple-darwin23.6.0` —— **ARM**,不是 x86_64 |
-| `windows-2022` | `x86_64-pc-windows-msvc` —— **msvc**,而那里的 mingw gcc 目标是 `-gnu` |
+| `macos-14` | `arm64-apple-darwin23.6.0` —— **ARM**，不是 x86_64 |
+| `windows-2022` | `x86_64-pc-windows-msvc` —— **msvc**，而那里的 mingw gcc 目标是 `-gnu` |
 
-本章三条判据都曾假设了 Linux 上的那个巧合,并在其它宿主上被纠正。
+本章有三条判据都曾假设了这个只在 Linux 上成立的巧合，因而必须在其他
+宿主上被纠正。
 
-**每台的格数不是常数。** 它取决于那台机器装了什么,而同一台 runner 在相邻两轮
-里被测到工具链不同。所以比对断言的是**扫描真的产出了行**、以及**期望表点名的每一
-行都被跑到**,而不是一个总数:一格因为载荷没被恢复而消失,与一格通过了,在退出码
-上没有区别。
+**每台宿主的格数不是一个常数。** 它取决于那台机器装了什么，而同一台
+runner 在相邻两次运行中曾被测到装有不同的工具链。因此比对断言的是
+**扫描确实产出了行**，以及**期望表点名的每一行都被跑到过**，而不是一个
+总数：一格因为 payload 没被恢复而消失，和一格通过了，二者的读数无从
+区分。
 
 ## mcpp 定义的宏
 
-`src/toolchain/predefines.cppm` 同时是这张表的规范与实现:契约是那个模块里的数据,
-发出是它旁边的函数,而 `tests/unit/test_predefines.cpp` 双向断言两者一致。发出去却不在
-表里、或在表里却没人发,都会让构建变红,而不是漂进一次发布。
+`src/toolchain/predefines.cppm` 同时是这张表的规范与实现：契约是那个
+模块里的数据，发出宏的是它旁边的一个函数，而
+`tests/unit/test_predefines.cpp` 双向断言两者一致。一个被发出却不在
+表里的宏，或者一个在表里却从未被发出的宏，都会让构建失败，而不是漂移
+进一次发布。
 
 | 宏 | 何时定义 | 是否 mcpp 拥有 |
 |---|---|---|
-| `__MCPP_TARGET_<OS>__` | 每次构建一个,拼法取自三元组的 `os` 字段 | 是 |
+| `__MCPP_TARGET_<OS>__` | 每次构建一个，拼法取自三元组的 `os` 字段 | 是 |
 | `__OPENKAL__` | 解析出的 `kernel-abi` 层接口名是 `openkal` | 是 |
-| `__unix__` | `[c-abi]` 实现供给它,在工具链不会定义它的地方 | 否 |
-
-**引擎原则上不该定义任何宏,每一行都要为自己辩护。** 包在清单里陈述需要什么,引擎以
-**解析**回答——`cfg(os = "windows")`、`cfg(c-abi = "musl")`、能力、feature。那条路可测、
-可报告、读清单就能看见;宏三样都不是。只有两条理由通过了:
-
-1. **源码不归我们改**,而它在预处理期发问。上游 C 用 `#if` 选平台行为,任何清单键都伸不进
-   第三方的 `.c` 里。
-2. **读者是已安装的头。** 包自己的构建 define 可以写在清单里,但它**安装出去**的头会被
-   **应用程序自己的编译**读到,那些 define 永远到不了那里。
-
-**`__MCPP_TARGET_<OS>__` 的规则。** 为每一个目标侧翻译单元定义,总是定义,每次构建一个。
-拼法取自三元组自己的 `os` 字段并转为大写:`x86_64-linux-gnu` 给出
-`__MCPP_TARGET_LINUX__`,`x86_64-windows-gnu` 给出 `__MCPP_TARGET_WINDOWS__`,
-`riscv64-none-elf` 给出 `__MCPP_TARGET_NONE__`。引擎不认识任何操作系统名:三元组解析器新增
-一个目标,它的宏随之存在,引擎无需改动。
-
-*允许:* 当上面呈现的 C 环境压掉了平台自己的宏时,用它得知目标的操作系统;以及按目标的
-ABI 给记录定尺寸。呈现 POSIX 的 Windows 目标**有意**没有 `_WIN32`,而调用约定仍是 Win64
-——那正是 `openkal-musl` 的 `bits/setjmp.h` 与 `openkal-llvm-runtime` 的
+| `__unix__` | `[c-abi]` 的实现在工具链不会定义它的地方供给它 | 否 |
+
+**引擎不应该定义宏，而每一行都必须证明自己是正当的。** 包在它的
+manifest 里陈述需要什么，引擎以**解析**作答 —— `cfg(os = "windows")`、
+`cfg(c-abi = "musl")`、一项能力、一个 feature。那条路径可测试、可报告、
+读一遍 manifest 就能看见；宏三样都不是。目前有两条理由站住了脚：
+
+1. **源码不归我们编辑**，而它在预处理期发问。上游 C 用 `#if` 选择平台
+   行为，没有任何 manifest 键能伸进第三方的 `.c` 里。
+2. **读者是一份已安装的头文件。** 包自己的构建 define 可以写在它的
+   manifest 里，但它**安装出去**的头文件，会被应用程序自己的编译读到，
+   那些 define 永远够不到那里。
+
+**`__MCPP_TARGET_<OS>__`——它的规则。** 为每一个目标侧的翻译单元定义，
+始终如此，每次构建一个。拼法取自三元组自己的 `os` 字段并转为大写：
+`x86_64-linux-gnu` 给出 `__MCPP_TARGET_LINUX__`，`x86_64-windows-gnu`
+给出 `__MCPP_TARGET_WINDOWS__`，`riscv64-none-elf` 给出
+`__MCPP_TARGET_NONE__`。引擎不学习任何操作系统的名字：三元组解析器
+新增一个目标，它对应的宏就随之存在，引擎不需要任何改动。
+
+*允许：* 在上层呈现的 C 环境已经压掉平台自己的宏时，用它得知目标的
+操作系统；以及按目标的 ABI 为一份记录定尺寸。一个呈现 POSIX 的
+Windows 目标有意没有 `_WIN32`——而调用约定仍然是 Win64，这正是
+`openkal-musl` 的 `bits/setjmp.h` 与 `openkal-llvm-runtime` 的
 `__libunwind_config.h` 各自据以定尺寸的事实。
 
-*禁止:* 选一个清单本可以选的头;或在本项目控制得了的包里用它代替 `cfg(os = …)`。
-
-**它总是被定义,不只在有东西被压掉时。** 条件式发出会让它的**缺席**含义不唯一:
-「不是 Windows」与「是 Windows,但没有东西压掉它的宏」会读成同一件事。一个缺席只有一种
-含义的宏,值一个 `-D`。
-
-**命名。** **全大写**、`__` 包裹、单词用 `_` 分隔;mcpp 拥有的名字带 `__MCPP_`。
-
-业界的约定是按**名字是什么**分的,不是按谁写的分。厂商名与产品名用大写——`__APPLE__`、
-`_WIN32`、`__MINGW32__`、`__GNUC__`;系统种类名用小写——`__linux__`、`__unix__`、
-`__gnu_linux__`。mcpp **拥有**的每一行都属于第一类:它命名的是 mcpp,或者是 openkal。
-「是哪一种系统」这个问题由 `__linux__` 那一族回答,而那一族是 mcpp **供给**而非拥有的,
-正因如此它们保持小写拼法。
-
-小写拼法先发布过,而产生它的那段推理值得留着,因为这个错很容易再犯一次:这些名字在真实
-守卫里与 `__linux__` 并排出现,于是「跟它一致」看起来就像一致性。**那是把「相邻」当成了
-「同类」。** `__APPLE__` 出现在同样那些守卫里,却是大写,因为它属于某个人——那些守卫里
-凡是属于某个人的名字都是大写。
-
-`__MCPP_` 这个前缀是承重的,但它是**前缀**而不是规则的全部:**一个 mcpp 拥有的名字,语义
-由 mcpp 自己定**,而 `__OPENKAL__` 同样是拥有的,它命名的是 *openkal* 而不是 mcpp。另一条
-路——**借用**——试过:`__CYGWIN__` 曾被保留定义,为的是让需要「PE 目标文件格式 + POSIX C
-环境」的代码有个名字,而 30 成员测量发现有成员把它读成「**Win32 可用**」并走向
-`#include <windows.h>`——那正是上游用它表达的意思。**一个借来的名字,语义由借出方的历史
-决定**,不由借用方的意图决定。
-
-**那个数目写的是四,实际是二**(2026-09-21 按撤销该名字那一版的重测更正)。`archive`
-(经由 xz)与 `sqlite3` 确实读它,两个都清了。另外两个是被归进来的——四个都停在
-`windows.h`——而它们的守卫并不相同:`c-ares` 走的是 `#ifdef HAVE_WINDOWS_H`,那个宏由
-本生态自己的配方在 windows 分支里 `#define`;`mimalloc` 已经不再走到任何头文件,它死在
-代码生成器里,用的那个 builtin 在替身三元组的 OS 上 LLVM 没有实现。**按诊断分组不是按
-真因分组**,这样数出来的数目会高估一次撤销能修掉多少。
-
-`__unix__` 是印证这条规则的例外:mcpp **供给**它而不拥有它,所以它保持标准拼法,mcpp 也
-不得改变它的含义。读它就按在任何别的 POSIX 系统上那样读。
-
-**稳定性。** 这张表里的一条是**已发布的接口**,而撤销一条是**静默**的:一个 `#if` 选了
-另一条分支,照常编译,发生在没人看着的机器上。构建工具手里没有任何机制能让它变响——
-预处理器无法被告知「为一个它找不到的名字报错」。
-
-所以撤销从来不由**读**来决定,而由**一次枚举读者的测量**来决定,测量数出多少,就决定这次
-撤销要走几步。本项目做过的两次撤销都在记录里,而它们的结果不同:
-
-| 撤销的名字 | 数出的读者 | 步数 |
+*禁止：* 选择一个 manifest 本可以选择的头文件；或者在本项目控制得了的
+包里，用它代替 `cfg(os = …)`。
+
+**它总是被定义，不只是在某个东西被压掉的时候。** 条件式地发出会让它的
+**缺席**含义不唯一：「不是 Windows」与「是 Windows，只是没有东西压掉
+它的宏」会读成同一回事。一个缺席只对应一种含义的宏，才值得花一个
+`-D`。
+
+**命名。** 全大写，用 `__` 包裹，单词之间用 `_` 分隔；mcpp 拥有的名字
+带 `__MCPP_` 前缀。
+
+业界的约定按**一个名字是什么**划分，而不是按谁写它划分。厂商名或产品
+名是大写 —— `__APPLE__`、`_WIN32`、`__MINGW32__`、`__GNUC__`。系统种类
+名是小写 —— `__linux__`、`__unix__`、`__gnu_linux__`。mcpp **拥有**的
+每一行都属于第一类：它命名的是 mcpp，或者是 openkal。「是哪一种系统」
+这个问题由 `__linux__` 那一族回答，而那一族是 mcpp **供给**而非拥有的，
+因此保持小写拼法，理由正在于此。
+
+小写拼法先发布了出来，而产生它的那段推理值得留存，因为这个错误很容易
+再犯一次：这些名字在真实的守卫里与 `__linux__` 并排出现，因此「与它
+一致」看起来就像是一种一致性。**这是把「相邻」与「同类」混为一谈。**
+`__APPLE__` 也出现在那些同样的守卫里，却是大写，因为它属于某个人 ——
+守卫里凡是属于某个人的名字都是大写。
+
+`__MCPP_` 这个前缀是承重的，但它只是一个**前缀**，不是规则的全部：一个
+mcpp 拥有的名字，含义由 mcpp 自己规定，而 `__OPENKAL__` 同样是被拥有
+的，它命名的是 *openkal*，而不是 mcpp。另一条路 —— **借用** —— 曾经
+试过：`__CYGWIN__` 被保留了定义，为的是让需要「PE 目标文件格式、POSIX
+C 环境」的代码有一个名字可用，而一次覆盖 30 个成员的测量发现，有成员
+把它读成「Win32 可用」，并因此走向 `#include <windows.h>`——那正是
+上游赋予它的含义。**一个借来的名字，含义由出借方的历史决定**，而不是
+由借用方的意图决定。
+
+**那个数字曾经是四，实际是二**（2026-09-21 按撤回该名字那一版的重新
+测量更正）。`archive`（经由 xz）与 `sqlite3` 确实读它，两者都已清理。
+另外两个之所以被归进同一组，是因为四者都停在 `windows.h` 这一步，而它
+们的守卫并不相同：`c-ares` 经由 `#ifdef HAVE_WINDOWS_H` 到达那个
+头文件，而这个宏是本生态自己的配方在它的 Windows 分支里定义的；
+`mimalloc` 则根本不再到达任何头文件 —— 它死在代码生成器里，卡在一个
+LLVM 没有为替代三元组的 OS 实现的 builtin 上。**按诊断分组，不等于按
+真因分组**，这样统计出来的数字会高估一次撤回真正能修好多少。
+
+`__unix__` 是印证这条规则的例外：mcpp **供给**它而不拥有它，因此它
+保持标准拼法，mcpp 也无权改变它的含义。按在任何其他 POSIX 系统上同样
+的方式读它即可。
+
+**稳定性。** 这张表里的一条是**已发布的接口**，而撤回一条是**静默**
+的：一个 `#if` 会选中另一条分支并照常编译，发生在没有任何人盯着的
+机器上。构建工具手里没有任何机制能让这件事变响 —— 预处理器无法被
+告知「为一个它找不到的名字报错」。
+
+所以撤回从来不是由**阅读**来决定的，而是由**一次枚举读者的测量**来
+决定，测量的结果决定这次撤回要走几步。本项目做过的两次撤回都在记录
+上，而结果各不相同：
+
+| withdrawn | readers found | steps |
 |---|---|---|
-| `__CYGWIN__`(2026.9.21.1) | 四个第三方成员,外加本生态**安装出去**的两个头里的六处 | 三步:发布替代品、迁移消费者、最后停止定义 |
-| `__mcpp_target_<os>__`、`__openkal__`(2026.9.21.2) | 零——本生态任何仓库里没有一个源文件、没有一份清单读它们 | 一步 |
+| `__CYGWIN__`（2026.9.21.1） | 四个第三方成员，外加本生态安装出去的两份头文件里的六处 | 三步：发布替代品、迁移消费方、最后停止定义 |
+| `__mcpp_target_<os>__`、`__openkal__`（2026.9.21.2） | 零 —— 本生态任何仓库里都没有一个源文件、也没有一份 manifest 读它们 | 一步 |
 
-两次之间规则没变,变的是数目。第二行便宜是有原因的,而这个原因值得写出来:两个名字都是
-在这里发明的,所以不可能有上游代码握着它们;暴露窗口 `__openkal__` 是三天,目标宏是一个
-发布。**一次不由数目支撑的撤销,正是本项目已经犯错过一次的那种论证。**
+两次之间规则没有变，变的是数字。第二行之所以便宜，是有原因的，这个
+原因值得写出来：两个名字都是在这里发明的，所以不可能有任何上游代码
+握着它们；暴露的时间窗口，`__openkal__` 是三天，目标宏是一个发布
+周期。**一次不是由数字支撑的撤回论证**，正是本项目已经犯错过一次的
+那种论证。
 
 ## 自定义目标
 
+不在 mcpp 表内的三元组需要一个显式的 section，这也是一块板子声明
+「任何默认值都给不出的事实」的方式：
 
-不在 mcpp 表内的三元组需要一个显式段落,而这也是一块板子声明
-「任何默认值都给不出的事实」的方式:
 
 ```toml
 [target.riscv64-none-elf]
@@ -642,20 +696,21 @@ runner  = ["qemu-system-riscv64", "-machine", "virt", "-nographic",
            "-no-reboot", "-bios", "default", "-kernel"]
 ```
 
-`sysroot = ""` 选定零 libc 档:编译行上没有 C 库,链接上也没有。
-**缺席 `sysroot` 键是另一个答案** —— 它继承该目标行自己的默认值。
-见[第 13 章](40-baremetal.md)。
+`sysroot = ""` 选定零 libc 档位：编译行上没有 C 库，链接上也没有。
+**缺席的 `sysroot` 键是另一个答案**—— 它继承该目标行自己的默认值。见
+[第 13 章](40-baremetal.md)。
 
 ## 参考
 
-[第 14 章](22-target-side.md)讲五层以及每一层由谁供给。
+[第 14 章](22-target-side.md)讲五层，以及每一层由谁供给。
 [第 15 章](24-openkal-cross.md)完整讲构建期体系。
-[第 03 章](20-toolchains.md)讲工具链轴,它是分开的:目标不决定编译器。
+[第 03 章](20-toolchains.md)讲工具链这根轴，它是分开的：目标不决定
+编译器。
 
 ## 当前边界
 
-- 处于 `planned` 档位的行,含义是**词汇表里已登记,而还没有任何东西接线**。点名这样
-  的目标会被解析器接受、被构建拒绝。
-- `host_can_serve` 判断的是「这台机器能不能产出这个目标」,与档位是两个不同的问题。
-  mcpp 支持的目标仍可能从这台宿主够不着;出口是显式的
-  `[target.X] toolchain = "…"`。
+- 处于 `planned` 档位的行，含义是**词汇表里已登记，还没有任何东西
+  接线**。点名这样一个目标会被解析器接受、被构建拒绝。
+- `host_can_serve` 判断的是「这台机器能不能产出这个目标」，这与档位
+  是两个不同的问题。mcpp 支持的目标仍可能从这台宿主够不着；出口是
+  显式的 `[target.X] toolchain = "…"`。
diff --git a/docs/zh/22-target-side.md b/docs/zh/22-target-side.md
index de8345665..8fd76a1b3 100644
--- a/docs/zh/22-target-side.md
+++ b/docs/zh/22-target-side.md
@@ -1,19 +1,19 @@
 # 22 —— 目标侧
 
-**读者:**要用同一份 manifest 服务多个目标的作者。
+**读者：** 要用同一份 manifest 服务多个目标的作者。
 
-**本章回答的那一个问题:**manifest 怎样说「只在那里」,以及哪些东西可以这样被
+**本章回答的那一个问题：** manifest 怎样说「只在那里」，以及哪些东西可以这样被
 条件化。
 
-**不在这里:**目标名的词汇表,那是 [21 —— 目标三元组](21-the-target-triple.md);
-以及加速器这条轴 —— 它在图之后才解析,属于
+**不在这里：** 目标名的词汇表，见 [21 —— 目标三元组](21-the-target-triple.md)；
+加速器这条轴在图之后才解析，属于
 [42 —— 异构硬件构建](42-heterogeneous-builds.md)。
 
-一次构建在发出任何命令行之前必须回答一个问题:目标的编译器运行时、平台接口、
-C 库与 C++ 运行时从哪里来。mcpp 在依赖图解析完成之后解析该问题一次,
-其后的每一个阶段读取同一个结果。
+一次构建在发出任何命令行之前，必须先回答一个问题：目标的编译器运行时、
+平台接口、C 库与 C++ 运行时各自来自哪里。mcpp 在依赖图解析完成之后解析该问题
+一次，其后的每一个阶段读取同一个已解析的值。
 
-本文规定该模型、约束它的规则、工程需要书写的内容,以及包需要声明的内容。
+本文规定这一模型、约束它的规则、工程需要书写的内容，以及包需要声明的内容。
 
 ## 五个层
 
@@ -22,24 +22,25 @@ C 库与 C++ 运行时从哪里来。mcpp 在依赖图解析完成之后解析
 | 层 | 内容 | 实现举例 |
 |---|---|---|
 | `compiler` | 执行编译的程序 | `llvm`、`gcc`、`msvc` |
-| `compiler-runtime` | 编译器自身的运行时:整数与浮点 builtins、展开器 | `compiler-rt` 与 `libunwind`、`libgcc` |
+| `compiler-runtime` | 编译器自身的运行时：整数与浮点 builtins、展开器 | `compiler-rt` 与 `libunwind`、`libgcc` |
 | `kernel-abi` | 平台接口或其等价物 | `linux`、`windows`、`darwin`、`openkal` |
 | `c-abi` | C 库 | `glibc`、`musl`、`picolibc`、`ucrt`、`libSystem` |
 | `c++-abi` | C++ 库及其 ABI 运行时 | `libc++` 与 `libc++abi`、`libstdc++`、MSVC STL |
 
 ### 成为层的判据
 
-一个部件成为层,当三个条件同时成立:野外至少存在两个可互换的实现;
-它可以独立于相邻层被替换;它与其下方的层之间存在确定的「曾为谁配置」关系。
-三者缺一,该部件属于相邻的层而非独立的一层。
+一个部件成为层，需要三个条件同时成立：至少存在两个可互换的实现；它可以独立于
+相邻层被替换；它与其下方的层之间存在一种确定的「曾为谁配置」关系。三者缺一，
+该部件就属于相邻的层，而不是独立的一层。
 
-`compiler-runtime` 独立于 `c++-abi`,因为 builtins 是一个 C 程序所需要的东西。
-把它算作 C++ 运行时的一部分,等价于断言 C 程序不需要整数除法,
-而该断言已经产生过一次实测缺陷:一个交叉到 macOS 的 C 程序被询问是否存在
-C++ 运行时,回答不存在,链接行因而保留了编译器载荷自带的 `libc++`。
+`compiler-runtime` 独立于 `c++-abi`，因为 builtins 是一个 C 程序本身需要的东西。
+把它算作 C++ 运行时的一部分，等于断言 C 程序不需要整数除法，而这一断言已经
+产生过一次实测缺陷：一个交叉编译到 macOS 的 C 程序被问及是否存在 C++ 运行时，
+答案是不存在，链接行因而保留了编译器载荷自带的 `libc++`。
 
-`kernel-abi` 在传统栈上没有名字 —— 在那里,C 库直接发出系统调用或直接调用
-平台入口。命名该接缝,是一份 C 库实现能够坐落在多个平台之上的前提。
+`kernel-abi` 在传统技术栈上没有名字——在那里，C 库直接发出系统调用，
+或直接调用平台入口。给这条接缝命名，正是一份 C 库实现得以坐落在多个平台之上
+的前提。
 
 ## 四种来源
 
@@ -50,37 +51,38 @@ C++ 运行时,回答不存在,链接行因而保留了编译器载荷自带的 `
 | `payload` | 编译器载荷自带 | 依赖解析之前 |
 | `prebuilt` | 一份被点名的预制载荷供给 | 依赖解析之前 |
 | `graph` | 依赖图中的包供给 | 依赖解析之后 |
-| `—` | 无人供给,且这是一个陈述 | — |
+| `—` | 无人供给，且这是一句陈述 | — |
 
-四种来源中两种在依赖解析之前可知、两种在其之后才可知。因此目标侧只在图存在的
-那一点解析一次。更早的任何推断都是对一个尚不存在的事实作推断,
-而对该事实的多处独立推断不会一致。
+四种来源中，两种在依赖解析之前可知，两种只在其后可知。因此目标侧只在图存在的
+那一刻解析一次。更早的任何推断，都是对一个尚不存在的事实所作的推断，而对同一
+事实的多处独立推断不会互相一致。
 
-缺席的层是答案而非缺口。裸机目标没有内核;不依赖任何 C 库的工程没有 C 库。
+缺席的层是一个答案，不是一处缺口。裸机目标没有内核；不依赖任何 C 库的工程
+没有 C 库。
 
 ## 三条规则
 
 ### 每层恰好一个供给者
 
-C 库、平台接口与 C++ 运行时是互斥的选择,而非可叠加的贡献。
-同一层出现两个供给者是错误,在解析期报出,并同时指出两个包及各自进入图的路径。
+C 库、平台接口与 C++ 运行时是互斥的选择，不是可叠加的贡献。同一层出现两个
+供给者是错误，在解析期报出，并同时指出这两个包，以及各自进入图的路径。
 
-严格性的依据是失败模态:选错供给者不会使链接失败,
-它产出一个能够运行且间歇性不能运行的程序。
+严格性的依据是失败的模式：选错供给者不会使链接失败，它产出的是一个能够运行、
+却间歇性不能运行的程序。
 
 ### 为其下方的层配置过
 
-一个实现只有在它曾被配置的层之上才可用。一份 `libc++` 构建把该配置记录在
-自己的 `__config_site` 中;一份 `libgcc` 构建是为 GCC 配置的。
-该关系由声明得来而非由推断得来 —— 见下文 [`requires`](#requires)。
+一个实现只有在它曾被配置的那个层之上才可用。一份 `libc++` 构建把这项配置
+记录在自己的 `__config_site` 中；一份 `libgcc` 构建是为 GCC 配置的。这一关系
+由声明得出，而非由推断得出——见下文的 [`requires`](#requires)。
 
-由此得出两条推论。编译器载荷的 C++ 运行时,仅在 C 库同样来自该载荷时可用。
-编译器运行时必须属于编译器自身的族,因为二者不一致的构建解析 `__udivti3`
-的方式,将与同一程序中其它每一次链接不同。
+由此得出两条推论。编译器载荷的 C++ 运行时，只有在 C 库同样来自该载荷时才可用。
+编译器运行时必须属于编译器自身所在的族，因为如果两者不一致，这次构建解析
+`__udivti3` 的方式，会与同一程序中其它每一次链接不同。
 
 ### 跨来源接线
 
-引擎仅在两层来自不同来源时为它们接线。
+引擎只在两层来自不同来源时才为它们接线。
 
 | 组合 | 关系的表达方 | 引擎 |
 |---|---|---|
@@ -88,47 +90,46 @@ C 库、平台接口与 C++ 运行时是互斥的选择,而非可叠加的贡献
 | 两层均来自 `payload` | 载荷自身一致 | 不介入 |
 | 一层预制、一层来自图 | 只有引擎同时知道两边的地址 | 需要接线 |
 
-因此把一层从预制载荷移入依赖图,减少而非增加引擎的工作。
-这是一份源码在引擎不作改动的情况下到达多个平台的机制依据。
+因此，把一层从预制载荷移入依赖图，减少的是引擎的工作，而不是增加。这正是
+一份源码能够在引擎不作任何改动的情况下到达多个平台的机制所在。
 
-### 层名固定,实现不固定
+### 层名固定，实现不固定
 
-五个层名是编译进引擎的闭集。填充它们的实现出现在包清单与索引中,
+五个层名是编译进引擎的一个闭集。填充它们的具体实现出现在包清单与索引中，
 不出现在引擎的任何一行代码中。
 
-层名可以固定,因为层由 C 与 C++ 的构建模型决定且不增长。
-实现不可以,因为增长正是它们所做的事:一个生态的组合数是其实现数之积,
-而包数是其和。
+层名可以固定，因为层由 C 与 C++ 的构建模型决定，并不增长。实现不能固定，
+因为增长正是实现要做的事：一个生态的组合数是其实现数之积，而包数只是其和。
 
 ## 工程书写的内容
 
-层名不出现在工程清单中。工程通过三个既有机制表达它的目标侧。
+层名不出现在工程清单中。工程通过三个既有机制来表达自己的目标侧。
 
 ### 目标三元组
 
-`--target <三元组>`,或 `[build] target`。OS 段选择平台接口。
-env 段陈述一条对 C 库的请求;它是请求而非答案,解析出的值由构建报告。
+`--target <三元组>`，或 `[build] target`。OS 段选择平台接口；env 段陈述的是
+对 C 库的一条请求——它是请求而非答案，解析出的值由构建自行报告。
 
-省略该段即为不陈述:`x86_64-linux` 请求「供给该层的任何实现」,
-`x86_64-linux-musl` 请求 musl。依赖图供给了另一个时以图为准,
-构建会报出该名字不准确并给出应当使用的拼写。该请求是被忽略而非被违反,
-因此产物两种写法下相同。
+省略该段即为不作陈述：`x86_64-linux` 请求「供给该层的任何实现」，
+`x86_64-linux-musl` 请求 musl。依赖图供给了另一个实现时，以图为准，构建会
+报出该名字不准确，并给出应当使用的拼写。这条请求是被忽略，而不是被违反，
+因此两种写法下产物相同。
 
 ### 工具链
 
-`mcpp toolchain default <族>@<版本>`、清单中的 `[toolchain]`,
-或针对单一目标的 `[target.<三元组>].toolchain`。它选择 `compiler` 层 ——
-唯一一个任何包都不能供给的层。
+`mcpp toolchain default <族>@<版本>`、清单中的 `[toolchain]`，或针对单一目标的
+`[target.<三元组>].toolchain`。它选择 `compiler` 层——五个层中唯一一个任何包都
+不能供给的层。
 
-目标表的行可以携带一条约定,即其载荷供给该目标 C 库的工具链。
-该约定在两个条件同时成立时生效:清单对该目标未作陈述,**且**依赖图中没有任何
-东西供给该目标的系统。第二个条件只有在解析之后才可知,
-因此工具链在那之后解析,而不在那之前。
+目标表的一行可以携带一条约定：其载荷供给该目标的 C 库的工具链。这条约定在
+两个条件同时成立时生效：清单对该目标未作陈述，**且**依赖图中没有任何东西
+供给该目标的系统。第二个条件只有在解析之后才可知，因此工具链在那之后解析，
+而不在那之前。
 
 ### 依赖
 
-其余每一层均通过依赖一个供给它的包来选择。一条依赖可以供给多个层,
-也可以通过它自身的依赖带来更多供给者。
+其余每一层都通过依赖一个供给它的包来选择。一条依赖可以供给多个层，也可以
+通过它自身的依赖带来更多供给者。
 
 ```toml
 [dependencies]
@@ -137,11 +138,11 @@ openkal-llvm-runtime = "0.1"
 
 ## 构建报告的内容
 
-构建打印它解析出的结果。清单中的一行陈述一个意图,该意图在其下方的包发生变化
-时过期;报告陈述结果,因而不会过期。
+构建打印它解析出的结果。清单中的一行陈述的是一个意图，该意图会在其下方的包
+发生变化时过期；报告陈述的是结果，因而不会过期。
 
-默认情况下报告只列出编译器载荷未供给的层。零配置构建的五个层全部解析自同一份
-载荷,五行 `(payload)` 回答的是无人提出的问题。
+默认情况下，报告只列出编译器载荷未供给的那些层。一次零配置构建的五层全部
+解析自同一份载荷，五行 `(payload)` 回答的是一个没有人提出的问题。
 
 ```
       Target x86_64-linux-gnu
@@ -154,27 +155,28 @@ openkal-llvm-runtime = "0.1"
              c++-abi           libc++         (openkal-llvm-runtime@0.1.1, graph)
 ```
 
-`MCPP_VERBOSE=1` 列出全部五层。诊断始终列出该判断所依据的每一层,
-包含其中平凡的部分,因为省略证据的错误信息无法被其读者复核。
+`MCPP_VERBOSE=1` 列出全部五层。诊断信息始终列出该判断所依据的每一层，
+包括其中平凡的部分，因为一条省略了自身证据的错误信息，读者无法核实。
 
-接口与实现是两列。`openkal` 是接口,`openkal-windows` 是它的一个实现;
-合并二者会掩盖一份源码为何能够到达多台机器。
+接口与实现是两列分开写的。`openkal` 是一个接口，`openkal-windows` 是它的一个
+实现；把二者合并会掩盖一份源码为何能够到达多台机器。
 
 ## 闭包可见性
 
-上面五层的报告回答的是「每一层来自哪里」,不回答图中「还有哪些别的包」——一个绑定到某个
-平台 SDK 的依赖,对这份报告而言和普通依赖一样不可见。两种手段补上这个缺口
-(设计 2026-09-18 §6)。
+上面这份五层报告回答的是「每一层来自哪里」，不回答图中「还有哪些别的包」——
+一个绑定到某个平台 SDK 的依赖，对这份报告而言和普通依赖一样不可见。两种手段
+补上这个缺口（设计 2026-09-18 §6）。
 
-**什么算平台依赖,精确定义。** 一个包带来平台依赖,当且仅当它自己这样说——
-`provides = ["platform-sdk"]`,一个普通的、不带命名空间前缀的能力。这里的一切都不是从
-头文件路径、链接 flag 或某个依赖的 `visibility` 推断出来的:推断会带来与保留前缀
-`mcpp:` 为五层所要避免的完全同一种「拼错即静默失效」的失败模式,只是用在了这个引擎本来
-就无法直接观测的事实上。[06 —— 让平台 SDK 依赖保持私有](06-features-and-capabilities.md#平台-sdk-依赖保持私有)
-是这样的包自己清单所遵循的模式。
+**什么算平台依赖，精确定义。** 一个包带来平台依赖，当且仅当它自己这样说——
+`provides = ["platform-sdk"]`，一个普通的、不带命名空间前缀的能力。这里的一切
+都不是从头文件路径、链接 flag 或某个依赖的 `visibility` 推断出来的：推断
+会带来与保留前缀 `mcpp:` 为五层所要避免的完全同一种「拼错即静默失效」的失败
+模式，只是这次用在了这个引擎本来就无法直接观测的事实上。
+[06 —— 平台 SDK 依赖保持私有](06-features-and-capabilities.md#平台-sdk-依赖保持私有)
+是这样的包自己的清单所遵循的模式。
 
-**报告。** 构建的 `Target` 报告新增一行,点名图中每一个声明了 `platform-sdk` 的包,
-没有则为空:
+**报告。** 构建的 `Target` 报告新增一行，点名图中每一个声明了 `platform-sdk`
+的包，没有则为空：
 
 ```
       Target              platform-deps     —
@@ -184,272 +186,314 @@ openkal-llvm-runtime = "0.1"
       Target              platform-deps     some.windows-headers@1.0.0
 ```
 
-按与五层相同的可见性规则打印:只在有内容可报告时打印,或在 `MCPP_VERBOSE` 下总是打印。
+按与五层相同的可见性规则打印：只在有内容可报告时打印，或在 `MCPP_VERBOSE`
+下总是打印。
 
-**拒绝开关。** `[build] platform-dependencies = "refuse"` 在图中存在这样的包时直接让
-构建失败——这是「本次构建完全是基于其 kernel-abi 实现的闭包,不多不少」这句话的机器
-可核验形式:
+**拒绝开关。** `[build] platform-dependencies = "refuse"` 在图中存在这样的包
+时直接让构建失败——这是「本次构建完全是基于其 kernel-abi 实现的闭包，
+不多不少」这句话的机器可核验形式：
 
 ```toml
 [build]
 platform-dependencies = "refuse"
 ```
 
-唯一接受的取值是 `"refuse"`;不写(默认)则允许平台依赖,即今天的行为。
+唯一接受的取值是 `"refuse"`；不写（默认）则允许平台依赖，即今天的行为。
 
 ## 包声明的内容
 
 ### provides
 
-供给某一层的包在保留前缀 `mcpp:` 下声明它。
+供给某一层的包，在保留前缀 `mcpp:` 之下声明这件事。
 
 ```toml
 provides = ["mcpp:compiler-runtime=compiler-rt", "mcpp:c++-abi=libc++"]
 ```
 
-语法为 `mcpp:<层>[=<实现>]`。层名对照闭集校验;拼写错误是错误,
-而非一个被静默禁用的行为。前缀之外的名字属于特性系统,原样透传。
+语法为 `mcpp:<层>[=<实现>]`。层名对照闭集校验；拼写错误是一个错误，而不是一种
+被静默禁用的行为。前缀之外的名字属于特性系统，原样透传。
 
-`mcpp:compiler` 可以被 require,不能被 provide。编译器是本引擎安装并驱动的
-载荷,而族与族之间的差异 —— flag 拼写、模块模型、BMI 格式、驱动配置文件 ——
-是引擎必须持有的事实,而非包能够描述的数据。
+`mcpp:compiler` 可以被 require，不能被 provide。编译器是这个引擎安装并驱动的
+一份载荷，而族与族之间的差异——flag 拼写、模块模型、BMI 格式、驱动配置文件——
+是引擎必须持有的事实，不是包能够描述的数据。
 
 ### requires
 
-`requires` 是对称的另一半,也是在引擎中不出现实现名的前提下执行分层规则的机制。
+`requires` 是对称的另一半，也是在引擎中不出现任何实现名的前提下，执行分层
+规则的机制。
 
 ```toml
 requires = ["mcpp:compiler=llvm"]
 ```
 
-由 `libc++` 源码构建的 C++ 运行时,其编译与其模块的编译均由 Clang 完成。
-该事实属于包。引擎检查一条它能够一般性地陈述的关系 ——
-被命名的层必须解析为被命名的实现 —— 并通过同时指出二者来报出不匹配;
-一张编译进引擎的族表,对于它从未听说过的族无法做到这一点。
+由 `libc++` 源码构建出的 C++ 运行时，其编译与其模块的编译都由 Clang 完成。
+这一事实属于该包。引擎检查一条它能够一般性地陈述的关系——被命名的层必须
+解析为被命名的实现——并通过同时指出二者来报出不匹配；一张编译进引擎的族表，
+对它从未听说过的族做不到这一点。
 
-该检查在编译开始之前运行。它所拒绝的组合,否则将在该运行时自身的头文件深处失败,
-其消息命名一个读者从未打开过的文件,以及一个 mcpp 从未作出的决定。
+这项检查在编译开始之前运行。它所拒绝的组合，若不加检查，会在该运行时自身的
+头文件深处失败，报错信息命名的是一个读者从未打开过的文件，以及一个 mcpp
+从未做出的决定。
 
-同一条声明也是「安装钩子从源码编译静态库」这类包的做法。这样的库针对某一个 C++ 标准库编译,无法链接进
-使用另一个标准库的程序;而它安装到的存储目录按包名与版本区分,并不区分这一选择。因此这类包声明它所针对
-的实现:
+同一条陈述也是这样一类包的做法：其安装钩子从源码编译出一个静态库。这样的库
+是针对某一个 C++ 标准库编译的，无法链接进使用另一个标准库的程序；而它安装到
+的那个存储目录只按包名与版本取键，并不区分这一选择。因此这类包声明它所针对的
+实现：
 
 ```toml
 requires = ["mcpp:c++-abi=libstdc++"]
 ```
 
-工具链解析出另一个 `c++-abi` 的工程随后会被拒绝,拒绝信息同时指出两个实现,而不是在链接时失败。这项检查
-在工具链解析之后进行,而工具链在依赖图安装之后才解析,因此检查时安装钩子已经运行过;钩子收到本次构建的
-目标,但收不到工具链的取值([32 —— 编写载荷](32-authoring-a-payload.md))。钩子不得把另一种变体构建进
-同一个存储目录,否则第一个消费者就会替之后所有消费者决定变体。
+工具链解析出另一个 `c++-abi` 的工程随后会被拒绝，拒绝信息同时指出两个实现，
+而不是在链接时才失败。这项检查在工具链解析之后进行，而工具链在依赖图安装之后
+才解析，因此检查发生时安装钩子已经运行过；钩子收到本次构建的目标，却收不到
+工具链的取值（见 [32 —— 编写载荷](32-authoring-a-payload.md)）。钩子不得把
+另一种变体构建进同一个存储目录，否则第一个消费者就会替之后所有消费者决定
+变体。
 
-### `c-abi` 包陈述它呈现的 C 环境(mcpp 2026.9.18+)
+### `c-abi` 包陈述它呈现的 C 环境（mcpp 2026.9.18+）
 
-传统技术栈不需要陈述这件事:编译器载荷的目标三元组已经蕴含了环境。一旦某个包取代载荷供给
-C 库,这一点就不再成立——openkal-musl 在 `x86_64-windows-gnu` 上生成 PE/Win64 代码,却向源码
-呈现 POSIX 环境,因为它是 musl 的移植版,它之上每一处 `#ifdef _WIN32` 问的都是错误的层。
-`[c-abi]` 块就是 C 库一次性陈述它到底呈现什么——且只有提供该层的包可以陈述。
+传统技术栈不需要陈述这件事：编译器载荷的目标三元组已经蕴含了 C 程序所编译
+针对的环境。一旦某个包取代载荷供给 C 库，这一点就不再成立——openkal-musl 在
+`x86_64-windows-gnu` 上生成 PE/Win64 代码，却向源码呈现 POSIX 环境，因为它是
+musl 的一个移植版，它之上每一处 `#ifdef _WIN32` 问的都是错误的那一层。
+`[c-abi]` 块是 C 库一次性陈述自己到底呈现了什么的方式——且只有供给该层的包
+才可以陈述它。
 
 ```toml
-# openkal-musl 的清单
+# openkal-musl's manifest
 [package]
 provides = ["mcpp:c-abi=musl"]
 
 [c-abi]
 presents   = "posix"        # posix | windows | none
-data-model = "arch-default" # arch-default | lp64 | llp64 | ilp32
-wchar      = 32              # 16 | 32
-builtins   = "iso"           # iso | platform(默认 platform)
+data-model = "arch-default"  # arch-default | lp64 | llp64 | ilp32
+wchar      = 32               # 16 | 32
+builtins   = "iso"            # iso | platform (default platform)
 ```
 
-**谁有资格声明。** 写了 `[c-abi]` 却没有在 `provides` 里列出 `mcpp:c-abi=<impl>` 的包,是在
-陈述一件自己不提供的层的事实——这总是错的,而不只是不寻常,因此在清单解析阶段即被拒绝,
-并指出缺失的 `provides` 条目。
+**谁有资格声明。** 写了 `[c-abi]`、却没有在 `provides` 里列出
+`mcpp:c-abi=<impl>` 的包，是在陈述一件自己并不供给的层的事实——这总是错的，
+而不只是不寻常，因此在清单解析阶段即被拒绝，并指出缺失的那条 `provides`
+条目。
 
-**四个键与各自的封闭取值集合。**
+**四个键，及各自封闭的取值集合。**
 
 | 键 | 取值 | 回答 |
 |---|---|---|
-| `presents` | `posix` / `windows` / `none` | 源码看到哪一族环境身份宏(`__unix__` 还是 `_WIN32` 还是都不定义) |
+| `presents` | `posix` / `windows` / `none` | 源码看到哪一族环境身份宏（`__unix__`、还是 `_WIN32`、还是都不定义） |
 | `data-model` | `arch-default` / `lp64` / `llp64` / `ilp32` | `long` 有多宽 |
 | `wchar` | `16` / `32` | `wchar_t` 有多宽 |
-| `builtins` | `iso` / `platform`(默认) | 编译器是否可以假定平台 C 库自己的扩展在场 |
-
-`presents`、`data-model`、`wchar` 没有默认值:块里漏写其中一个即被拒绝,并指出缺失的键——
-「没写」不等于三个封闭取值中的任何一个。只有 `builtins` 有默认值 `platform`,即今天的行为。
-未知的键或未知的取值永远是解析错误,并点名该键——绝不静默忽略。**不声明 `[c-abi]` 块的包
-不改变任何东西**:解析出的目标侧、每条编译命令、每个缓存键,都与这项能力出现之前逐字节相同。
-
-**`presents` 冻结在三个取值,而且它不回答任何关于能力的问题。** 它陈述的是源码看到哪些
-环境身份宏。它不陈述任何接口、任何头文件、任何路径是否可用;由它推断出这些的包,读到了
-一个它没有被给予的事实——Windows 目标上呈现 POSIX 的环境没有 `fork`、没有 `/proc`、
-没有 `epoll`,而它陈述这件事的方式是寻常的那一种:定义在链接期缺席。取值集不增长,理由
-与 openkal 规范为自己的核心集封闭所给的相同(SPEC 0.14 §3.2):一个描述环境**类别**的名字,
-会被没有人想到过的那个环境证伪,而 openkal 把自己发过的唯一一个这样的名字(`hosted`)
-在一个发布周期之内撤回了。在这里加第四个取值就是再造一次那个名字。一个包要知道某项能力
-在不在,答案在它最早存在的地方回答——依赖解析,由下文的接口枚举给出。
-
-三件事互不推导,这是刻意保持分开的:`presents` 决定源码走哪条分支,`data-model`/`wchar`
-决定 ABI。POSIX 不蕴含 LP64(32 位架构上是 ILP32),LP64 也不蕴含 POSIX。
-
-**实现(realisation)。** 一旦 `c-abi` 层解析到声明了这个块的包,mcpp 就把请求转换成编译器
-配置,作用于目标侧的每一个编译单元——C 库自己、C++ 运行时、编译器运行时的 builtins,以及
-图中所有普通包——覆盖 C、C++、汇编编译,依赖扫描,以及 `std` 模块预编译。汇编(`.S`/`.s`)要
-做到这一点需要自己单独的广播通道:`.S` 单元的命令行是独立组装的(`mcpp.build.flags::
-CompileFlags::as`,不是 `::cc`/`::cxx`),而且它有意只从包的 C 标志里取出 `-D`/`-U`/`-I`
-子集——对 C 编译器有意义的 `-std=` 或 `-O` 之类标志对 GAS 毫无意义——所以实现出来的环境
-令牌(`--target=`、`-f[no-]short-wchar`,以及 `builtins = "iso"` 添加的部分)要原样再广播
-一遍进这条更窄的通道(openkal-musl 尖峰实验发现并修好的缺口:同一个包里 `.c` 单元看到
-`_WIN32` 未定义,`.S` 单元却仍看到它已定义——真实代码,比如 `okm_setjmp.S` 与上游
-libunwind 的 `assembly.h`,正是按这个宏来选寄存器保存集的)。mcpp 保存的是一份
-「请求到三元组与开关」的映射表,是不含包名的通用知识:
+| `builtins` | `iso` / `platform`（默认） | 编译器是否可以假定平台 C 库自身的扩展在场 |
+
+`presents`、`data-model`、`wchar` 都没有默认值：块中漏写其中任何一个都会被
+拒绝，并指出缺失的键——「没写」不等同于三个封闭取值中的任何一个。只有
+`builtins` 有默认值 `platform`，即今天的行为。未知的键或未知的取值永远是
+解析错误，并点名该键——绝不静默忽略。**一个不声明 `[c-abi]` 块的包不改变
+任何东西**：解析出的目标侧、每一条编译命令、每一个缓存键，都与这项能力出现
+之前逐字节相同。
+
+**`presents` 冻结在三个取值，而且它不回答任何关于能力的问题。** 它陈述的是
+源码看到哪些环境身份宏，不陈述任何接口、任何头文件、任何路径是否可用；由它
+推断出这些内容的包，读到的是一个它没有被给予的事实——一个在 Windows 目标上
+呈现 POSIX 的环境没有 `fork`、没有 `/proc`、没有 `epoll`，它陈述这件事的方式
+是寻常的那一种：相应定义在链接期缺席。这个取值集不再增长，理由与 openkal
+自己给出的、为它的核心集封闭所给的理由相同（SPEC 0.14 §3.2）：一个描述环境
+**类别**的名字，会被没有人想到过的那个环境证伪，而 openkal 已经把自己发布过
+的唯一一个这样的名字（`hosted`）在一个发布周期之内撤回了。在这里再加第四个
+取值，就是再造一次那个名字。一个包要知道某项能力在不在，答案要在它最早存在
+的那个地方回答——依赖解析，由下文的接口枚举给出。
+
+三件事互不蕴含，这是刻意分开的：`presents` 决定源码走哪条分支，
+`data-model`/`wchar` 决定 ABI。POSIX 不蕴含 LP64（32 位架构上是 ILP32），
+LP64 也不蕴含 POSIX。
+
+**实现（realisation）。** 一旦 `c-abi` 层解析到声明了这个块的包，mcpp 就把
+这条请求转换成编译器配置，施加到目标侧的每一个编译单元——C 库自己、C++
+运行时、编译器运行时的 builtins，以及图中所有普通包——覆盖 C、C++、汇编
+编译，依赖扫描，以及 `std` 模块预编译。汇编（`.S`/`.s`）要做到这一点需要
+自己单独的一条广播通道：`.S` 单元的命令行是独立组装的
+（`mcpp.build.flags::CompileFlags::as`，不是 `::cc`/`::cxx`），而且它有意
+只从包的 C flags 里取出 `-D`/`-U`/`-I` 这一子集——对 C 编译器有意义的 `-std=`
+或 `-O` 之类 flag，对 GAS 毫无意义——所以实现出来的环境令牌（`--target=`、
+`-f[no-]short-wchar`，以及 `builtins = "iso"` 添加的部分）要原样再广播一次，
+进入这条更窄的通道（openkal-musl 尖峰实验发现并修好的缺口：同一个包里，`.c`
+单元看到 `_WIN32` 未定义，`.S` 单元却仍看到它已定义——真实代码，比如
+`okm_setjmp.S` 与上游 libunwind 的 `assembly.h`，正是按这个宏来挑选寄存器
+保存集的）。mcpp 保存的是一份「请求到三元组与开关」的映射表，是一份不含任何
+C 库名的通用知识：
 
 | 目标 | 请求 | 实现 |
 |---|---|---|
 | Linux | `posix` / `arch-default` | 默认三元组已经满足 |
-| macOS | `posix` / `arch-default` | 一个令牌,`-D__unix__`——Apple 的 clang 默认三元组预定义的是 `__APPLE__`/`__MACH__`,从来不是 `__unix__` |
-| 裸机(freestanding) | `posix` / `arch-default` | 同样一个令牌,`-D__unix__`,原因相同:这里同样没有任何东西定义它 |
-| Windows | `posix` / `arch-default` | 采用 Cygwin 式语义:仅在编译行加 `--target=x86_64-pc-cygwin`;并加 `-D__MCPP_TARGET_WINDOWS__`(见下方说明);`data-model` 变为 LP64 是三元组切换的结果,不是另一个开关 |
-| 任意目标 | `builtins = "iso"` | 关闭代码生成阶段假定平台 C 库在场的惯用法识别——Apple 目标上发 `-fno-builtin`,因为按函数名的那个拼法对唯一重要的那个惯用法实测是**静默空操作**(`memset_pattern16` 是 LLVM TargetLibraryInfo 的 libfunc,不是 clang 的 builtin);A/B 与实测代价见 `src/toolchain/cenv.cppm` |
-| 其余情况 | | 明确拒绝,点名目标、请求与缺什么——不静默降级 |
-
-**macOS 与裸机这两行是一次修正,不是设计原文(协调者修订,2026.9.18.1 发布不到一天就被真实
-构建抓到)。** 实现 `presents = "posix"` 遵循的规则是:在每一个目标上陈述的是同一件可观察的
-事实——`__unix__` 已定义,`_WIN32` 未定义——目标之间的差别只在于实现它要花多大代价。原文
-假设 macOS 的默认三元组已经像 Linux 一样呈现了它;真实构建上的校验探针把这个假设当场
-抓包为假——声明已定义,实测未定义——这正是那个探针存在的意义所在,不是它的漏洞。原文还
-把裸机目标对 `presents = "posix"` 的任何请求一律拒绝,这挡住了整整一个目标
-(`riscv64-none-elf`,openkal-llvm-runtime),而不是去实现这个引擎其实能给出的事实:裸机
-目标一开始两个宏都没有定义,和 macOS 默认三元组一模一样,所以这处修复付出的是同一个令牌
-的代价。已知的成本,留给 mcpp-index 30 个成员的实测去权衡:写成
-`#ifdef __unix__ ... #elif defined(__APPLE__)` 的可移植代码,现在在 macOS 上也会走 Unix
-分支,只有那条分支本身在 macOS 上也写对了才是对的。
+| macOS | `posix` / `arch-default` | 一个令牌，`-D__unix__`——Apple 的 clang 在默认三元组上预定义的是 `__APPLE__`/`__MACH__`，从来不是 `__unix__` |
+| freestanding（裸机） | `posix` / `arch-default` | 同样一个令牌，`-D__unix__`，理由相同：这里同样没有任何东西定义它 |
+| Windows | `posix` / `arch-default` | 采用 Cygwin 式语义：只在编译行加 `--target=x86_64-pc-cygwin`；再加 `-D__MCPP_TARGET_WINDOWS__`（见下方说明）；`data-model` 变为 LP64 是三元组切换的结果，不是另一个开关 |
+| 任意目标 | `builtins = "iso"` | 关闭代码生成阶段假定平台 C 库在场的惯用法识别——在 Apple 目标上发出 `-fno-builtin`，因为按函数名逐个开关的那种拼法，对唯一重要的那个惯用法实测是**静默空操作**（`memset_pattern16` 是 LLVM TargetLibraryInfo 的 libfunc，不是 clang 的 builtin）；A/B 对照与实测代价见 `src/toolchain/cenv.cppm` |
+| 其余情况 | | 明确拒绝，点名目标、请求与缺什么——绝不静默降级 |
+
+**macOS 与 freestanding 这两行是一次修正，不是设计原文（协调者修订，
+2026.9.18.1 发布不到一天就被真实构建抓到）。** 实现 `presents = "posix"`
+所遵循的规则是：在每一个目标上陈述的都是同一件可观察的事实——`__unix__` 已
+定义，`_WIN32` 未定义——目标之间的差别只在于实现它要花多大代价。原文假设
+macOS 的默认三元组已经像 Linux 一样呈现了它；真实构建上的校验探针把这个假设
+当场抓包为假——声明已定义，实测未定义——这正是那个探针存在的意义所在，
+不是它的漏洞。原文还把 freestanding 目标对 `presents = "posix"` 的任何请求
+一律拒绝，这挡住了整整一个目标（`riscv64-none-elf`，openkal-llvm-runtime），
+而不是去实现这个引擎确实能够给出的事实：freestanding 目标一开始两个宏都没有
+定义，和 macOS 默认三元组一模一样，所以这处修复付出的是同一个令牌的代价。
+已知的成本，留给 mcpp-index 三十个成员的实测去权衡：写成
+`#ifdef __unix__ ... #elif defined(__APPLE__)` 的可移植代码，现在在 macOS 上
+也会走 Unix 分支，只有那条分支本身在 macOS 上也写对了才是对的。
 
 **编译器只在实现真的需要一个它拿不出来的令牌时才被拒绝——不是仅仅因为声明了
-`[c-abi]`。** `cenv::realise`(上文)先跑,是声明与目标的纯函数;只有 Clang 才行的要求
-第二个才检查,且只在结果令牌非空时才触发。openkal-musl 自己在 Linux 上的声明——
-`presents = "posix", data-model = "arch-default", wchar = 32`——实现出来什么都没有(上表
-第一行),所以 GCC 在那里被接受,校验探针照常核实,和任何其他空实现一样。Windows 那一情形
-没有变:Cygwin 式替换是非空的,所以一个非 Clang 编译器在那里仍然被拒绝,并点名它做不到
-什么。
-
-Windows 一行是旗舰情形:`x86_64-w64-windows-gnu` 与 `x86_64-pc-cygwin` 生成的机器码完全一致——
-同样的 PE 格式、同样的 Win64 调用约定、同样的 SEH——差别只在预处理器看到什么、`long` 有多宽。
-因此实现只触及**编译**行;**链接**行保持图解析出的三元组,因为目标文件格式没有变化。
-
-**这里定义 `__MCPP_TARGET_WINDOWS__`,而 `__CYGWIN__` 仍然定义着(2026.9.21.1;这个名字在
-那一版是小写拼法,2026.9.21.2 在它还没有消费者时改成了大写)。**
-
-这次替换有意压掉 `_WIN32`——那正是「呈现 POSIX」的含义。但**ABI 并没有跟着环境一起变**:
-调用约定仍是 Win64,寄存器保存区仍按它的大小。生态里有两个**已安装的**头按这个事实定尺寸:
+`[c-abi]`。** `cenv::realise`（上文）先运行，是声明与目标的纯函数；只有
+Clang 才行的这条要求第二个才检查，且只在结果令牌非空时才触发。openkal-musl
+自己在 Linux 上的声明——`presents = "posix", data-model = "arch-default",
+wchar = 32`——实现出来的是空（上表第一行），所以 GCC 在那里被接受，
+校验探针照常核实，和任何其他空实现一样。Windows 那一情形没有变：Cygwin 式
+替换是非空的，所以一个非 Clang 编译器在那里仍然被拒绝，并被点名它做不到什么。
+
+Windows 那一行是旗舰情形：`x86_64-w64-windows-gnu` 与 `x86_64-pc-cygwin`
+产出的机器码完全一致——同样的 PE 格式、同样的 Win64 调用约定、同样的 SEH——
+差别只在预处理器看到什么，以及 `long` 有多宽。因此实现只触及**编译**行；
+**链接**行保持图解析出的那个三元组，因为目标文件格式没有变化。
+
+**`__MCPP_TARGET_WINDOWS__` 在这里定义，而 `__CYGWIN__` 仍然定义着
+（2026.9.21.1；这个名字在那一版是小写拼法，2026.9.21.2 在它还没有消费者时
+改成了这个拼法）。**
+
+这次替换有意压掉 `_WIN32`——那正是「呈现 POSIX」的含义。但**ABI 并没有跟着
+环境一起变**：调用约定仍是 Win64，寄存器保存区仍按它原来的大小。这个生态里
+有两个**已安装的**头按这一事实定尺寸：
 
 | 包 | 头文件 | 它定尺寸的记录 |
 |---|---|---|
 | openkal-musl | `port/include/bits/setjmp.h` | `jmp_buf` |
 | openkal-llvm-runtime | `__libunwind_config.h` | `unw_context_t`、`unw_cursor_t` |
 
-已安装的头会被**应用程序自己的编译**读到,所以两者都用不了包私有的 define。
-`__MCPP_TARGET_WINDOWS__` 是 mcpp 为它们所问的那个问题给出的**自己的**名字——这个目标是不是
-Windows,无论上面呈现的是什么 C 环境——既然是自己的名字,它的语义就不由别人的历史决定。
-它只在这次替换下发出;普通的 Windows 构建仍然有 `_WIN64`。
-
-**`__CYGWIN__` 仍然定义着,这是一个次序问题,不是决定留下它。** 30 成员测量已经判定这个
-借来的名字代价是四个成员:`archive`、`sqlite3`、`mimalloc`、`c-ares` 各自停在
-`#include <windows.h>`,经由 `#if defined(_WIN32) || defined(__CYGWIN__)` 到达。上游用它
-表达的是「**Win32 可用**」——mimalloc 把话写在守卫自己的注释里,sqlite3 把它列进
-`SQLITE_OS_WIN`。**一个借来的名字,语义由借出方的历史决定**,不由借用方的意图决定。
-
-撤掉它试过了,结果打断了上面那两个头——它们读它,正是因为没有别的 target-wide 名字可用。
-libunwind 的 `static_assert` 响亮地红了;`setjmp.h` 那一处不会——它自己的注释写着
-「a mismatch nothing reports until the record overruns」。所以撤销分三步,每个中间状态都能构建:
-
-1. 2026.9.21.1 **增加** `__MCPP_TARGET_WINDOWS__`——纯增量;
-2. 那两个包改读新名字,保留 `|| defined(__CYGWIN__)` 以便在两种引擎上都能构建;
-3. 之后的版本再停止定义借来的那个。
-
-先做第三步,会让**已发布**的那两个头全部落进各自的 `#else`:错误的记录尺寸,而没有任何
-东西报告。
-
-**`kernel-abi` 提供者的自身单元被推导落到平台边界上——它不必自己说出来**
-(mcpp 2026.9.18+,PR 进行中根据 openkal-musl 尖峰实验做的修订)。提供
-`mcpp:kernel-abi=<impl>` 的包(比如 openkal-windows)必须看到平台自身的
-环境——它要 include 平台声明,`_WIN32` 对它必须为真——而且永远如此,这是
-由定义决定的:这样的包的全部工作就是说平台自己的 ABI,所以它绝不可能是那个
-想要图里「呈现」的 `[c-abi]` 环境、而不是三元组自身环境的包。mcpp 不等着被
-告知这一点。任何 `provides` 里点名 `mcpp:kernel-abi=<impl>` 的包,默认就得到
-`c-environment = "platform"`,不需要自己声明:
+一个已安装的头会被**应用程序自己的编译**读到，所以两者都用不了包私有的
+define。`__MCPP_TARGET_WINDOWS__` 是 mcpp 为它们所问的那个问题给出的**自己
+的**名字——这个目标是不是 Windows，无论它之上呈现的是什么 C 环境——既然是
+自己的名字，它的语义就不由别人的历史决定。它只在这次替换下发出；一次普通的
+Windows 构建仍然有 `_WIN64`。
+
+**`__CYGWIN__` 仍然定义着，这是一个先后次序的结果，不是要留下它的决定。**
+三十成员测量已经判定，这个借来的名字的代价是若干成员：它们都停在
+`#include <windows.h>`，经由 `#if defined(_WIN32) || defined(__CYGWIN__)`
+到达。上游用它表达的意思是「Win32 可用」——sqlite3 把它列在
+`SQLITE_OS_WIN` 之下。**一个借来的名字，其含义由出借方的历史决定**，
+不由借用方的意图决定。
+
+**这个数字曾经是四，现在是二**（2026-09-21 更正）。`archive`（经由 xz）与
+`sqlite3` 读这个名字，都在撤回它的那次发布上被清理掉了。`c-ares` 与
+`mimalloc` 被归入同一组，是因为四者都停在 `#include <windows.h>`，而两者
+都不是这个名字造成的：`c-ares` 是经由 `#ifdef HAVE_WINDOWS_H` 到达那个头的，
+这个宏由 mcpp-index 自己的配方在它的 Windows 分支里定义；`mimalloc` 则根本
+不再到达任何头——它在代码生成器里失败，报错是「目标 OS 还不支持
+`__builtin_thread_pointer()`」，这是替代三元组本身的性质，而不是任何宏的
+性质。**按诊断信息分组，不等于按成因分组。**
+
+撤掉它试过了，结果打断了上面那两个头——它们读它，正是因为没有别的
+target-wide 名字可用。libunwind 的 `static_assert` 响亮地报了错；`setjmp.h`
+那一处不会——它自己的注释写着「不会有任何东西报告这处不一致，直到记录溢出
+为止」。所以撤销分三步，每个中间状态都能构建：
+
+1. 2026.9.21.1 **增加** `__MCPP_TARGET_WINDOWS__`——纯增量；
+2. 那两个包改读新名字，保留 `|| defined(__CYGWIN__)`，以便在两种引擎上都能
+   构建；
+3. 之后的版本再停止定义借来的那一个。
+
+先做第三步，会让**已发布**的那两个头全部落进各自的 `#else`：记录尺寸是错的，
+而没有任何东西报告这件事。
+
+**`kernel-abi` 提供者自身的单元被推导落到平台边界上——它不必自己说出来
+（mcpp 2026.9.18+，根据 openkal-musl 尖峰实验做的一次 PR 中期修订）。**
+供给 `mcpp:kernel-abi=<impl>` 的包（比如 openkal-windows）必须看到平台自身
+的环境——它要 include 平台声明，`_WIN32` 对它必须为真——而且永远如此，这是
+由定义决定的：这样的包的全部工作就是说出平台自己的 ABI，所以它绝不可能是
+那个想要图里所「呈现」的 `[c-abi]` 环境、而不是三元组自身环境的那一方。mcpp
+不等着被告知这一点。任何 `provides` 里点名了 `mcpp:kernel-abi=<impl>` 的包，
+默认就得到 `c-environment = "platform"`，不需要自己再声明一个键：
 
 ```toml
 [package]
 provides = ["mcpp:kernel-abi=openkal"]
-# 没有 [package] c-environment 这一行——边界是从 provides 推导出来的
-```
-
-**为什么要推导,而不只是提供这个开关。** 开关本身没问题;它做不到的是追溯性地
-修好一个已经发布、却没写这个开关的包。openkal-windows 0.8.0、openkal-macos
-0.10.0、openkal-linux 0.13.0,以及未来任何 kernel-abi 实现,都能因此把边界
-做对——不需要新发版本,也不需要跨仓库协调版本号——因为 `provides =
-["mcpp:kernel-abi=<impl>"]` 正是它们本就已经声明的那一个事实。这里堵住的
-失败是实测出来的,不是假设:openkal-windows 和图里其余部分一样,在 POSIX
-替换下编译,`-fno-short-wchar` 给了它 32 位的 `wchar_t`,而它调用的 Win32
-接口回传的却是真正的 16 位 UTF-16——于是一个 `wchar_t*` 循环把两个 UTF-16
-码元读成了一个码点。把这条边界变成默认值,而不是一个包必须记得去写的清单
-键,让这一类失败变得**无法被表达**,而不只是被记录在文档里。
-
-**优先级:包自己清单里显式写的 `c-environment` 永远赢过推导。**
-推导只在包什么都没写的时候才填 `cEnvironment`——如果一个包终究还是需要
-呈现的环境,它仍然可以显式这样声明(今天还没有办法反着写「不是
-platform」,因为 `"platform"` 仍是这个键唯一接受的取值)。这个显式键也仍然
-是 §5.3 另一类情形——不是 kernel-abi 边界、但自身确实有平台绑定单元的普通
-包——唯一的手段,那种情形下作者做出的确实是 mcpp 无法推导出来的选择:
+# no [package] c-environment line — the boundary is inferred from `provides`
+```
+
+**为什么要推导，而不只是提供这个开关。** 开关本身没有问题；它做不到的是
+追溯性地修好一个已经发布、却没写这个开关的包。openkal-windows 0.8.0、
+openkal-macos 0.10.0、openkal-linux 0.13.0，以及未来任何一个 kernel-abi 实现，
+都能因此把边界做对——不需要新发版本，也不需要跨仓库协调版本号——因为
+`provides = ["mcpp:kernel-abi=<impl>"]` 正是它们本就已经声明的那一个事实。
+这里堵住的失败是实测出来的，不是假设：openkal-windows 和图里其余部分一样在
+POSIX 替换下编译，`-fno-short-wchar` 给了它 32 位的 `wchar_t`，而它调用的
+Win32 接口回传的却是真正的 16 位 UTF-16——于是一个 `wchar_t*` 循环把两个
+UTF-16 码元读成了一个码点。把这条边界变成默认值，而不是一个包必须记得去写
+的清单键，让这一类失败变得**无法被表达**，而不只是被记录在文档里。
+
+**优先级：包自己清单里显式写的 `c-environment` 永远赢过推导。** 推导只在包
+什么都没写时才填 `cEnvironment`——如果一个包终究还是需要呈现的那个环境，
+它仍然可以显式这样声明（今天还没有办法反着写「不是 platform」，因为
+`"platform"` 仍是这个键唯一接受的取值）。这个显式键也仍然是 §5.3 另一类
+情形——不是 kernel-abi 边界、但自身确实有平台绑定单元的普通包——唯一的手段，
+那种情形下作者做出的确实是 mcpp 无法推导出来的选择：
 
 ```toml
 [package]
-# 一个普通包,不是 kernel-abi 提供者——这一个引擎推导不出来;作者要自己
-# 声明它,因为平台绑定单元只是这个包所构建内容里真正的少数(设计 §5.3)
+# an ORDINARY package, not a kernel-abi provider — the engine cannot infer
+# this one; the author states it because platform-bound units are a real
+# minority of what this package builds (design §5.3)
 c-environment = "platform"
 ```
 
-这是一条边界规则,由这一个开关记录下来,而不是引擎强制执行:这样的包对图其余部分暴露的
-接口仍然只能用定宽类型(SPEC §5.4)。
-
-**声明被校验,而不是被信任。** 声明要经过核对,绝不直接信任——这与 openkal 自己核对一致性声明
-的做法一致。目标侧解析出上述开关之后,mcpp 用它们编译一个纯预处理探针(`-E -dM`,把预定义宏
-全部打印出来——足够便宜,且不需要执行,这一点很重要,因为解析出的环境常常是交叉目标),读回
-`__SIZEOF_LONG__`、`__SIZEOF_WCHAR_T__` 以及哪些环境身份宏被定义,与声明核对。不符即失败,并
-同时打印声明值与实测值。结果按配置(编译器二进制身份 + 最终参数)缓存,同一配置解析两次只
-编译一次探针。
-
-**探针的命令行必须选中目标,而在 freestanding 上它一度没有(mcpp 2026.9.20.1)。**
-clang 是一个二进制,它能产出被编译进去的每一个目标,因此一条不点名目标的命令行回答的是
-它自己所在的那台机器。宿主交叉目标经 `--target=` 到达探针;freestanding 目标的目标选择
-与必须随行的 ISA 标志一起,走 freestanding 编译前缀那条路,而探针从未拿到它。于是每一次
-freestanding 构建都是拿宿主去核对声明:在 Linux 宿主上,那台宿主恰好满足 `__unix__` 已
-定义、`_WIN32` 未定义、`wchar_t` 32 位,于是检查以错误的理由通过;在 Windows 宿主上它报
-`_WIN32` 已定义、`wchar_t` 16 位,构建失败。
-
-2026.9.18.3 把那次 Windows 失败读成"`--target=` 替换没能剥掉宿主预定义",于是加了一个
-`hostStripMacros` 列表,由调用方在 `-dM` 之前前置一组 `-U<name>`。clang 的预定义跟随的是
-目标而不是宿主——在 Linux 宿主上 `--target=riscv64-none-elf` 报 `__riscv`、不报 `__linux__`、
-`__SIZEOF_WCHAR_T__` 为 4——所以根本没有一次替换失败过。那个列表被删除,而删除本身就是
-要点而非顺手整理:它抹掉的正是"探针量错了机器"这件事的唯一证据。
-
-装配处拒绝这次遗漏,而不是每个调用点各自记得不要犯。`cenv_probe::assemble_argv` 在一个
-freestanding 目标的 argv 没有选中目标时返回拒绝;而对宿主本地构建接受没有目标选择的
-argv——那里宿主**就是**目标,缺席是那个决定本身,不是它的遗漏。
-
-`__SIZEOF_WCHAR_T__` 那一处配套缺陷仍然关闭在实现侧,并且与上述无关:`cenv::realise`
-对 `decl.wcharBits = 32` 一律发 `-fno-short-wchar`,不论某个工具链的默认值是什么,于是
-编译产出的宽度是声明所述的那个,而不是继承来的。
-
-**一个包提供了该层的哪些接口,又需要哪些(mcpp 2026.9.20.1)。** 一项能力要么在要么不在,
-而一个包需要能够在被构建之前陈述它需要什么。openkal 自己的规范(0.14 §3.3)撤回了它给
-接口**集合**起过的唯一一个名字(`hosted`),理由是:一个描述环境类别的名字,会被没有人
-想到过的那个环境证伪;替代做法是由消费者在自己的包里逐条列举。mcpp 为 `kernel-abi` 层
-承载这份列举:
+这是一条边界规则，由这一个开关记录下来，而不是由引擎强制执行的：这样的包对
+图其余部分暴露的接口，仍然只能用定宽类型跨越（SPEC §5.4）。
+
+**声明被校验，而不是被信任。** 一条声明要经过核对，绝不直接被信任——这与
+openkal 核对自身一致性声明所用的做法相同。目标侧解析出上述开关之后，mcpp
+用它们编译一个纯预处理探针（`-E -dM`，把预定义宏全部打印出来——足够便宜，
+且不需要执行，这一点很重要，因为解析出的环境常常是一个交叉目标），读回
+`__SIZEOF_LONG__`、`__SIZEOF_WCHAR_T__`，以及哪些环境身份宏被定义，与声明
+核对。不符即让构建失败，并同时打印声明值与实测值。结果按配置（编译器二进制
+身份加最终参数）缓存，同一配置解析两次只编译一次探针。
+
+**探针的命令行必须选中目标，而在 freestanding 上它一度没有做到（mcpp
+2026.9.20.1）。** clang 是一个二进制，它能产出自己被编译进去的每一个目标，
+因此一条不点名目标的命令行回答的是它自己所在的那台机器。宿主交叉目标经由
+`--target=` 到达探针；freestanding 目标的目标选择与必须随行的 ISA flag
+走的是同一条路——freestanding 编译前缀——而探针从未拿到过它。于是每一次
+freestanding 构建实际上是拿宿主去核对声明：在 Linux 宿主上，那台宿主恰好
+满足 `__unix__` 已定义、`_WIN32` 未定义、`wchar_t` 32 位，于是检查以错误的
+理由通过；在 Windows 宿主上它报 `_WIN32` 已定义、`wchar_t` 16 位，构建失败。
+
+2026.9.18.3 把那次 Windows 失败读成「`--target=` 替换没能剥掉宿主预定义」，
+于是加了一个 `hostStripMacros` 列表，由调用方在 `-dM` 之前前置一组
+`-U<name>`。clang 的预定义跟随的是目标而不是宿主——在 Linux 宿主上
+`--target=riscv64-none-elf` 报 `__riscv`、不报 `__linux__`、
+`__SIZEOF_WCHAR_T__` 为 4——所以根本没有一次替换失败过。那个列表已被删除，
+而删除本身就是要点，不是顺手整理：它抹掉的正是「探针量错了机器」这件事的
+唯一证据。
+
+装配处拒绝这次遗漏，而不是让每个调用点各自记得不要犯它。
+`cenv_probe::assemble_argv` 在一个 freestanding 目标的 argv 没有选中目标时
+返回拒绝；而对一次宿主本地构建接受没有目标选择的 argv——那里宿主**就是**
+目标，缺席是那个决定本身，不是它的遗漏。
+
+`__SIZEOF_WCHAR_T__` 那一处配套缺陷仍然关闭在实现侧，并且与上述无关：
+`cenv::realise` 对 `decl.wcharBits = 32` 一律发出 `-fno-short-wchar`，不论
+某个工具链的默认值是什么，于是编译产出的宽度就是声明所述的那个，而不是继承
+来的。
+
+**一个包提供该层的哪些接口，又需要哪些（mcpp 2026.9.20.1）。** 一项能力要么
+在场要么不在场，而一个包需要能够在被构建之前陈述自己需要什么。openkal 自己
+的规范（0.14 §3.3）撤回了它为接口**集合**起过的唯一一个名字（`hosted`），
+理由是：一个描述环境类别的名字，会被没有人想到过的那个环境证伪；替代做法是
+由消费者在自己的包里逐条列举。mcpp 为 `kernel-abi` 层承载这份列举：
 
 ```toml
-# 实现方
+# the implementation
 [package]
 provides = ["mcpp:kernel-abi=openkal"]
 
@@ -457,129 +501,144 @@ provides = ["mcpp:kernel-abi=openkal"]
 provides-interfaces = ["openkal.abort", "openkal.stream", "openkal.memory",
                        "openkal.env", "openkal.time", "openkal.fs"]
 
-# 消费方
+# a consumer
 [kernel-abi]
 requires-interfaces = ["openkal.fs", "openkal.net"]
 ```
 
-`provides-interfaces` 只有提供该层的包可以陈述,这是 `[c-abi]` 遵循的同一条规则,理由
-相同。`requires-interfaces` 没有这个限制:它是关于陈述它的那个包自身的一句话。
+`provides-interfaces` 只有供给该层的包可以陈述，这是 `[c-abi]` 遵循的同一条
+规则，理由也相同。`requires-interfaces` 没有这个限制：它是一句关于陈述它的
+那个包自身的话。
 
-**引擎不认识这两个集合的任何一个成员。** 对它们做的唯一操作是集合差,因此某个规范新增
-一个接口不需要 mcpp 发版;而拼错会产出一条点名该字符串的拒绝,而不是一次被静默关掉的
-检查——一个没有被提供的名字就是缺的,不论它是否存在。
+**引擎不认识这两个集合中的任何一个成员。** 对它们施加的唯一操作是集合差，
+因此某个规范新增一个接口不需要 mcpp 发新版；而一次拼写错误会产出一条点名
+该字符串的拒绝，而不是一次被静默关掉的检查——一个没有被提供的名字就是缺的，
+不论它是否真的存在。
 
-**这个问题在依赖解析时回答,因为那是它最早能被回答的时刻。** openkal SPEC 0.14 §6.2
-列出能力信息出现的三个时刻,并规定每个都是该信息最早能存在的时刻:解析回答"这个程序
-可不可以在这个实现上构建",链接回答"有没有用到实现没提供的接口",能力字回答"在它提供
-的接口内它如何表现"。源码用 `#ifdef` 问同一个问题,问在预处理期——比任何答案存在得更早。
+**这个问题在依赖解析时回答，因为那是它最早能被回答的时刻。** openkal SPEC
+0.14 §6.2 列出能力信息出现的三个时刻，并规定每一个都是该信息最早能存在的
+那一刻：解析回答「这个程序可不可以针对这个实现构建」，链接回答「有没有用到
+实现没有提供的接口」，一个能力字回答「在它提供的接口内，它如何表现」。源码用
+`#ifdef` 问的是同一个问题，却问在预处理期——比任何答案存在得更早。
 
-**一个什么都没陈述的提供者,不是一个什么都不提供的提供者。** 实现方没有写
-`provides-interfaces` 的图照常构建;这个键晚于那些包出现,而链接仍以它一贯的词汇报告缺席。
+**一个什么都没陈述的提供者，不是一个什么都不提供的提供者。** 一份实现方没有
+写 `provides-interfaces` 的图照常构建；这个键晚于那些包出现，而链接仍以它
+一贯的词汇报告缺席。
 
-**但它会说出来(mcpp 2026.9.21.2)。** 一共三种情形、其中两种能构建——提供方陈述了列表且
-包含该需求;陈述了列表但不包含(拒绝);什么都没陈述——而在这行提示之前,第一种与第三种
-产生一模一样的输出:
+**但它会说出来（mcpp 2026.9.21.2）。** 一共三种情形，其中两种能构建——
+提供方陈述了一份列表且列表包含该需求；陈述了列表但不包含（拒绝）；什么都没
+陈述——而在这条提示出现之前，第一种与第三种产生一模一样的输出：
 
 ```
         note kernel-abi interfaces: fakekernel@0.1.0 states none, 2 requirements unchecked
 ```
 
-**一条没人回答的需求,读起来和一条被确认的需求一模一样**,这正是它要关掉的缺口:一个看着
-绿色构建的消费者,分不清「问过并且一致」与「从来没问成」。提示点名解析出的那个实现,因为
-一个只被告知「有东西没检查」的读者无法据此行动。提供方确实陈述了列表时这行不出现,
-`tests/e2e/743` 双向断言——没有第二条腿的话,第一条腿在一个无条件打印这行的引擎上同样会绿。
+**一条没人回答的需求，读起来和一条被确认过的需求一模一样**，这正是它要关掉
+的那个缺口：一个看着绿色构建的消费者，分不清「问过并且一致」与「从来没问成」。
+提示点名解析出的那个实现，因为一个只被告知「有东西没检查」的读者，无法据此
+行动。提供方确实陈述了列表时，这一行不出现，`tests/e2e/743` 双向断言——
+没有第二条腿，第一条腿在一个无条件打印这一行的引擎上同样会绿。
 
-**一个 C 库不供给什么(`[c-abi-absent]`,mcpp 2026.9.20.1)。** 一个 C 库供给的名字集合
-在清单里不可枚举——POSIX 约有一千二百个——而枚举它正是 §3.3 记录下撤回的那个错误。
-例外是可枚举的:
+**一个 C 库不供给什么（`[c-abi-absent]`，mcpp 2026.9.20.1）。** 一个 C 库供给
+的名字集合在清单里不可枚举——POSIX 约有一千二百个——枚举它正是 §3.3 记录下
+撤回的那个错误。例外是可枚举的：
 
 ```toml
 [c-abi-absent]
 fork      = { form = "link" }
-mprotect  = { form = "enosys", note = "openkal 没有作用于映射保护属性的操作" }
-tcsetattr = { form = "accepted-no-effect", note = "openkal 不命名的那些字段不被施加" }
-```
-
-`form` 必填且取值封闭。`link` 是 openkal 自己的能力模型对一个实现所要求的形状(§6.1 把
-运行期报告不支持称为缺陷);另外两个是对它的偏离,给它们命名是为了让一次偏离成为可以被
-数出来的东西。当链接点到 `link` 形状里的某一项时,mcpp 把这份清单读回来,于是
-`undefined reference to 'fork'` 会带着那句说明它是缺陷还是这个程序所构建环境之限制的话
-一起到达。
-
-**早于这些键的引擎,以及两张表都是顶层表的理由。** 旧 mcpp 忽略它不认识的**顶层表**,
-而拒绝它认识的表里的**未知成员**——后者正是让拼错的 `presents` 不会静默关掉一条声明的
-机制。因此两张新表都写成顶层表;对 `[c-abi-absent]` 而言,这个位置是量出来的,不是偏好。
-
-写成 `[c-abi].absent` 更顺,但那样每个早于 2026.9.20.1 的 mcpp 都会**在每个目标上拒绝
-整份清单**,报 `[c-abi] has no member 'absent'`。判据取自真正发布的 2026.9.18.3 归档
-——当时的索引 floor——跑在 openkal-musl 0.17.0 将要发布的那份清单上。这张表做的每一件事
-都是诊断性的:它给一次**已经失败**的链接加上一句话,没有任何 flag、链接行或产物依赖它。
-于是忽略它的引擎产出的正是它今天产出的那条链接错误;而拒绝它的引擎会让整个包不可用,
-并且会把索引 floor 逼到这个版本——为了一句他们无非是收不到的说明,夺走停在其下的每个
+mprotect  = { form = "enosys", note = "openkal has no operation upon a mapping's protection" }
+tcsetattr = { form = "accepted-no-effect", note = "the fields openkal does not name are not applied" }
+```
+
+`form` 必填且取值封闭。`link` 是 openkal 自己的能力模型对一个实现所要求的
+形状（§6.1 把运行期报告不支持称为一处缺陷）；另外两个是对它的偏离，给它们
+命名是为了让一次偏离成为可以被数出来的东西。当链接命中 `link` 形状里的
+某一项时，mcpp 把这份清单读回来，于是 `undefined reference to 'fork'` 会带着
+那句说明它是缺陷还是这个程序所构建环境之限制的话一起到达。
+
+**早于这些键的引擎，以及两张表都写成顶层表的理由。** 旧 mcpp 忽略它不认识的
+**顶层表**，而拒绝它认识的表里的**未知成员**——后者正是让拼错的 `presents`
+不会静默关掉一条声明的机制。因此这两张新表都写成顶层表；对
+`[c-abi-absent]` 而言，这个位置是量出来的，不是偏好。
+
+写成 `[c-abi].absent` 更顺，但那样一来，每个早于 2026.9.20.1 的 mcpp 都会
+**在每一个目标上拒绝整份清单**，报 `[c-abi] has no member 'absent'`。判据取自
+真正发布的 2026.9.18.3 归档——当时的索引 floor——跑在 openkal-musl 0.17.0
+即将发布的那份清单上。这张表做的每一件事都是诊断性的：它给一次**已经失败**
+的链接加上一句话，没有任何 flag、链接行或产物依赖它。于是忽略它的引擎产出的
+正是它今天产出的那条链接错误，而拒绝它的引擎会让整个包不可用，并且会把索引
+floor 逼到这个版本——为了一句他们本来就收不到的说明，夺走停在其下的每一个
 客户端手里的**整个索引**。
 
-对一个包的后果:采用任一张表都不对索引 floor 提出要求,旧引擎解析出的图照常构建,失去的
-只是那项检查和那句说明,而那正是那个版本本来就有的行为。把 `absent` 写在 `[c-abi]` 里面
-会被拒绝,拒绝消息点名顶层的那个拼法。
-
-**指纹。** 解析出的环境参与构建指纹(`compileFlags`,§92 的第 7 项):C 库声明 `lp64` 与
-`llp64` 的两次构建,从同一份源码编译出 `long` 宽度不同的目标文件,因此二者绝不共享输出目录,
-也不会复用对方产出的目标文件缓存。
-
-**全局构建缓存的键也覆盖了这一点(mcpp 2026.9.18+,PR 进行中的修订,不是设计原文)。**
-`~/.mcpp/build-cache/v1`——一次普通依赖编译跨项目、也跨 `mcpp` 升级复用的缓存——是与上面
-构建指纹分开的另一套机制,按包逐一取键,只取真正到达该包自身编译命令行的那些轴
-(`mcpp.build.cache_key`)。解析出的环境到达一个包的命令行,完全是通过引擎的**广播**
-(与 `targetSideUsage`、`-D__OPENKAL__` 同一条通道),从来不经过包自己声明的
-`[build] cflags`/`cxxflags`——所以键的推导本身也得被告知去读广播后的值,而不只是声明的值。
-这个缺口正是这样被发现的(协调者反馈,openkal-musl 尖峰实验):原地升级 `mcpp`、缓存目录
-未清理时,给按新环境构建的镜像喂了按**旧**解析环境编译出的目标文件——一个镜像里混了两种
-C 环境,而且没有任何诊断。`fill_package_config` 现在把 `PackageRoot::privateBuild.cflags`/
-`cxxflags`/`asmflags`——广播之后的值——和包自己声明的标志一起折进键里,做法与它原本处理
-include 目录的方式完全一致。`--cache=off`,或者干脆清空缓存目录,从来都不是键本身正确
-的信号——这两条路径都是绕开了这个键,而不是证明了它。
-
-**这次发布还把缓存的 epoch 提了一版,让已有条目全部作废——升级后第一次构建会是冷构建。**
-键改对了,不代表用旧的、错误推导方式写下的条目就可以留着继续信:一个条目被污染,恰恰是
-因为它记录的键和它实际编译时的输入从一开始就对不上——而修好之后最可能仍然拿到不变的键
-的那个包,正好是这次修订里新推导进 `c-environment = "platform"` 的那一类(上文的
-kernel-abi 提供者):它的 `privateBuild.cflags` 现在是空的,新键因此是从空内容算出来的,
-跟旧键(同样是从空内容算出来的)一样;而磁盘上那份目标文件,却是带着替换令牌编译出来的。
-没有更便宜的办法能把修复前写下的条目和修复后写下的条目分开,所以
-`mcpp.build.cache_key::kCacheEpoch` 往上提了一版(2 → 3),让整个缓存无条件作废,而不是
-去相信一个恰恰在最要紧的那些条目上靠不住的键相等判断。
-
-**存储键——尚未补上,这里把它到底意味着什么讲清楚(对照真正写入 store 的那条代码路径核实
-过,mcpp 2026.9.18+)。** 一个包的**安装钩子**能够、也确实会编译目标侧代码——目标文件、
-静态库——而它装进的共享 store 只按包名与版本取键,这与 [requires](#requires) 已经记录的
-C++ 运行时选择缺口同形。它和上面构建缓存的键不同、也不是这一个 PR 能用同样方式补上的地方
-在于:安装钩子运行在工具链解析**之前**,这是真实的顺序约束,不是遗漏。`install_hook_env`
-在正常路径上工具链相关的字段一律为空——`prepare.cppm` 要等依赖图装完之后才解析 `tc`,因为
-解析目标侧本身可能要依赖图最终供给了哪个包的哪一层(`c-abi` 提供者正是这个图里的一个成员)。
-钩子没有办法去问这次构建解析出了什么环境,因为在它运行的那一刻,压根还没有算出来——不是
-mcpp 忘了传给它,是那时候真的没有可传的东西。
-
-**失败模式,直说,不当成缺口表里的一行:** 一个编译了对环境敏感的 C 代码的钩子(凡是正确性
-依赖 `wchar_t` 宽度、数据模型、或哪些环境身份宏被定义的代码)没有办法问这次构建实际解析出
-什么,所以它只能按一种假设编译,然后指望每一个消费者都跟它假设的一样。一个图里声明的
-`[c-abi]` 与之不符的项目,会拿到按一种 `wchar_t` 宽度编译的目标文件,去链接按另一种宽度
-写的头文件——**没有任何东西会去核对这件事**:store 里不记录它装的是按哪种环境编译的,所以
-根本没有可以核对的对象,只有一次悄无声息的错误链接。这与上面 C++ 运行时那条 `requires`
-检查已经接受下来的、同一种形状的已知限制相同,不是这一个 PR 新引入的——`[c-abi]` 继承它,
-是因为它继承了同一个 store。
-
-**要真正补上它需要什么:** 要么 (a) 改成两阶段安装——把安装钩子做的任何目标侧编译推迟到目标侧
-解析完成之后,解析出环境后再重新调用一次钩子(或者一个更晚的第二个钩子)——这会改动整个
-代码库目前当作固定不变的安装/解析顺序;要么 (b) 把 `c++-abi` 那条 `requires` 形状检查的
-做法,推广到 `c-abi`/`c-environment`——包声明它的 store 产物是按哪种环境构建的,工具链解析
-完之后核对,不符就拒绝——这个方案本节已经设计好,但这个 PR 里没有实现。在其中一个真正落地
-之前,过渡期的纪律和 C++ 运行时那条现有要求一样:这类包的安装钩子不得把一种以上的环境变体
-构建进同一个 store 目录。
+对一个包的后果：采用这两张表中的任何一张，都不对索引 floor 提出要求，旧引擎
+解析出的图照常构建，失去的只是那项检查和那句说明，而那正是那个版本本来就有
+的行为。把 `absent` 写在 `[c-abi]` 里面会被拒绝，拒绝消息点名顶层的那个拼法。
+
+**指纹。** 解析出的环境参与构建的指纹（`compileFlags`，§92 第 7 项）：C 库
+声明 `lp64` 与 `llp64` 的两次构建，从同一份源码编译出 `long` 宽度不同的
+目标文件，因此二者绝不共享输出目录，也不会复用对方产出的目标文件缓存。
+
+**全局构建缓存的键也覆盖了这一点（mcpp 2026.9.18+，一次 PR 中期修订，不是
+设计原文）。** `~/.mcpp/build-cache/v1`——一次普通依赖编译跨工程、也跨
+`mcpp` 升级复用的缓存——是与上面构建指纹分开的另一套机制，按包逐一取键，
+只取真正到达该包自身编译命令行的那些轴（`mcpp.build.cache_key`）。解析出的
+环境到达一个包的命令行，完全是通过引擎的**广播**（与 `targetSideUsage`、
+`-D__OPENKAL__` 同一条通道），从来不经过包自己声明的
+`[build] cflags`/`cxxflags`——所以键的推导本身也必须被告知去读广播之后的
+值，而不只是声明的值。这个缺口正是这样被发现的（协调者反馈，openkal-musl
+尖峰实验）：原地升级 `mcpp`、且缓存目录未清理时，给按新环境构建的镜像喂了
+按**旧**解析环境编译出的目标文件——一个镜像里混了两种 C 环境，且没有任何
+诊断。`fill_package_config` 现在把 `PackageRoot::privateBuild.cflags`/
+`cxxflags`/`asmflags`——广播之后的值——和包自己声明的 flag 一起折进键里，
+做法与它原本处理 include 目录的方式完全一致。`--cache=off`，或者干脆清空
+缓存目录，从来都不是「键本身是对的」这件事的信号——这两条路径都只是绕开了
+这个键，而不是证明了它。
+
+**这次发布还把缓存的 epoch 提了一版，让已有条目全部作废——升级后第一次
+构建会是冷构建。** 键改对了，不代表用旧的、错误推导方式写下的条目就可以留着
+继续信：一个条目被污染，恰恰是因为它记录的键和它实际编译时的输入从一开始就
+对不上——而修好之后最可能仍然拿到不变的键的那个包，正好是这次修订里新推导
+进 `c-environment = "platform"` 的那一类（上文的 kernel-abi 提供者）：它的
+`privateBuild.cflags` 现在是空的，新键因此是从空内容算出来的，跟旧键（同样是
+从空内容算出来的）一样；而磁盘上那份目标文件，却是带着替换令牌编译出来的。
+没有更便宜的办法能把修复前写下的条目和修复后写下的条目分开，所以
+`mcpp.build.cache_key::kCacheEpoch` 往上提了一版（2 → 3），让整个缓存无条件
+作废，而不是去相信一个恰恰在最要紧的那些条目上靠不住的键相等判断。
+
+**存储键——尚未补上，这里把它到底意味着什么讲清楚（对照真正写入 store 的
+那条代码路径核实过，mcpp 2026.9.18+)。** 一个包的**安装钩子**能够、也确实
+会编译目标侧代码——目标文件、静态库——而它装进的共享 store 只按包名与版本
+取键，这与 [requires](#requires) 已经记录的 C++ 运行时选择缺口同形。它与上面
+构建缓存的键不同、也不是这一个 PR 能用同样方式补上，是因为：安装钩子运行在
+工具链解析**之前**，这是真实的顺序约束，不是遗漏。`install_hook_env` 在正常
+路径上工具链相关的字段一律为空——`prepare.cppm` 要等依赖图装完之后才解析
+`tc`，因为解析目标侧本身可能要依赖图最终供给了哪个包的哪一层（`c-abi`
+提供者正是这个图里的一个成员）。钩子没有办法去问这次构建解析出了什么环境，
+因为在它运行的那一刻，压根还没有算出来——不是 mcpp 忘了传给它，是那时候
+真的没有可传的东西。
+
+**失败模式，直说，不当成缺口表里的一行：** 一个编译了对环境敏感的 C 代码的
+钩子（凡是正确性依赖 `wchar_t` 宽度、数据模型、或哪些环境身份宏被定义的
+代码）没有办法问这次构建实际解析出什么，所以它只能按一种假设编译，然后指望
+每一个消费者都跟它假设的一样。一个图里声明的 `[c-abi]` 与之不符的工程，
+会拿到按一种 `wchar_t` 宽度编译的目标文件，去链接按另一种宽度写的头文件——
+**没有任何东西会去核对这件事**:store 里不记录它装的是按哪种环境编译的，
+所以根本没有可以核对的对象，只有一次悄无声息的错误链接。这与上面 C++ 运行时
+那条 `requires` 检查已经接受下来的、同一种形状的已知限制相同，不是这一个 PR
+新引入的——`[c-abi]` 继承它，是因为它继承了同一个 store。
+
+**要真正补上它需要什么：** 要么 (a) 改成两阶段安装——把安装钩子做的任何
+目标侧编译推迟到目标侧解析完成之后，解析出环境后再重新调用一次钩子（或者
+一个更晚的第二个钩子），这会改动整个代码库目前当作固定不变的安装/解析顺序；
+要么 (b) 把 `c++-abi` 那条 `requires` 形状检查的做法，推广到
+`c-abi`/`c-environment`——包声明它的 store 产物是按哪种环境构建的，工具链
+解析完之后核对，不符就拒绝——这个方案本节已经设计好，但这个 PR 里没有实现。
+在其中一个真正落地之前，过渡期的纪律和 C++ 运行时那条现有要求一样：这类包的
+安装钩子不得把一种以上的环境变体构建进同一个 store 目录。
 
 ### 标准库模块源
 
-作为标准库的包陈述它的 `std` 模块源在何处,以及该源需要什么。
+作为标准库的包陈述它的 `std` 模块源在何处，以及该源需要什么。
 
 ```toml
 [build]
@@ -588,25 +647,26 @@ std-compat-module = "llvm-generated/std.compat.cppm"
 std-module-flags  = ["--no-default-config", "-nostdinc", "-nostdinc++"]
 ```
 
-这些键属于 `[build]`,因为模块源是该包的一个翻译单元:
-它以该包的 include 目录与定义被编译。属于 `[build]` 同时使这些 flag 可条件化,
-而一个在多种 C 库之上供给同一 C++ 运行时的包需要这一点。
+这些键属于 `[build]`，因为模块源是该包的一个翻译单元：它以该包的 include
+目录与定义被编译。属于 `[build]` 同时使这些 flag 可以条件化，而一个在多种
+C 库之上供给同一 C++ 运行时的包需要这一点。
 
 ```toml
 [target.'cfg(c-abi = "musl")'.build]
 std-module-flags = ["-D_GNU_SOURCE"]
 ```
 
-声明 `std-module` 而没有相应的 `provides` 条目是错误:该包描述了一个它并不供给的库。
+声明 `std-module` 而没有相应的 `provides` 条目是一个错误：该包描述了一个它
+并不供给的库。
 
-这三个键的 `[package]` 写法仍被接受,且不可条件化。
+这三个键的 `[package]` 写法仍被接受，且不可条件化。
 
-### 标准库自身的语言级别(mcpp 2026.9.15.2+)
+### 标准库自身的语言级别（mcpp 2026.9.15.2+）
 
-一张模块图以同一个标准编译,即根包的标准([07 —— 工作空间](07-workspace.md) §4.2)。
-供给 C++ 层的包(`hosted-standard-library` 或 `mcpp:c++-abi=<impl>`)是唯一的例外:
-它陈述了 `[package] standard` 时,它的每个既不提供也不导入模块的 C++ 翻译单元都恰好以该级别编译,
-与图的级别无关。
+一张模块图以同一个标准编译，即根包的标准（[07 —— 工作空间](07-workspace.md)
+§4.2）。供给 C++ 层的包（`hosted-standard-library` 或 `mcpp:c++-abi=<impl>`）
+是唯一的例外：它陈述了 `[package] standard` 时，它的每一个既不提供也不导入
+模块的 C++ 翻译单元都恰好以该级别编译，与图的级别无关。
 
 ```toml
 [package]
@@ -614,18 +674,21 @@ standard = "c++23"
 provides = ["hosted-standard-library", "mcpp:c++-abi=libc++"]
 ```
 
-标准库以自己的级别构建,并在其他任何级别被使用:上游以 C++23 编译 libc++,而 libc++ 22 的
-源码在 C++20 下无法编译。这一例外是安全的,因为它覆盖的单元不读也不写 BMI;该包的模块单元,
-包括 `std` 与 `std.compat` 模块,仍按图的级别编译,因此没有模块被分裂。该级别被追加到每个被覆盖
-单元自己的 flag 中,因此同样到达编译命令、依赖扫描、`compile_commands.json` 与
-`mcpp emit build-database`。不陈述 `standard` 的供给者按图的级别编译。
+标准库以自己的级别构建，并在其他任何级别下被使用：上游以 C++23 编译
+libc++，而 libc++ 22 的源码在 C++20 下无法编译。这一例外是安全的，因为它
+覆盖的单元既不读也不写 BMI；该包的模块单元，包括 `std` 与 `std.compat`
+模块，仍按图的级别编译，因此没有任何模块被分裂。该级别被追加到每个被覆盖
+单元自己的 flag 中，因此同样到达编译命令、依赖扫描、`compile_commands.json`
+与 `mcpp emit build-database`。不陈述 `standard` 的供给者按图的级别编译。
 
-这一例外不推广到其他包。声明依赖于 `__cplusplus` 的头文件会使普通库的目标文件与其消费者的
-目标文件在没有诊断的情况下不一致,而标准库正是其接口被设计为在另一级别下使用的那一类包。
+这一例外不推广到其他包。一个头文件若声明依赖于 `__cplusplus`，会使普通库的
+目标文件与其消费者的目标文件在没有诊断的情况下互不一致，而标准库正是其接口
+被设计为在另一级别下使用的那一类包。
 
 ### 对已解析目标侧的适配
 
-供给某一层的包经常支持其下方层的多个实现。它查询已解析的目标侧,而非被告知。
+供给某一层的包经常支持其下方层的多个实现。它查询已解析的目标侧，而不是
+被告知。
 
 ```toml
 [target.'cfg(c-abi = "musl")'.build]
@@ -635,44 +698,45 @@ include_dirs = ["config/musl"]
 include_dirs = ["config/picolibc"]
 ```
 
-若此处要求一次特性选择,将迫使工程重述目标三元组或其依赖图已经确立的事实,
-并允许两处陈述互相矛盾。
+若此处要求一次 feature 选择，将迫使工程重述目标三元组或其依赖图已经确立的
+事实，并让两处陈述有可能互相矛盾。
 
-**当某一层由依赖图供给时,编译器不再搜索该层的宿主位置。**
-`mcpp.toolchain.hostflags` 读取每一层的来源并关掉对应的编译器隐式搜索:
-图供给 `c-abi` 时去掉编译器自带的 C 库搜索路径(`-nostdlibinc`),
-图供给 `c++-abi` 时去掉其 C++ 搜索路径(`-nostdinc++`)—— 两者各自独立判断,
-不取决于另一层是否也来自图。在此之前,一个只因为宿主头文件恰好补上了某个缺口
-才能编译的包,会在一台机器上构建成功、在另一台机器上以不同方式失败;现在确定的
-结果只有两种 ——「在图里找到」与「没找到」,不再有「用了这台机器上恰好装着的
-那份 SDK」。包应当通过下面的层谓词来适配,而不是依赖宿主机器恰好装了什么。
+**当某一层由依赖图供给时，编译器不再搜索该层的宿主位置。**
+`mcpp.toolchain.hostflags` 读取每一层的来源，并关闭对应的编译器隐式搜索：
+图供给 `c-abi` 时去掉编译器自带的 C 库搜索路径（`-nostdlibinc`），图供给
+`c++-abi` 时去掉它的 C++ 搜索路径（`-nostdinc++`）——两者各自独立判断，
+不取决于另一层是否也来自图。在此之前，一个只因为宿主头文件恰好补上了某个
+缺口才能编译的包，会在一台机器上构建成功、在另一台机器上以不同方式失败；
+现在确定的结果只有两种——「在图里找到」与「没找到」，不再有「用了这台机器上
+恰好装着的那份 SDK」。包应当通过下面的层谓词来适配，而不是依赖宿主机器
+恰好装了什么。
 
-谓词的键就是五个层名,值就是本章开头那张表里的接口名 —— 与 `Target` 报告打印的是
-同一批字符串。它们可以与三元组键在 `all`/`any`/`not` 下组合:
+谓词的键就是五个层名，值就是本章开头那张表里的接口名——与 `Target` 报告
+打印的是同一批字符串。它们可以与三元组键在 `all`/`any`/`not` 下组合：
 
 ```toml
 [target.'cfg(all(linux, c-abi = "musl"))'.build]
 cxxflags = ["-D_GNU_SOURCE"]
 ```
 
-**层名的是库,不是三元组的 env 段。** 二者在 `musl` 上重合,在 `gnu` 上分叉:
-在 Linux 上该段请求的是 glibc,在 Windows 上它命名的是工具链的 MinGW 形态,
-而后者的 C 运行时与 MSVC 形态链接的是同一个 UCRT。写法是 `c-abi = "glibc"`,
-而非 `c-abi = "gnu"`;与答案相对的那个「请求」是 `env = "gnu"` —— 另一个问题
-(`docs/specs/target-side.md` §3.4)。
+**层名指的是库，不是三元组的 env 段。** 二者在 `musl` 上重合，在 `gnu` 上
+分叉：在 Linux 上该段请求的是 glibc，在 Windows 上它命名的是工具链的
+MinGW 形态，而后者的 C 运行时与 MSVC 形态链接的是同一个 UCRT。写法是
+`c-abi = "glibc"`，而非 `c-abi = "gnu"`；与答案相对的那个「请求」是
+`env = "gnu"`——这是另一个问题（`docs/specs/target-side.md` §3.4）。
 
-**`env` 与 `c-abi` 不可互换。** `env` 是三元组**请求**的东西;`c-abi` 是图与载荷
-**回答**的东西。依赖图里的 `openkal-musl` 会在 `x86_64-linux-gnu` 三元组下供给 musl,
-而只有 `c-abi` 看得见这件事。
+**`env` 与 `c-abi` 不可互换。** `env` 是三元组**请求**的东西；`c-abi` 是图
+与载荷**回答**的东西。依赖图里的 `openkal-musl` 会在 `x86_64-linux-gnu`
+三元组下供给 musl，而只有 `c-abi` 看得见这件事。
 
-这些谓词仅在 `[build]` 段中可用。目标侧在依赖解析之后才被解析,
-因此由它选择的依赖将构成环;`[target.'cfg(<层> = …)'.dependencies]` 会被报出并忽略,
-而不是被静默丢弃。一个在不同 C 库下需要不同依赖的包,
-按 C 库拆分,或依赖其并集并在 `[build]` 中选择源码。
+这些谓词只在 `[build]` 段中可用。目标侧在依赖解析之后才被解析，因此由它
+选择的依赖会构成一个环；`[target.'cfg(<层> = …)'.dependencies]` 会被报出并
+忽略，而不是被静默丢弃。一个在不同 C 库下需要不同依赖的包，要么按 C 库拆分，
+要么依赖其并集，再在 `[build]` 中选择源码。
 
-mcpp 不认识的键 —— 打错的字,或来自更新版本 mcpp 的谓词 —— 会被报成一条 schema
-警告,并且该段不生效。它过去是静默地求值为假,而那与「这一段本就不该匹配」读数完全
-相同。
+mcpp 不认识的键——拼错的字，或来自更新版本 mcpp 的谓词——会被报成一条
+schema 警告，并且该段不生效。它过去静默地求值为假，而那与「这一段本就
+不该匹配」读起来完全相同。
 
 ## 诊断
 
@@ -680,78 +744,81 @@ mcpp 不认识的键 —— 打错的字,或来自更新版本 mcpp 的谓词 
 
 | 情形 | 报出内容 |
 |---|---|
-| 被要求的实现不是解析出的那个 | 同时指出二者,以及选择它的命令 |
-| 两个包供给同一层 | 同时指出二者,以及各自进入图的路径 |
-| 某一层无人供给 | 指出该层,以及应当依赖的能力 |
-| 载荷的 C++ 运行时位于外来 C 库之上 | 同时指出二者,以及两条出路 |
+| 被要求的实现不是解析出的那个 | 同时指出二者，以及选择它的命令 |
+| 两个包供给同一层 | 同时指出二者，以及各自进入图的路径 |
+| 某一层无人供给 | 指出该层，以及应当依赖的能力 |
+| 载荷的 C++ 运行时位于一个外来 C 库之上 | 同时指出二者，以及两条出路 |
 
-一条来自编译器或链接器的、关于目标侧组合的消息,表明缺少一条诊断。
-在任何命令行被发出之前,引擎已经知道该组合不成立。
+一条来自编译器或链接器、关于某个目标侧组合的消息，表明缺少一条诊断。在任何
+命令行被发出之前，引擎已经知道该组合不成立。
 
 ## 兼容性
 
 三条规定保全既有清单与既有构建。
 
-能力名 `hosted-standard-library` 继续表示 C++ 层。
-同时携带两种拼写的包是一个供给者,其中命名了接口的那一条是被报告的一条。
+能力名 `hosted-standard-library` 继续表示 C++ 层。同时携带两种拼写的包是
+一个供给者，其中命名了接口的那一条是被报告的一条。
 
-工具链族拼写 `openkal-llvm` 归一为 `llvm`。它命名同一份载荷,
-并携带一条关于目标侧的事实,而上述模型从包的声明中解析该事实。
+工具链族拼写 `openkal-llvm` 归一为 `llvm`。它命名的是同一份载荷，并携带一条
+关于目标侧的事实，而上述模型从包的声明中解析该事实。
 
-保留前缀内的未知名字,在根工程自己的清单中是错误,在依赖的清单中是警告。
-前者是作者正看着的一处拼写错误;后者是一份对着更新引擎写成的清单,
-拒绝它将意味着层名词表永远不能被一个已发布的包扩展。
-清单中其它位置的未知键被忽略。
+保留前缀内的未知名字，在根工程自己的清单中是一个错误，在依赖的清单中是一条
+警告。前者是作者正看着的一处拼写错误；后者是一份针对更新引擎写成的清单，
+拒绝它将意味着层名词表永远不能被一个已发布的包扩展。清单中其它位置的未知键
+被忽略。
 
-该规定只约束此后的引擎。一个包若声明某个层名,
-其使用者仍须运行不早于该层名被引入的那个版本。
+这条规定只约束此后的引擎。一个包若声明某个层名，它的使用者仍须运行不早于
+该层名被引入的那个版本。
 
 ## `[target.*]` —— 平台条件依赖与 flag
 
-用 `[target.<sel>]` 表把依赖与构建 flag 限定到某个平台。选择器 `<sel>` 有三种形式:
+用 `[target.<sel>]` 表把依赖与构建 flag 限定到某个平台。选择器 `<sel>` 有
+三种形式：
 
 | 选择器 | 含义 | 示例 |
 |---|---|---|
-| **裸 OS 别名** | 单个 OS / 族 —— 简洁且常用的形式 | `[target.windows]`、`[target.unix]` |
-| **`cfg(...)` 谓词** | 复合条件(arch / env / 组合子) | `[target.'cfg(all(linux, not(arch = "aarch64")))']` |
-| **精确三元组** | 某个具体目标(同时承载 `toolchain` / `linkage` / `sysroot` / `runner` / `min_api_level`,见 [04 §2.7.3](04-mcpp-toml.md)) | `[target.x86_64-linux-musl]` |
+| **裸 OS 别名** | 单个 OS / 族——简洁且常用的形式 | `[target.windows]`、`[target.unix]` |
+| **`cfg(...)` 谓词** | 复合条件（arch / env / 组合子） | `[target.'cfg(all(linux, not(arch = "aarch64")))']` |
+| **精确三元组** | 某个具体目标（同时承载 `toolchain` / `linkage` / `sysroot` / `runner` / `min_api_level`，见 [04 §2.7.3](04-mcpp-toml.md)） | `[target.x86_64-linux-musl]` |
 
-一个选择器可以承载平台条件的**依赖**与**构建 flag**:
+一个选择器可以承载平台条件的**依赖**与**构建 flag**：
 
 ```toml
-# 简洁的裸别名形式 —— 仅在 Windows 上拉取并链接 OpenBLAS。
+# Concise bare-alias form — pull OpenBLAS and link it only on Windows.
 [target.windows.dependencies.compat]
 openblas = "0.3.33"
 [target.windows.build]
 ldflags = ["-Llib", "-llibopenblas"]
 
-# cfg(...) 用于复合谓词(文法:all/any/not 作用于 os/arch/family/env,
-# 以及裸别名 windows/unix/linux/macos)。
+# cfg(...) for compound predicates (grammar: all/any/not over os/arch/family/env,
+# plus the bare aliases windows/unix/linux/macos).
 [target.'cfg(all(linux, not(arch = "aarch64")))'.build]
 cxxflags = ["-march=x86-64-v2"]
 ```
 
-`[target.windows]` 与 `[target.'cfg(windows)']` 完全等价 —— 裸别名
-`windows` / `linux` / `macos` / `unix` 都不是合法的目标三元组,因此不存在歧义。
-单个 OS/族用裸形式,arch/env 条件与组合子用 `cfg(...)`。
-
-- **可用键**:`dependencies` / `dev-dependencies` / `build-dependencies` /
-  `feature-deps.<feature>`(mcpp 2026.8.6.2+ —— 见 [30 —— build.mcpp](30-build-mcpp.md);feature 本身无条件注册,
-  只有它的依赖集合受限定),以及带 `cflags` / `cxxflags` / `ldflags` / `sources`
-  的 `build`(mcpp 0.0.95+ —— 条件源码 glob,例如把 `src/x86/**/*.asm` 收在
-  `cfg(arch = "x86_64")` 之后;`!` 排除 glob 在此同样有效),再加 `flags` 与
-  `include_dirs` / `include_dirs_after`(mcpp 0.0.102+),
-  以及 `private_include_dirs` 与 `std-module-flags`(mcpp 2026.9.1.1+),
-  还有带 `frameworks` / `libraries` / `link_library_dirs` 的 `runtime`
-  (mcpp 2026.8.29.1+;`frameworks` 自 2026.9.12.3 起),以及带 `kind` 的
-  `targets.<name>`(mcpp 2026.9.14.2+;见
-  [`targets.<name> kind`](#targetsname-kind--一个库在某一行上的形态mcpp-20269142))。
-- **mcpp 不读取的子表会被报出**(mcpp 2026.9.14.2+):拼错的
-  `[target.<sel>.dependecies]` 是一条警告,列出 `[target.<sel>]` 表拥有的各个段,
-  `--strict` 下成为错误。
-- **条件依赖声明替换无条件声明**(mcpp 2026.9.14.2+)。在选择器命中的行上,
-  `[target.<sel>.dependencies]` 中某个身份的声明就是该身份的声明,无条件声明在
-  该行上不生效。某一行上以不同形态链接的依赖写两次,每次都带来源:
+`[target.windows]` 与 `[target.'cfg(windows)']` 完全等价——裸别名
+`windows` / `linux` / `macos` / `unix` 都不是合法的目标三元组，因此不存在
+歧义。单个 OS/族用裸形式，arch/env 条件与组合子用 `cfg(...)`。
+
+- **可用键**：`dependencies` / `dev-dependencies` / `build-dependencies` /
+  `feature-deps.<feature>`（mcpp 2026.8.6.2+——见
+  [30 —— 构建程序：`build.mcpp`](30-build-mcpp.md)；feature 本身无条件注册，
+  只有它的依赖集合受限定），以及带 `cflags` / `cxxflags` / `ldflags` /
+  `sources` 的 `build`（mcpp 0.0.95+——条件源码 glob，例如把
+  `src/x86/**/*.asm` 收在 `cfg(arch = "x86_64")` 之后；`!` 排除 glob 在此
+  同样有效），再加 `flags` 与 `include_dirs` / `include_dirs_after`
+  （mcpp 0.0.102+），以及 `private_include_dirs` 与 `std-module-flags`
+  （mcpp 2026.9.1.1+），还有带 `frameworks` / `libraries` /
+  `link_library_dirs` 的 `runtime`（mcpp 2026.8.29.1+；`frameworks` 自
+  2026.9.12.3 起），以及带 `kind` 的 `targets.<name>`（mcpp 2026.9.14.2+；
+  见
+  [`targets.<name> kind`](#targetsname-kind--一个库在某一行上的形态mcpp-20269142)）。
+- **mcpp 不读取的子表会被报出**（mcpp 2026.9.14.2+）：拼错的
+  `[target.<sel>.dependecies]` 是一条警告，列出 `[target.<sel>]` 表拥有的
+  各个段，`--strict` 下成为错误。
+- **条件依赖声明替换无条件声明**（mcpp 2026.9.14.2+）。在选择器命中的行上，
+  `[target.<sel>.dependencies]` 中某个身份的声明就是该身份的声明，无条件
+  声明在该行上不生效。某一行上以不同形态链接的依赖写两次，每次都带来源：
 
   ```toml
   [dependencies]
@@ -762,83 +829,89 @@ cxxflags = ["-march=x86-64-v2"]
   ```
 
   同一规则适用于 `dev-dependencies`、`build-dependencies` 与
-  `feature-deps.<feature>`;多个命中的段按清单顺序生效,最后一个为准。
-  `mcpp why deps` 给出每条请求来自哪张表([09 —— 按场景的命令](09-commands-by-scenario.md))。
-  只写选项、不写来源的表 `huxerui.huxerui = { linkage = "shared" }` 声明的是
-  名为 `huxerui.huxerui.linkage` 的包:mcpp 报出这一行并给出补全来源后的声明,
-  解析随即失败。2026.9.14.2 之前的引擎保留无条件声明。
-- **`runtime` 是链接行中与方言无关的那一半。** `build.ldflags` 按 GNU 拼法书写,
-  而原生 `cl.exe` 不接受 `-L`。这些键表达同一件事而不承诺拼法:mcpp 把
-  `libraries` / `link_library_dirs` 渲染成 `-L<dir>` + `-l<name>` 或
-  `/LIBPATH:<dir>` + `<name>.lib`,把 `frameworks` 在 Mach-O 各行渲染成
-  `-framework <name>`,其余各行不产生任何标志。它们就是顶层 `[runtime]`
-  (见 [04 —— mcpp.toml](04-mcpp-toml.md) §2.11)已有的同几个键,此处只是
-  让它们按目标生效,并未引入新词汇。此处的一条追加在顶层列表**之后**,不是
-  替换——manifest 借此把 `UIKit` 挡在 macOS 链接之外、把 `AppKit` 挡在 iOS
-  链接之外,同时在顶层共享两者都要的那些 framework。`[runtime]` 的其余键
-  在这里会被报出并忽略,因为它们不是按目标区分的。
+  `feature-deps.<feature>`；多个命中的段按清单顺序生效，最后一个为准。
+  `mcpp why deps` 给出每条请求来自哪张表（[09 —— 按场景的命令](09-commands-by-scenario.md)）。
+  只写选项、不写来源的表 `huxerui.huxerui = { linkage = "shared" }`
+  声明的是名为 `huxerui.huxerui.linkage` 的包：mcpp 报出这一行并给出补全
+  来源后的声明，解析随即失败。2026.9.14.2 之前的引擎保留无条件声明。
+- **`runtime` 是链接行中与方言无关的那一半。** `build.ldflags` 按 GNU 拼法
+  书写，而原生 `cl.exe` 不接受 `-L`。这些键表达同一件事而不承诺拼法：mcpp
+  把 `libraries` / `link_library_dirs` 渲染成 `-L<dir>` + `-l<name>` 或
+  `/LIBPATH:<dir>` + `<name>.lib`，把 `frameworks` 在 Mach-O 各行渲染成
+  `-framework <name>`，其余各行不产生任何 flag。它们就是顶层 `[runtime]`
+  （见 [04 —— mcpp.toml](04-mcpp-toml.md) §2.11）已有的同几个键，此处只是
+  让它们按目标生效，并未引入新词汇。此处的一条追加在顶层列表**之后**，
+  不是替换——manifest 借此把 `UIKit` 挡在 macOS 链接之外、把 `AppKit`
+  挡在 iOS 链接之外，同时在顶层共享两者都要的那些 framework。`[runtime]`
+  的其余键在这里会被报出并忽略，因为它们不是按目标区分的。
 
   ```toml
-  # 只在 Windows 上链接,并按实际编译器的拼法书写。
+  # Linked only on Windows, and spelled correctly for whichever compiler builds it.
   [target.windows.runtime]
   libraries = ["user32", "gdi32"]
   ```
 
-  一个谓词下只写这一张表时,它与其他情形一样生效。在 mcpp 2026.9.9.1 之前并非
-  如此:除非同一谓词下还写了别的东西,该块会被解析后丢弃。
+  一个谓词下只写这一张表时，它与其他情形一样生效。在 mcpp 2026.9.9.1
+  之前并非如此：除非同一谓词下还写了别的东西，该块会被解析后丢弃。
 - **`build.ldflags` 中的相对搜索路径属于写下它的包。** `-L<dir>` 与
-  `-Wl,-rpath,<dir>` —— 无论写在这里、写在顶层 `[build] ldflags`,还是来自
-  `mcpp::link_flag` —— 以该包目录下的绝对路径进入链接,依赖的 flag 传给消费者时
-  也是如此。以加载器展开的记号开头的项按原样传递:`$ORIGIN` 及其他任何 `$` 记号,
-  以及 `@executable_path`、`@loader_path`、`@rpath`(mcpp 2026.9.14.2+)。
-- **`build` 接受的恰好是*可叠加的构建输入*集合** —— 那些以追加方式合并、
-  并在谓词求值之后被消费的东西,也就是 `BuildInputs` 的成员表。`linkage`、`target`
-  与档案开关刻意不在其中:它们是**目标选择的输入**(用一个针对 `target` 求值的谓词
-  去条件化 `target` 是循环的),或者需要覆盖而非追加的语义。
-  集合之外的键会被报出并忽略;消息里列出的正是它比对用的那份集合,因此不会与检查漂移。
-- **按解析后的目标求值** —— 交叉构建取 `--target` 三元组,否则取宿主。因此原生
-  Linux 构建**根本不会下载** `[target.windows]` 依赖。
-- **谓词的键**:`os`、`arch`、`family`、`env` —— 三元组的坐标 —— 以及自 mcpp
-  2026.9.1.1 起的五个目标侧层名 `compiler`、`compiler-runtime`、`kernel-abi`、
-  `c-abi`、`c++-abi`(见[22 —— 目标侧](22-target-side.md))。`accelerator` 同样
-  是这里的键,由本次构建自己的 `accel`(`--accel` 或 `[build] accel` 里的后端名)
-  回答,因此它是对一个集合的成员判定;`accelerator = "none"` 则是一段用来说
-  「本次构建没有命名任何后端」的写法,而不必枚举它不是的那些后端。裸词
-  `linux` / `macos` / `windows` / `unix` 是对应 `os` / `family` 判定的糖。
-  集合之外的键会被报成一条 schema 警告,且该段不生效 —— 它过去静默地求值为假,
-  而那与「这一段本就不该匹配」读数完全相同。
-- **被解析的层的谓词不能选择依赖。** 层是**从**依赖图解析出来的,因此由它选出的
-  依赖会决定它正在询问的那个答案。`[target.'cfg(c-abi = "musl")'.dependencies]`
-  会被报出并忽略;同一谓词下的 `build` 输入照常生效。`accelerator` 不在此列
-  (mcpp 2026.9.6.5):它是构建的输入而不是图给出的答案,所以
+  `-Wl,-rpath,<dir>`——无论写在这里、写在顶层 `[build] ldflags`，还是来自
+  `mcpp::link_flag`——以该包目录下的绝对路径进入链接，依赖的 flag 传给
+  消费者时也是如此。以加载器展开的记号开头的项按原样传递：`$ORIGIN`
+  及其他任何 `$` 记号，以及 `@executable_path`、`@loader_path`、`@rpath`
+  （mcpp 2026.9.14.2+）。
+- **`build` 接受的恰好是*可叠加的构建输入*集合**——那些以追加方式合并、
+  并在谓词求值之后被消费的东西，也就是 `BuildInputs` 的成员表。`linkage`、
+  `target` 与档案开关刻意不在其中：它们是**目标选择的输入**（用一个针对
+  `target` 求值的谓词去条件化 `target` 是循环的），或者需要覆盖而非追加的
+  语义。集合之外的键会被报出并忽略；消息里列出的正是它比对用的那份集合，
+  因此不会与检查本身漂移。
+- **按解析后的目标求值**——交叉构建取 `--target` 三元组，否则取宿主。因此
+  原生 Linux 构建**根本不会下载** `[target.windows]` 依赖。
+- **谓词的键**：`os`、`arch`、`family`、`env`——三元组的坐标——以及自 mcpp
+  2026.9.1.1 起的五个目标侧层名 `compiler`、`compiler-runtime`、
+  `kernel-abi`、`c-abi`、`c++-abi`（见 [22 —— 目标侧](22-target-side.md)）。
+  `accelerator` 同样是这里的键，由本次构建自己的 `accel`（`--accel` 或
+  `[build] accel` 里的后端名）回答，因此它是对一个集合的成员判定；
+  `accelerator = "none"` 是一种写法，用来说明「本次构建没有命名任何后端」，
+  而不必枚举它不是的那些后端。裸词 `linux` / `macos` / `windows` / `unix`
+  是对应 `os` / `family` 判定的糖。集合之外的键会被报成一条 schema 警告，
+  且该段不生效——它过去静默地求值为假，而那与「这一段本就不该匹配」
+  读起来完全相同。
+- **被解析的层的谓词不能选择依赖。** 层是**从**依赖图解析出来的，因此由它
+  选出的依赖会决定它正在询问的那个答案。
+  `[target.'cfg(c-abi = "musl")'.dependencies]` 会被报出并忽略；同一谓词下
+  的 `build` 输入照常生效。`accelerator` 不在此列（mcpp 2026.9.6.5）：它是
+  构建的输入而不是图给出的答案，所以
   `[target.'cfg(accelerator = "cuda")'.dependencies]` 生效。
-- **优先级**:精确三元组表胜过 `cfg`/别名表;多个命中的谓词表,其 flag 按序拼接,
-  其依赖声明按清单顺序生效。
-  条件项追加在无条件 `[build]` 项**之后**,因此在 GNU「最后一个 flag 生效」的
-  规则下,条件规则会覆盖更宽的无条件规则。这正是让按 OS **移除**成为可表达的原因:
+- **优先级**：精确三元组表胜过 `cfg`/别名表；多个命中的谓词表，其 flag
+  按顺序拼接，其依赖声明按清单顺序生效。条件项追加在无条件 `[build]`
+  项**之后**，因此在 GNU「最后一个 flag 生效」的规则下，条件规则会覆盖
+  更宽的无条件规则。这正是让按 OS **移除**成为可表达的原因：
 
   ```toml
   [build]
   flags = [{ glob = "third_party/zlib/**", defines = ["HAVE_UNISTD_H=1"] }]
 
-  # clang-MSVC 没有 <unistd.h>:撤销基础 define,加上 windows 的那个。
+  # clang-MSVC has no <unistd.h>: undo the base define, add the windows one.
   [target.'cfg(windows)'.build]
   flags = [{ glob = "third_party/zlib/**",
              defines = ["NO_FSEEKO"], cflags = ["-UHAVE_UNISTD_H"] }]
   ```
 
-- **未命中当前目标的条件 `flags` 条目根本不存在**,因此它不会产生
-  「glob 未匹配到任何源文件」的警告。于是一份 manifest 可以同时携带三个 OS 的
-  flag 表,而不会在另外两个上制造噪声 —— 与未启用 feature 的条目根本不存在是
-  同一个道理。**无条件**表里的零命中 glob 仍然告警,因为那里它是真实缺陷。
-- **`toolchain` / `linkage` / `sysroot` 仅限精确三元组** —— 它们描述某一个具体的交叉目标,
-  因此写在 `[target.<triple>]` 下(见上),而不是裸别名或 `cfg(...)` 下。
+- **未命中当前目标的条件 `flags` 条目根本不存在**，因此它不会产生「glob
+  未匹配到任何源文件」的警告。于是一份 manifest 可以同时携带三个 OS 的
+  flag 表，而不会在另外两个上制造噪声——与未启用 feature 的条目根本不存在
+  是同一个道理。**无条件**表里的零命中 glob 仍然告警，因为那里它是真实
+  缺陷。
+- **`toolchain` / `linkage` / `sysroot` 仅限精确三元组**——它们描述某一个
+  具体的交叉目标，因此写在 `[target.<triple>]` 下（见上），而不是裸别名或
+  `cfg(...)` 下。
 
 ### `sysroot` —— 目标的 C 库
 
-`sysroot`(mcpp 2026.8.20.2+)覆盖目标表为某个三元组绑定的 C 库,与 `toolchain`
-覆盖编译器 pin 同轴:一个指名目标所解析的编译器,另一个指名它的 C 库,两者在工程
-有理由与之分歧之前都只由引擎决定。
+`sysroot`（mcpp 2026.8.20.2+）覆盖目标表为某个三元组绑定的 C 库，与
+`toolchain` 覆盖编译器 pin 处于同一条轴上：一个指名目标所解析的编译器，
+另一个指名它的 C 库，在工程有理由与之分歧之前，两者都只由引擎决定。
 
 ```toml
 [target.riscv64-none-elf]
@@ -851,25 +924,26 @@ sysroot = ""                          # no C library at all
 ```
 
 **键缺席与键为空是两个不同的答案。** 缺席继承目标表的 C 库。存在且为空是
-**零 libc 档**:不解析任何 C 库,不加入头文件与库目录,链接行上只有工程与其依赖
-提供的内容,`#include <stdio.h>` 不再解析。内核与 bootloader 要的正是这一档,而把
-两种情形合并会让这类工程静默地把目标的 C 库拿回去。
+**零 libc 档**：不解析任何 C 库，不加入头文件与库目录，链接行上只有工程
+与其依赖提供的内容，`#include <stdio.h>` 不再解析。内核与 bootloader
+要的正是这一档，而把两种情形合并会让这类工程静默地把目标的 C 库拿回去。
 
-取值是 xpkg 引用或空字符串;裸名在解析清单时即被拒绝,因为接受它会导致什么都不安装,
-然后在很晚的时候以「缺少 libc」失败。
+取值是一个 xpkg 引用或空字符串；裸名在解析清单时即被拒绝，因为接受它会
+导致什么都不安装，然后在很晚的时候以「缺少 libc」失败。
 
-构建程序可以询问供给 sysroot 的是哪个 C 库**载荷**:`mcpp::target_libc()` 返回该包的
-名字,`mcpp::target_libc_profile()` 返回目标 ISA 档位对应的子目录。零 libc 档上两者均
-为空。
+构建程序可以询问供给 sysroot 的是哪个 C 库**载荷**：`mcpp::target_libc()`
+返回该包的名字，`mcpp::target_libc_profile()` 返回目标 ISA 档位对应的
+子目录。零 libc 档上两者均为空。见
+[40 —— 裸机与 freestanding 目标](40-baremetal.md)。
 
-**这与「目标侧解析出的 C 库是哪一个」不是同一个问题。** `target_libc()` 命名的是
-mcpp 装上的那个载荷,而这个值是目标侧解析的一项**输入** —— 依赖图里的包可以改为供给
-C 库,那时解析出的 `c-abi` 就不是这里返回的东西。要按已解析的层分支,请用层谓词:
-`[target.'cfg(c-abi = "musl")'.build]`(见[22 —— 目标侧](22-target-side.md))。
-这一段在 2026.9.1.1 之前写的是「解析到的是哪份 C 库」,那是两者里错的那一个。
-参见[40 —— 裸机与 freestanding 目标](40-baremetal.md)。
+**这与「目标侧解析出的 C 库是哪一个」不是同一个问题。** `target_libc()`
+命名的是 mcpp 装上的那个载荷，而这个值是目标侧解析的一项**输入**——依赖图
+里的包可以改为供给 C 库，那时解析出的 `c-abi` 就不是这里返回的东西。要按
+已解析的层分支，请用层谓词：`[target.'cfg(c-abi = "musl")'.build]`
+（见 [22 —— 目标侧](22-target-side.md)）。这一段在 2026.9.1.1 之前写的是
+「解析到的是哪份 C 库」，那是两者里错的那一个。
 
-### `abi` —— 整个产物共享的开关(mcpp 2026.9.12.2+)
+### `abi` —— 整个产物共享的开关（mcpp 2026.9.12.2+）
 
 ```toml
 [target.'cfg(os = "emscripten")'.abi]
@@ -877,22 +951,26 @@ threads    = true
 exceptions = true
 ```
 
-目标的某些性质不是单个翻译单元可以自行选择的 flag。线程支持即是一例:在 WebAssembly 上,每个目标文件、
-预编译的标准库模块与链接必须在共享内存与原子操作上保持一致,只要有一个翻译单元未启用它们,链接就会失败,
-或模块拒绝加载。异常是同一种形状:clang 把异常模型记进 BMI,并拒绝一个与之不一致的导入者。这类性质
-写作 `[target.<selector>.abi]` 的有类型成员,而不是 `cxxflags` 中的 flag,引擎因此能把它施加到每个
-必须一致的单元上,并把它与包的需求相比较。
+目标的某些性质不是单个翻译单元可以自行选择的 flag。线程支持即是一例：在
+WebAssembly 上，每个目标文件、预编译的标准库模块与链接必须在共享内存与
+原子操作上保持一致，只要有一个翻译单元没有启用它们，链接就会失败，或者
+模块拒绝加载。异常是同一种形状：clang 把异常模型记进 BMI，并拒绝一个与之
+不一致的导入者。这类性质写作 `[target.<selector>.abi]` 的有类型成员，
+而不是 `cxxflags` 中的一个 flag，引擎因此能把它施加到每一个必须一致的
+单元上，并把它与包的需求相比较。
 
 | 成员 | 类型 | 渲染为 | 到达 |
 |---|---|---|---|
-| `threads` | 布尔 | 在既非 PE 也非 freestanding 的目标上为 `-pthread`;在 PE 与 freestanding 目标上不产生任何 flag | 标准库模块的预构建、依赖扫描、所有包的每个 C 与 C++ 翻译单元,以及链接 |
-| `exceptions` *(mcpp 2026.9.12.3+)* | 布尔 | `-fexceptions`,只在 `os = "emscripten"` 上,经方言 flag 进入编译行,也进入链接行;在其余每个目标上什么都不产生,因为那里异常本来就是默认开启的 | 与 `threads` 相同的那一套 |
+| `threads` | 布尔 | 在既非 PE 也非 freestanding 的目标上为 `-pthread`；在 PE 与 freestanding 目标上不产生任何 flag | 标准库模块的预构建、依赖扫描、所有包的每个 C 与 C++ 翻译单元，以及链接 |
+| `exceptions` *(mcpp 2026.9.12.3+)* | 布尔 | `-fexceptions`，只在 `os = "emscripten"` 上，经方言 flag 进入编译行，也进入链接行；在其余每个目标上什么都不产生，因为那里异常本来就是默认开启的 | 与 `threads` 相同的那一套 |
 
-两个成员都经由方言 flag 进入依赖缓存键,因此未启用某个成员时构建的依赖不会被启用它的构建复用。未知
-成员,以及不是布尔值的成员,都会被拒绝,并同时列出 `threads` 与 `exceptions`。
+两个成员都经由方言 flag 进入依赖缓存键，因此没有启用某个成员的构建，不会
+被启用它的构建复用。未知成员，以及不是布尔值的成员，都会被拒绝，并同时
+列出 `threads` 与 `exceptions`。
 
-**没有 `exceptions`,观察到的失败在运行时,不在链接时。** 一个跨 `import std` 边界抛出异常的 Web
-程序能正常编译并链接——Emscripten 的编译期异常支持不依赖这个 flag——只在 `throw` 真正执行时中止:
+**没有 `exceptions`，观察到的失败在运行时，不在链接时。** 一个跨
+`import std` 边界抛出异常的 Web 程序能正常编译并链接——Emscripten 的
+编译期异常支持不依赖这个 flag——只在 `throw` 真正执行时中止：
 
 ```
 Aborted(Assertion failed: Exception thrown, but exception catching is not
@@ -900,18 +978,20 @@ enabled. Compile with -sNO_DISABLE_EXCEPTION_CATCHING or
 -sEXCEPTION_CATCHING_ALLOWED=[..] to catch.)
 ```
 
-**只有根 manifest 做决定。** 这个开关属于产物,而根包是唯一构建产物的包。依赖写下的
-`[target.<selector>.abi]` 会被报告(`abi/dependency-table`),且不改变任何东西。依赖改为声明自己的需求:
+**只有根 manifest 能做决定。** 这个开关属于产物，而根包是唯一构建产物的
+包。依赖写下的 `[target.<selector>.abi]` 会被报告
+（`abi/dependency-table`），且不改变任何东西。依赖改为声明自己的需求：
 
 ```toml
 [package]
-requires_abi = { threads = true }          # 整个包需要线程
+requires_abi = { threads = true }          # the package needs threads
 
 [features]
-mt = { requires_abi = { threads = true } } # 只有这个 feature 需要线程
+mt = { requires_abi = { threads = true } } # only this feature needs them
 ```
 
-根包未满足的需求在任何编译开始之前被拒绝,拒绝信息指出包名以及提出需求的对象:
+根包未满足的需求在任何编译开始之前就被拒绝，拒绝信息指出包名以及提出
+需求的对象：
 
 ```
 error: `wasmrt` requires the artefact's ABI to have threads (feature `mt`), and this build does not state it.
@@ -921,29 +1001,31 @@ error: `wasmrt` requires the artefact's ABI to have threads (feature `mt`), and
            threads = true
 ```
 
-若没有这项拒绝,不匹配会表现为预编译模块的配置错误,而该错误既不指出包,也不指出开关。
+若没有这项拒绝，不匹配会表现为一个预编译模块的配置错误，而该错误既不指出
+包，也不指出开关。
 
-### `requires_abi` 在 target 轴上(mcpp 2026.9.12.3+)
+### `requires_abi` 在 target 轴上（mcpp 2026.9.12.3+）
 
-`[package] requires_abi` 与 `[features.<f>] requires_abi` 是无条件的:它们要求
-本包构建的每一个目标都打开某个开关。一个需求局限于某个平台的依赖——比如每个
-hosted 行都要线程、Web 上一个都不要——直接写在已经承载它自己 `sources` 的
-选择器上:
+`[package] requires_abi` 与 `[features.<f>] requires_abi` 是无条件的：
+它们要求本包构建的每一个目标都打开某个开关。一个需求局限于某个平台的
+依赖——比如每个 hosted 行都要线程、Web 上一个都不要——直接写在已经承载
+它自己 `sources` 的选择器上：
 
 ```toml
 [target.'cfg(linux)']
 requires_abi = { threads = true }
 
-# 按 feature 的形式,命名沿用 feature-deps 与 feature-xlings
+# the per-feature form, named after feature-deps and feature-xlings
 [target.'cfg(linux)'.feature-requires-abi]
 mt = { threads = true }
 ```
 
-需求集合是 `[package] requires_abi`、活跃 feature 各自的表、以及每一个命中的
-选择器各自表的并集——不止一个选择器可以要求同一个成员,而它们各自都是真话。
-它只对**命中已解析目标**的选择器生效:`[target.'cfg(windows)']` 下的需求对
-一次 Linux 构建不施加任何东西,双向皆然——有它、没它,那次构建都不受影响。
-根包未满足的需求在任何编译开始之前被拒绝,拒绝信息按原样点名那个选择器:
+需求集合是 `[package] requires_abi`、活跃 feature 各自的表、以及每一个
+命中的选择器各自表的并集——不止一个选择器可以要求同一个成员，而它们各自
+都是真话。它只对**命中已解析目标**的选择器生效：`[target.'cfg(windows)']`
+下的需求对一次 Linux 构建不施加任何东西，双向皆然——有它、没它，那次构建
+都不受影响。根包未满足的需求在任何编译开始之前就被拒绝，拒绝信息按原样
+点名那个选择器：
 
 ```
 error: `wasmrt` requires the artefact's ABI to have threads ([target.'cfg(linux)']), and this build does not state it.
@@ -953,20 +1035,22 @@ error: `wasmrt` requires the artefact's ABI to have threads ([target.'cfg(linux)
            threads = true
 ```
 
-**早于 2026.9.12.3 的引擎静默读过这个键——既不警告,也不报错。**
-`[target.<sel>] requires_abi` 是目标选择器下一个取值为表的键,而旧引擎的
-schema 清扫会跳过每一个取值为表的键,理由是它假定表就是条件通道;
-`requires_abi` 在这里恰好是一个内联表,与那个假定同一种 TOML 形状,于是
+**早于 2026.9.12.3 的引擎静默读过这个键——既不警告，也不报错。**
+`[target.<sel>] requires_abi` 是目标选择器下一个取值为表的键，而旧引擎的
+schema 清扫会跳过每一个取值为表的键，理由是它假定表就是条件通道；
+`requires_abi` 在这里恰好是一个内联表，与那个假定同一种 TOML 形状，于是
 不受任何报告地漏过同一次清扫。一个依赖这份拒绝来保护一次无条件线程构建的
-包,因此要自己声明引擎下限
-(`[build-dependencies.mcpp] version = ">= 2026.9.12.3"`),而不能指望旧客户端
-自己发现这个缺口。
+包，因此要自己声明引擎下限
+（`[build-dependencies.mcpp] version = ">= 2026.9.12.3"`），而不能指望
+旧客户端自己发现这个缺口。
 
-`--no-entry`(Emscripten 里没有 `main` 的模块用的 flag)不是 mcpp 解释的开关;
-它是一条普通的 `[target.'cfg(os = "emscripten")'.build] ldflags` 条目,`main`
-照样只是指出一个翻译单元——见[21 —— 目标三元组](21-the-target-triple.md#wasm-产物契约)。
+`--no-entry`（Emscripten 里没有 `main` 的模块用的 flag）不是 mcpp
+解释的开关；它是一条普通的
+`[target.'cfg(os = "emscripten")'.build] ldflags` 条目，`main` 照样只是
+指出一个翻译单元——见
+[21 —— 目标三元组](21-the-target-triple.md#wasm-产物契约)。
 
-### `targets.<name> kind` —— 一个库在某一行上的形态(mcpp 2026.9.14.2+)
+### `targets.<name> kind` —— 一个库在某一行上的形态（mcpp 2026.9.14.2+）
 
 ```toml
 [targets.huxerui]
@@ -976,28 +1060,32 @@ kind = "lib"
 kind = "shared"
 ```
 
-`[targets.<name>] kind` 的按行形式([04 —— mcpp.toml](04-mcpp-toml.md) §2.2)。
-在桌面各行上链接进应用、在 Android 上必须是唯一一份共享库的框架,在它自己的清单里
-声明一次;每个消费者都只保留一行无条件依赖。
-
-- 一行陈述 `kind`,在两种库形态 `lib` 与 `shared` 之间选择;或者 *(2026.9.15.2+)*
-  陈述 `linkage`,给出该库在这些行上的默认形态而不约束它。同一行同时写两者会被拒绝,
-  后命中的陈述替换先前的陈述,包括无条件表中的陈述。不是该包库目标(声明的或推断的)
-  的名字、程序目标以及其他形态都被拒绝。
-- 在命中的行上,该包被约束为共享形态,与 `[targets.<name>] kind = "shared"`
-  的约束完全相同([04 —— mcpp.toml](04-mcpp-toml.md) 中的 `dependency_linkage`):
-  不写 `linkage` 的消费者得到共享库,写 `linkage = "static"` 的消费者得到一条点名
-  这一行的警告,`--strict` 下成为错误。`mcpp why deps` 以原因 `row-kind` 报告该形态。
-  某行的 `linkage = "shared"` 让不写 `linkage` 的消费者得到共享库,原因为
-  `package-default`;对消费者的 `linkage = "static"` 予以遵从,给出信息行而不是警告。
-- 点名目标侧层的选择器不能承载这张表;该表被报出并忽略,因为库的形态是在解析
-  回答该层的那张图时决定的。
-- 2026.9.14.2 之前的引擎不读取这张表,也不报告。依赖它的包要写明这一引擎下限。
+`[targets.<name>] kind` 的按行形式（[04 —— mcpp.toml](04-mcpp-toml.md)
+§2.2）。在桌面各行上链接进应用、在 Android 上必须是唯一一份共享库的框架，
+在它自己的清单里声明一次；每个消费者都只保留一行无条件依赖。
+
+- 一行陈述 `kind`，在两种库形态 `lib` 与 `shared` 之间选择；或者
+  *(2026.9.15.2+)* 陈述 `linkage`，给出该库在这些行上的默认形态而不约束
+  它。同一行同时写两者会被拒绝，后命中的陈述替换先前的陈述，包括无条件
+  表中的陈述。既不是该包库目标（声明的或推断的）、也不是程序目标、
+  也不属于其他形态的名字都会被拒绝。
+- 在命中的行上，该包被约束为共享形态，与
+  `[targets.<name>] kind = "shared"` 的约束完全相同（[04 —— mcpp.toml](04-mcpp-toml.md)
+  中的 `dependency_linkage`）：不写 `linkage` 的消费者得到共享库，写
+  `linkage = "static"` 的消费者得到一条点名这一行的警告，`--strict` 下
+  成为错误。`mcpp why deps` 以原因 `row-kind` 报告该形态。某行的
+  `linkage = "shared"` 让不写 `linkage` 的消费者得到共享库，原因为
+  `package-default`；对消费者的 `linkage = "static"` 予以遵从，给出信息行
+  而不是警告。
+- 点名目标侧层的选择器不能承载这张表；该表被报出并忽略，因为库的形态是
+  在解析出回答该层的那张图时决定的。
+- 2026.9.14.2 之前的引擎不读取这张表，也不报告。依赖它的包要写明这一
+  引擎下限。
 
 ## 当前边界
 
-- **依赖不能以加速器为条件。** 加速器这一层是从依赖图解析出来的,因此由它选择的依赖
-  会决定它自己在问的那个答案。mcpp 会报告该谓词并忽略它;包要么无条件、要么以平台为
-  条件,而由加速器选择的是 `[build] sources`。
-- 一般而言,层也不能选择依赖,理由相同:任何早于图的推导,都是在推断一个尚不存在的
-  事实。
+- **依赖不能以加速器为条件。** 加速器这一层是从依赖图解析出来的，因此由它
+  选择的依赖会决定它自己正在问的那个答案。mcpp 会报告该谓词并忽略它；
+  包要么无条件，要么以平台为条件，而由加速器选择的是 `[build] sources`。
+- 一般而言，层也不能选择依赖，理由相同：任何早于图的推导，都是在推断一个
+  尚不存在的事实。
diff --git a/docs/zh/23-the-project-environment.md b/docs/zh/23-the-project-environment.md
index 813aa10f8..89334f5a0 100644
--- a/docs/zh/23-the-project-environment.md
+++ b/docs/zh/23-the-project-environment.md
@@ -1,15 +1,16 @@
 # 23 —— 项目环境
 
-**读者:**构建需要「编译器之外的工具」的作者。
+**读者：** 构建需要编译器之外工具的作者。
 
-**本章回答的那一个问题:**工程怎样声明它的构建所处的环境,以及这条声明决定什么。
+**本章回答的那一个问题：** 工程如何声明其构建运行的环境，以及该声明决定什么。
 
-**不在这里:**构建程序拿这些工具做什么,那是 [30 —— 构建程序](30-build-mcpp.md);
-以及选择编译器,那是 [20 —— 工具链管理](20-toolchains.md)。
+**不在这里：** 构建程序如何使用这些工具，见
+[30 —— 构建程序：`build.mcpp`](30-build-mcpp.md)；选择编译器，见
+[20 —— 工具链管理](20-toolchains.md)。
 
-项目可以声明自己在哪个环境里构建。这一条声明决定项目链接哪个 C 库、以及它的
-构建程序找到哪些工具——于是同一份 `mcpp.toml` 在开发机和 CI 上是同一个构建,
-不论这两台机器上还装了别的什么。
+工程可以声明自己构建所在的环境。这一条声明决定工程链接哪一份 C 库、
+构建程序能找到哪些工具——因此同一份 `mcpp.toml` 在开发者的笔记本上和在 CI 上
+是同一次构建，无论这两台机器上还装了别的什么。
 
 ```toml
 [xlings]
@@ -19,235 +20,249 @@ subos = "tools"
 "xim:qemu-riscv" = "9.2.4-1"
 ```
 
-可运行的工程:`examples/07-project-subos/`。
+可运行的工程：`examples/07-project-subos/`。
 
 ## 1. SubOS 的定义
 
-SubOS 是一个目录,里面是一份用户态:它自己的 `bin`、自己的库视图、自己那套已
-装包版本,以及一个自述用的 `subos_info` 块。mcpp 把它当作「这个项目对着什么
-构建」的答案,而且是回答这个问题的唯一机制——不是编译器所在路径,不是
-`XLINGS_ACTIVE_SUBOS`,也不是当前 shell。
+SubOS 是一个承载用户空间的目录：它有自己的 `bin`、自己的库视图、自己安装的
+包版本，以及一个描述自身的 `subos_info` 块。mcpp 把它当作「本工程针对什么构建」
+这一问题的答案，而且它是回答这一问题的唯一机制——不是编译器的路径，
+不是 `XLINGS_ACTIVE_SUBOS`，也不是 shell。
 
-存在两种,区别在于目录落在哪里:
+存在两种形态，差别在于目录所在的位置：
 
 | 声明 | 目录 | 共享范围 |
 |---|---|---|
-| 未声明 | mcpp 初始化的 `subos/default` | 机器上的每个项目 |
-| `subos = "default"` | 同一个目录,只是被显式点名 | 机器上的每个项目 |
+| 不声明 | mcpp 初始化的 `subos/default` | 这台机器上的每个工程 |
+| `subos = "default"` | 同一目录，显式点名 | 这台机器上的每个工程 |
 | `subos = "<name>"` | `<project>/.mcpp/.xlings/subos/<name>/` | 不共享 |
 
-第三行是隔离的那种。它属于该项目,就放在清单旁边,删掉项目它也随之消失。
+第三行是隔离的那一种。它属于工程本身，与 manifest 放在一起，
+删除工程也就删除了它。
 
 ## 2. 这条声明的决定范围
 
-**C 库。** payload-first 的构建链接的是某一个确定的 glibc,而「哪一个」是项目
-的性质而非机器的性质。第 8 章讲绑定本身、降级规则,以及一个不自述的 SubOS 会
-让这些规则变成什么。
+**C 库。** 一次 payload-first 构建链接的是某一份具体的 glibc，
+是哪一份是关于工程的事实，而不是关于机器的事实。第 8 章讲述这项绑定、
+它的降级规则，以及一个不描述自身的 SubOS 对它们的影响。
 
-**构建程序看见哪些工具**(mcpp 2026.8.25.1+)。被声明环境的 `bin` 放在
-`build.mcpp` 运行时 `PATH` 的最前面:
+**构建程序能看到的工具**（mcpp 2026.8.25.1+）。声明的环境的 `bin` 被放到
+`build.mcpp` 运行时所用 `PATH` 的最前面：
 
 ```
-PATH=<被声明环境的 bin>:<mcpp 自己启动时的 PATH>
+PATH=<the declared environment's bin>:<the PATH mcpp itself was started with>
 ```
 
-因此构建程序里把 `qemu-system-riscv64` 写成裸名,拿到的就是那个环境里的副本。
-这条通道的契约见第 7 章。
+因此，构建程序写下裸名 `qemu-system-riscv64` 时，拿到的是声明环境内的那一份。
+第 7 章讲述这一点所依赖的契约。
 
-**只对声明了的项目生效。** 没有 `[xlings].subos` 的项目拿到的是 mcpp 启动时
-的 `PATH`,逐字节不变。把一个共享目录放到每个项目前面,会让「构建看见什么」
-取决于这台机器上还装过什么——同一台机器上的两个项目彼此一致,而同一个项目在
-两台机器上不一致。是声明本身把它放到了前面。
+**只对声明了环境的工程生效。** 没有 `[xlings].subos` 的工程拿到的 `PATH`
+与 mcpp 被启动时的 `PATH` 逐字节相同。把一个共享目录放在每个工程前面，
+会让一次构建看到的内容取决于这台机器上还装了别的什么——同一机器上的两个工程
+会彼此一致，而同一个工程在两台机器上却不会一致。声明它，才会把它放到那个位置。
 
-**前置而非替换。** 构建程序理应会调 `git`、`python3` 或 shell,这些都不在
-SubOS 里。前置让被声明的环境成为默认答案;其余的仍在它后面可达。
+**是前置，不是替换。** 构建程序合理地会调用 `git`、`python3` 或某个 shell，
+它们都不住在 SubOS 里。放在最前面只是让声明的环境成为默认答案；
+其余一切仍然可以在它后面被找到。
 
-### 2.1 生效的版本钉(2026.9.3+)
+### 2.1 生效的版本钉（2026.9.3+）
 
-指名一个环境,同时改变了工具的版本从哪来。工程自己 `[xlings.workspace]` 里的条目
-总是胜出;不同的是它们叠在什么之上:
+点名一个环境同时改变了工具版本的来源。工程自己 `[xlings.workspace]` 中的
+条目永远胜出——既胜过这里的环境，也按第 3 节的规则胜过依赖的声明——
+不同的是它们各自叠加在什么之上：
 
-| 工程声明了 | 它没点名的工具,版本来自 |
+| 工程的声明 | 它未点名的工具，其版本来自 |
 |---|---|
-| `[xlings.workspace]`,无 `subos` | 机器的环境 |
-| `[xlings.workspace]` 与 `subos = "<名>"` | 那个环境自己的 workspace;机器的不适用 |
+| `[xlings.workspace]`，不带 `subos` | 机器自身的环境 |
+| `[xlings.workspace]` 且 `subos = "<name>"` | 该环境自己的 workspace；机器的不生效 |
 
-第二行就是隔离的含义。指名的环境有自己的已安装集合,把机器的版本带进去会指向那里
-不存在的版本 —— 所以原本依赖「机器上装了就能用」的工程,一旦指名环境,就必须把用到
-的都声明出来。
+第二行就是「隔离」的含义。一个具名环境有它自己已安装的集合，
+把机器的版本带进去只会点名一些根本不在那里的版本——因此工程一旦点名一个环境，
+就必须重新声明它原本依赖机器所提供的工具。
 
-在工程内执行的 `xlings use` 压过这两者,直到 mcpp 重写环境为止:它是最后合并的那
-一层,而人做出的动作应当压过一份文件。
+在工程内部执行的一次 `xlings use` 优先于以上两者，直到 mcpp 重写该环境为止：
+它是最后被合并的一层，而一个人主动做出的动作理应胜过一份文件。
 
 ## 3. 这条声明不决定的部分
 
-`[xlings.workspace]` 声明的是「环境里要有哪些包」,而每个包的载荷目录另有通道交付,
-即 `MCPP_XPKG_<NAME>_DIR`。这与 `PATH` 是两个问题,答案也保持分开:需要某个包
-的数据文件(比如 protoc 自带的 well-known `.proto`)的构建程序问目录,需要
-**运行**某个程序的构建程序问 `PATH`。
+`[xlings.workspace]` 点名环境中应当存在的包，而每个包的 payload 目录会
+另行以 `MCPP_XPKG_<NAME>_DIR` 的形式交付。这是与 `PATH` 不同的问题，
+答案也不同：需要一个包的数据文件（比如 protoc 内置的那些 `.proto` 文件）的
+构建程序去问目录，需要*运行*一个程序的构建程序去问 `PATH`。
 
-**工作区成员的声明不是工作区的声明。** 工作区构建中由工作区根持有这个选择;成员的
-`[xlings]` 只在该成员作为独立根被构建时生效。
+**workspace 成员的声明不是 workspace 的声明。** 在一次 workspace 构建中，
+workspace 根拥有这项选择；一个成员自己的 `[xlings]` 只在该成员作为独立的根
+被构建时才生效。
 
-**依赖的声明是另一回事,而且它被采纳**(`[xlings] deps` 自 2026.9.5.4,下面那条版本
-规则自 2026.9.6.6)。板级支持包知道哪个模拟器够得到它那台机器,规则包知道它驱动哪个
-工具包;要消费者把这些再写一遍,正是这类包存在的意义所反对的重复。依赖声明的东西会被
-装上,而 `MCPP_XPKG_<NAME>_DIR` 在那个依赖自己的构建程序里为它作答。
+**依赖的声明是另一回事，它会被采纳**（`[xlings] deps` 自 2026.9.5.4+，
+下述版本规则自 2026.9.6.6）。一个板级支持包知道哪个模拟器能到达它的机器，
+一个规则包知道自己的规则驱动哪套工具集；消费方若被迫重复其中任何一项，
+正是这类包存在的意义所要去除的重复。依赖所声明的内容会被安装，
+`MCPP_XPKG_<NAME>_DIR` 在该依赖自己的构建程序里为它给出答案。
 
-工程与依赖命名**同一个包**时,只装它的一个版本:身份是 `(namespace, name)`,版本是这个
-包上的约束。离产物更近的声明赢,并且覆盖会被报出来;不满足对方所陈述之要求的钉会被拒绝
-并点出两侧。见 [23 — The Project Environment](23-the-project-environment.md) 的「一个包一个版本」。
+当工程与依赖点名**同一个包**，安装的是它的一个版本：身份是
+`(namespace, name)`，版本是施加于其上的约束。离产物更近的声明胜出，
+且覆盖会被报告；不满足对侧所陈述要求的一个 pin 会被拒绝，并同时指出两侧。
+参见本章「一个包一个版本」一节。
 
-## 4. 只读取环境,从不创建环境
+## 4. 只读取环境，从不创建环境
 
-mcpp 解析被声明的名字,并读取它找到的东西。解析不到的名字是硬失败:
+mcpp 解析一个声明的名字，并读取它找到的内容。一个解析不出的名字是硬错误：
 
 ```
 error: selected SubOS 'tools' does not exist at …/.mcpp/.xlings/subos/tools;
 create/bootstrap that environment instead of falling back to active/default
 ```
 
-回退到 default 或回退到当前活跃的那个,等于用另一个环境顶替清单点名的那个,而
-这恰恰会让一份 `mcpp.toml` 意味着两个不同的构建。创建并填充 SubOS 属于 xlings
-这一层——`xlings subos new`——mcpp 去管理 SubOS 状态则是把分层倒置。
+回落到默认环境或当前激活的环境，等于用另一个环境替换 manifest 点名的那一个，
+而这恰恰会让同一份 `mcpp.toml` 意味着两次不同的构建。创建并填充一个 SubOS
+是 xlings 那一层的事——`xlings subos new`——由 mcpp 去管理 SubOS 的状态
+会颠倒这层分工。
 
-一个存在但**不携带 `subos_info` 块**的环境是**降级而非失败**:运行时绑定报
-`inconclusive`,没有 payload-first 绑定可用,打印一条提示,构建继续。完整规则见
-第 8 章。
+一个存在、却不带 `subos_info` 块的环境**降级而非失败**：运行时绑定报告
+`inconclusive`，没有 payload-first 绑定可用，打印一条提示，构建继续进行。
+第 8 章给出完整规则。
 
 ## 5. 采用私有环境的条件
 
-- **产物取决于版本的代码生成器。** `protoc`、`flatc`、着色器编译器:它的输出是
-  下游一切的输入,所以项目钉住生产者,而不是指望机器上那个恰好兼容。
-- **构建程序要运行的模拟器。** 若干裸机包把「在 QEMU 里启动产物」作为验证的一
-  部分;是哪个 QEMU 属于「验证了什么」的一部分。
-- **CI 与开发机不一致的项目**,两边都没错,而构建不该察觉到差异。
-- **同一台机器上两个项目需要同一工具的不同版本。** 共享目录意味着必有一方落
-  败;私有环境让这个问题不成立。
-
-代价一侧:隔离环境是一个必须被创建并填充的目录,而这笔账由首次构建来付。
-2026.8.29 起 mcpp 会做这件事 —— 声明在 `[xlings.workspace]` 里的包在首次使用时被供给,
-一个尚不存在的具名 `[xlings] subos` 会被创建而不是被拒绝 —— 但代价是实打实的:
-干净机器上的第一次构建会先下载安装,然后才编译。工具很普通、版本也无所谓的项目,
-不声明、直接继承机器的那份更划算。
-
-在 `--offline` / `MCPP_OFFLINE` 或 `MCPP_NO_AUTO_INSTALL` 下,mcpp 转为拒绝而不是
-安装,并列出包名以便手动供给 —— 与 `[toolchain]` 遵守的是同样两个开关,理由也相同:
-一次没被要求的下载,不该由构建替工程决定。
-
-这份声明在每台构建本工程的宿主上都会供给,宿主装不了的包是错误,不是被跳过的条目。
-只存在于某一个宿主平台的工具因此按平台声明(2026.9.2.1):
-`deps = [{ linux = "qemu-user-aarch64" }]` 在 Linux 上声明这个模拟器,在别处什么都不声明。
-键与解析规则见本章。
-
-**哪些命令会安装它。** 一条条目可以带档位 —— `{ version = "0.24.0", when = "run" }` ——
-`[feature-xlings.<feature>]` 则把工具挂在某个 feature 上。用不到的工具因此不会被下载:
-见本章。不写档位就是从前的行为。
-
-**runner。** `[xlings.workspace]` 下的程序也是 `[target.<triple>].runner` 查找其第一个元素
-的首选位置,在 `PATH` 之前([04 §2.7.3](04-mcpp-toml.md))。两个键合起来,在 CI 宿主上供给用户态模拟器,
-并通过它执行交叉构建的产物,而清单不必写出载荷的路径。
+- **一个版本会改变其产出的生成器。** `protoc`、`flatc`、某个着色器编译器：
+  它的输出是下游一切的输入，因此工程钉住这个产生者的版本，而不是寄望机器上
+  恰好装着一份兼容的。
+- **构建程序运行的模拟器。** 若干裸机包把产物启动在 QEMU 之下，
+  以此作为证明产物可用的一部分；用的是哪个 QEMU，也是被证明的内容之一。
+- **CI 与开发者机器不同的工程**，二者都没有错，而构建不应察觉这种不同。
+- **同一台机器上两个工程需要同一工具的不同版本。** 共享一个目录意味着
+  其中一个工程要吃亏；私有环境让这个问题根本不出现。
+
+反过来看：一个隔离的环境是一个必须被创建并填充的目录，代价由第一次构建承担。
+自 2026.8.29 起，mcpp 负责这项工作——一个声明的 `[xlings.workspace]` 条目
+在第一次用到时被置备，一个尚不存在的具名 `[xlings] subos` 被创建而不是被拒绝——
+但代价是真实的：干净机器上的第一次构建，会在编译任何东西之前先下载并安装。
+一个工具寻常、版本无关紧要的工程，更适合什么都不声明，直接继承机器的环境。
+
+在 `--offline` / `MCPP_OFFLINE` 或 `MCPP_NO_AUTO_INSTALL` 之下，mcpp 拒绝而非
+安装，并点名这些包以便离线置备——与 `[toolchain]` 所遵守的同两个开关，
+理由也相同：一次未被要求的下载，不是构建可以替工程做主的事。
+
+这条声明会在构建工程的每一台宿主上被置备，一个宿主装不上的包是错误，
+而不是被跳过的条目。因此只为一个宿主平台存在的工具要按平台声明
+（2026.9.2.1）：`deps = [{ linux = "qemu-user-aarch64" }]` 只在 Linux 上声明
+这个模拟器，在别处什么都不声明。相关的键与解析规则都在本章。
+
+**哪些命令会安装它。** 一个条目可以点名一个层级——
+`{ version = "0.24.0", when = "run" }`——`[feature-xlings.<feature>]` 表
+则把一个条目挂在某个 feature 上。工程用不到的工具就不会被下载：见本章。
+省略层级即为历史行为。
+
+**runner。** `[xlings.workspace]` 下的一个程序，也是
+`[target.<triple>].runner` 为它的第一个元素最先查找的地方，先于 `PATH`
+（[04 §2.7.3](04-mcpp-toml.md)）。这两个键合在一起，在 CI 宿主上置备一个
+用户态模拟器，并通过它执行一个交叉构建出的产物，而 manifest 不必点名该
+payload 的路径。
 
 ## 6. 应当写在别处的声明
 
-| 需求 | 写入位置 |
+| 需求 | 声明在 |
 |---|---|
-| 程序链接的库 | `[dependencies]` |
-| 编译器 | `[toolchain]`,第 3 章 |
-| 依赖产出的宿主工具 | `tools = [...]`,第 7 章 |
-| 环境里要有的工具 | `[xlings.workspace]` |
-| 只有某个命令或某个 feature 需要的工具 | `when = "run"`、`[feature-xlings.<f>]` |
-| 用哪个环境 | `[xlings] subos` |
+| 程序链接的一个库 | `[dependencies]` |
+| 编译器 | `[toolchain]`，第 3 章 |
+| 依赖产出的一个宿主工具 | `tools = [...]`，第 7 章 |
+| 环境中存在的一个工具 | `[xlings.workspace]` |
+| 只有某一个命令或某一个 feature 需要的工具 | `when = "run"`、`[feature-xlings.<f>]` |
+| 使用哪一个环境 | `[xlings] subos` |
 
 ## 7. `[xlings]` —— manifest 键
 
 ```toml
-[xlings.workspace]                 # 这个工程的环境里有什么
+[xlings.workspace]                 # what this project's environment contains
 cmake                    = "3.28"
-"xim:picolibc-riscv"     = "1.8.12"        # 带命名空间的包 —— 必须带引号
-code                     = ""              # 存在即可,版本不限
+"xim:picolibc-riscv"     = "1.8.12"        # a namespaced package - quotes required
+code                     = ""              # present; version unconstrained
 llvm                     = { macosx = "20", default = "22" }
 ```
 
 ```toml
 [xlings]
-subos = "dev"                      # 指名的隔离环境
+subos = "dev"                      # a named, isolated environment
 ```
 
-`[xlings]` 是 mcpp 对 **xlings local project 机制**的书写面:让一个目录拥有自己
-环境的那份项目 `.xlings.json`。子段名与含义都是那份文件的,mcpp 原样物化进
-`<project>/.mcpp/.xlings.json`,没有翻译层。
+`[xlings]` 是 mcpp 对**xlings 本地工程机制**的表面：即给一个目录赋予自己环境的
+那份工程 `.xlings.json`。子表的名字及其含义都来自那份文件，mcpp 不加任何转译层，
+把它们原样物化进 `<project>/.mcpp/.xlings.json`。
 
-**`[xlings.workspace]` 是唯一的表。** 一条条目写出工程用哪个包、用哪个版本。
-mcpp 既供给它——机器上没有就装,有就映射——也把它物化成解析用的钉,于是工程写下
-的版本就是它的工具解析到的版本。
+**`[xlings.workspace]` 是唯一的一张表。** 一个条目点名一个包，以及本工程使用它的
+版本。mcpp 置备它——机器上没有就安装，有就映射——并把它物化为一个解析 pin，
+使工程点名的版本正是其工具最终解析到的版本。
 
 ### 条目的形式
 
-| 形式 | 含义 |
+| 写法 | 含义 |
 |---|---|
 | `cmake = "3.28"` | 该版本 |
-| `llvm = "22"` | 已装的最高 `22.*`;版本前缀会被解析 |
-| `code = ""` | 存在即可,版本不限 |
-| `"xim:picolibc-riscv" = "1.8.12"` | 来自 `xim` 索引的包 |
-| `llvm = { macosx = "20", default = "22" }` | 按宿主平台 |
+| `llvm = "22"` | 已安装的最高 `22.*`；版本前缀可以解析 |
+| `code = ""` | 存在，版本不受约束 |
+| `"xim:picolibc-riscv" = "1.8.12"` | `xim` 索引中的一个包 |
+| `llvm = { macosx = "20", default = "22" }` | 按宿主平台区分 |
 
-**带命名空间的包写成 `"<命名空间>:<名字>" = "<版本>"`,引号必需** —— TOML 的裸键
-不能含冒号。这是**推荐形态,也是所有官方包使用的形态**:一条条目先点名一个包,
-再说用它的哪个版本,所以命名空间属于名字。
+**带命名空间的包写作 `"<namespace>:<name>" = "<version>"`，引号是必须的**——
+TOML 裸键不能包含冒号。这是推荐写法，也是每个官方包采用的写法：
+一个条目点名一个包，然后说明它的哪个版本，因此命名空间归属于名字。
 
-命名空间写在版本上(`picolibc-riscv = "xim:1.8.12"`)同样接受,因为物化出来的
-`.xlings.json` 里正是那种形态 —— 那里的键是 xvm target,scope 限定的是版本。
-两套词汇,同一条条目。两半都写且不一致是错误;同一个包用两种拼法出现两次也是错误。
+命名空间也可以写在版本那一侧（`picolibc-riscv = "xim:1.8.12"`），因为
+物化后的 `.xlings.json` 正是这样携带它的——那里的一个键是一个 xvm target，
+而 scope 限定了版本。两套词汇，一个条目。在两侧各写一次且值不同是错误，
+在两种拼法下重复点名同一个包也是错误。
 
-平台键是 xlings 自己的 —— `linux`、`macosx`、`windows`,外加 `default`。`macos`
-与 `macosx` 是同一个平台的两套词汇(mcpp 的三元组说前者,描述符与 xlings 的项目
-文件说后者),**凡是点名平台的地方两者都接受**。表里既没有本机这一项也没有
-`default`,就表示在这里什么都不声明。
+平台键是 xlings 自己的一套——`linux`、`macosx`、`windows`——加上 `default`。
+`macos` 与 `macosx` 是同一个平台的两种写法（mcpp 的三元组用其中一种，
+描述符与 xlings 的工程文件用另一种），两种写法在任何点名平台的地方都被接受。
+一张表若既没有对应这台宿主的键，也没有 `default`，就是在这里什么都不声明。
 
-### 两条解析轴 —— 宿主与目标(mcpp 2026.9.6.4+)
+### 两条解析轴 —— 宿主与目标（mcpp 2026.9.6.4+）
 
-一条工具条目回答的是两个不同问题中的一个,写在哪张表里决定了是哪一个:
+一个工具条目回答两个不同问题中的一个，由写它的那张表决定回答哪一个：
 
-| 写法 | 轴 | 解析依据 |
+| 写法 | 轴 | 解析对象 |
 |---|---|---|
-| `[xlings.workspace]`,平台键写在值里 | 宿主 | 跑这次构建的机器 |
-| `[target.<selector>.xlings.workspace]` | 目标 | 解析后的目标(`--target`,否则是宿主) |
+| `[xlings.workspace]`，取值中的平台键 | 宿主 | 运行构建的机器 |
+| `[target.<selector>.xlings.workspace]` | 目标 | 已解析的目标（`--target`，否则是宿主） |
 
-两种写法都是正确的,谁也不取代谁。在构建机上执行的工具属于宿主轴;产物编译或链接
-时对着的载荷属于目标轴。
+两种写法都正确，谁也不取代谁。在构建机器上执行的工具属于宿主轴；
+被产出代码编译或链接所依赖的 payload 属于目标轴。
 
 ```toml
 [xlings.workspace]
-"xim:dpcpp" = "7.1.0"              # 一个编译器,它在本机上跑
+"xim:dpcpp" = "7.1.0"              # a compiler, and it runs here
 
 [target.'cfg(os = "linux")'.xlings.workspace]
-"xim:glibc"         = ""           # 设备单元编译时对着的东西
+"xim:glibc"         = ""           # what the device units are compiled against
 "xim:linux-headers" = ""
 ```
 
-非交叉构建时两条轴指向同一个平台,所以把目标事实写在宿主轴上的工程是碰巧正确的,
-而且照常工作。它在第一次被交叉构建时不再正确。**凡是产物编译或链接时对着的东西,
-推荐写在目标轴上。**
+在一次原生构建中，两条轴点名的是同一个平台，因此在宿主轴上陈述目标事实的工程
+碰巧是对的，并且能照常工作。这个工程第一次被交叉编译时，它就不再是对的了。
+**对被产出代码所编译或链接依赖的任何东西，目标轴是推荐写法。**
 
-`[target.<selector>.feature-xlings.<feature>]` 把条件与门组合起来,与
-`[target.<selector>.feature-deps.<feature>]` 同形:selector 说的是哪些目标,
-feature 说的是要不要。
+`[target.<selector>.feature-xlings.<feature>]` 把条件与开关组合起来，
+写法与 `[target.<selector>.feature-deps.<feature>]` 完全一致：
+选择器说明适用于哪些目标，feature 说明是否启用。
 
 ```toml
 [target.'cfg(os = "linux")'.feature-xlings.backend-vulkan]
 "xim:shaderc" = "2026.3"
 ```
 
-**这里的 selector 禁止命名被解析的层。** `c-abi`、`c++-abi`、`compiler`、
-`compiler-runtime`、`kernel-abi` 由依赖解析回答,而依赖解析发生在工具安装之后、
-构建程序运行之后。按这些层条件化的工具会被声明却永远装不上——构建照常成功,工具
-就是不在——所以这样的 manifest 会被拒绝,并把工具与谓词都点出来。改成按目标条件化,
-或者用 feature 做门:`[feature-xlings.<feature>]` 在任何东西被供给之前就已知。
+**这里的选择器不能点名一个已解析的层。** `c-abi`、`c++-abi`、`compiler`、
+`compiler-runtime` 与 `kernel-abi` 都由依赖解析回答，而依赖解析发生在工具
+安装完成、构建程序运行完成之后。以某一层为条件的工具会被声明，却永远不会被
+安装——一次成功的构建里那个工具干脆缺席——因此这样的 manifest 会被拒绝，
+并同时指出工具和该谓词。请改为以目标为条件，或以 feature 为开关：
+`[feature-xlings.<feature>]` 在任何东西被置备之前就已经确定。
 
-**`accelerator` 是例外,它被接受**(mcpp 2026.9.6.5)。它不由任何东西解析而来:
-它是 `--accel`,或 `[build] accel`,在查找第一个包之前就已读入。以它为谓词的载荷
-与三元组谓词在同一趟合并,并像其它载荷一样被安装。
+**`accelerator` 是例外，它被允许使用**（mcpp 2026.9.6.5）。它不是从任何东西
+解析出来的：它就是 `--accel`，或者 `[build] accel`，在第一个包被查找之前
+就已经读出。以它为条件的 payload，与三元组谓词在同一趟合并中被合并，
+并像其他任何条目一样被安装。
 
 ```toml
 [target.'cfg(accelerator = "cuda")'.xlings.workspace]
@@ -255,16 +270,16 @@ feature 说的是要不要。
 "xim:cuda-cudart" = "12.9.79"
 ```
 
-带设备孤岛的工程应当用这种写法。没有它,厂商工具包只能无条件声明或者干脆不声明,
-于是不带加速器的 `mcpp build`——最便宜的那次构建,也是 CI 通常跑的那次——会为一个
-它根本没在编译的设备下载数 GB。
+带设备孤岛的工程应当使用这种写法。没有它，厂商工具集就只能被无条件声明，
+或者干脆不声明，于是不带加速器的 `mcpp build`——最廉价的一种构建，
+也是 CI 通常跑的那一种——会为一个它根本没有在为之编译的设备下载数 GB 内容。
 
-依赖同理:`[target.'cfg(accelerator = "cuda")'.dependencies]` 生效,而以被解析的层
-为条件的依赖不生效,因为后者会决定它正在询问的那个答案。加速器这条路径上没有任何
-循环。
+同一条规则也适用于依赖：`[target.'cfg(accelerator = "cuda")'.dependencies]`
+会被采纳，而以一个已解析的层为条件的依赖不会，因为后者会替自己正在问的那个
+问题决定答案。加速器身上没有任何循环。
 
-条件只写在 selector 一处。selector 之下的值如果又带平台键,就是同一件事说了两遍,
-会被拒绝,并把两半都指出来:
+条件只能写在选择器上。一个同时携带平台键的选择器下的取值，
+是把同一件事说了两遍，会被拒绝，并同时指出两侧：
 
 ```
 [target.cfg(os = "linux").xlings.workspace] xim:tool: the value carries platform
@@ -272,50 +287,54 @@ keys (linux, macosx), but [target.cfg(os = "linux")] already says which targets
 this applies to.
 ```
 
-`subos` 不按目标条件化:一个工程只有一个环境,所以 `[target.<selector>.xlings]`
-拒绝这个键,而不是把它丢掉。
+`subos` 不能以目标为条件：一个工程只有一个环境，因此
+`[target.<selector>.xlings]` 直接拒绝这个键，而不是丢弃它。
 
-**已发布的描述符一般不为目标轴条目携带边**,`mcpp publish` 会说明这一点。描述符按
-平台分块,大多数 selector 不是平台 —— `cfg(target_arch = "aarch64")` 不对应那份文件
-里的任何一块。**但只命名一个操作系统的 selector 就是平台**:`cfg(linux)`、
-`cfg(os = "linux")` 以及 windows/macos/unix 的对应写法,会被并入相应的
-`xpm.<platform>.deps` 块,而不只是给出提示。除此之外,**使用者**装到的东西来自顶层
-`[xlings.workspace]`;目标轴对"本包自己的构建对着什么"仍然是正确的。
+**一份已发布的描述符，通常不为目标轴的条目携带任何边**，`mcpp publish`
+会说明这一点。描述符按平台各有一个块，而大多数选择器都不是一个平台——
+`cfg(target_arch = "aarch64")` 点不到该文件里的任何一个块。**但只点名一个
+操作系统的选择器就是一个平台**:`cfg(linux)`、`cfg(os = "linux")`
+以及 windows/macos/unix 的等价写法，会折叠进对应的
+`xpm.<platform>.deps` 块，而不只是引发那条提示。这个包的**消费方**
+另外会安装什么，来自顶层的 `[xlings.workspace]`；目标轴对这个包自己的
+构建所编译依赖的内容，仍然是准确的。
 
-这两条轴所属的一般规则见 [SPEC-004](../specs/manifest-semantics.md)。
+这两条轴所属的一般规则，见 [SPEC-004](../specs/manifest-semantics.md)。
 
-### `when` —— 需要这个工具的命令(mcpp 2026.9.4.2+)
+### `when` —— 需要这个工具的命令（mcpp 2026.9.4.2+）
 
 ```toml
 [xlings.workspace]
-"xim:qemu-arm"   = "9.2.4-1"                             # 每次构建都装,与从前一样
-"xim:codegen"    = { version = "1.0",    when = "build" }
-"xim:probe-rs"   = { version = "0.24.0", when = "run"   }
-"xim:clang-tidy" = { version = "20",     when = "dev"   }
+"xim:qemu-arm"  = "9.2.4-1"                             # every build, as before
+"xim:codegen"   = { version = "1.0",    when = "build" }
+"xim:probe-rs"  = { version = "0.24.0", when = "run"   }
+"xim:clang-tidy"= { version = "20",     when = "dev"   }
 ```
 
-包依赖从一开始就有这条轴 —— `[dependencies]`、`[build-dependencies]`、
-`[dev-dependencies]`。工具只有一张表,于是一个同时点名模拟器与调试探针的板级支持包
-会把两个都装给每一位消费者,包括只想把库编出来的那一位。
+包依赖从一开始就有这条轴——`[dependencies]`、`[build-dependencies]`、
+`[dev-dependencies]`。工具却只有一张表，于是一个同时点名了一个模拟器和一个
+调试探针的板级支持包，会把两者都装给每一个消费方，包括那些只想编译这个库的。
 
-| `when` | 安装方 | 传播到消费者 |
+| `when` | 安装方 | 是否到达消费方 |
 |---|---|---|
-| *(不写)* | 每个构建命令 | 是 |
-| `build` | 每个构建命令 | 是 |
+| *（省略）* | 每一个执行构建的命令 | 是 |
+| `build` | 每一个执行构建的命令 | 是 |
 | `run` | `mcpp run`、`mcpp test` | 是 |
-| `dev` | 只有声明它的那个包作为根时 | **否** |
+| `dev` | 只有声明它的那个包，当它作为根时 | **否** |
 
-**不写 `when` 就是 2026.9.4.2 之前的行为**,所以没有任何清单需要改。收窄是可选动作,
-不是作者必须回答的新问题。
+**省略 `when` 就是 2026.9.4.2 之前的行为，完全一致**，因此没有任何 manifest
+需要为此改动。收窄是可选的，不是作者必须回答的问题。
 
-`dev` 是唯一不传播的一档。它的含义是「声明它的那个包自己在被开发时」,所以依赖的
-`dev` 条目永远不会为消费者安装。其余各档都会到达消费者 —— 这正是板级包知道自己机器
-的意义:它声明一次模拟器,每一位消费者都拿得到。
+`dev` 是唯一不传播的层级。它的含义是「*仅当声明它的这个包本身正在被开发时*」，
+因此一个依赖的 `dev` 条目永远不会为消费方安装。其余每个层级都会到达消费方，
+这正是板级支持包了解自己机器这件事的意义所在：它只声明一次模拟器，
+每个消费方都能拿到。
 
-档位写在**条目**上而不是另开一张表,理由与 `[dependencies]` 同时接受 `dep = "1.0"`
-和 `dep = { version = "1.0", features = [...] }` 是同一条。带档位的条目**必须**写出
-`version`,哪怕留空(`version = ""` 表示「存在即可,版本不限」)—— 否则
-`{ when = "run" }` 与写错的 `version` 键无法区分。
+层级写在条目本身而不是写成第二张表，理由与 `[dependencies]` 同时接受
+`dep = "1.0"` 和 `dep = { version = "1.0", features = [...] }` 相同。
+一个带作用域的条目必须点名 `version`，哪怕留空（`version = ""` 意为
+「存在，版本不限」)，因为 `{ when = "run" }` 与一个拼错的 `version` 键
+否则将无法区分。
 
 ### `[feature-xlings.<feature>]` —— 某个 feature 才需要的工具
 
@@ -329,60 +348,67 @@ hardware = {}
 "xim:probe-rs" = "0.24.0"
 ```
 
-同一张表,按 feature 门控,拼法沿用 `[feature-deps.<feature>]`。**不要 `hardware`
-的消费者永远不会下载探针驱动。** 这里的条目同样接受 `when`。
+同一张表，以 feature 为开关，写法与 `[feature-deps.<feature>]` 一致。
+一个从不要求 `hardware` 的消费方，永远不会下载探针驱动。这里的条目
+接受 `when`，与无条件条目完全一样。
 
-`[features]` 里没有声明过的 feature 名会作为 schema 警告报出:它对谁都不激活、什么
-都不装,而这种工具的缺席只表现为「设备就是连不上」,是最难诊断的一种。
+一个没有任何 `[features]` 表声明的 feature 名会被报成一条 schema 警告：
+它不为任何人激活，也不安装任何东西，而一个工具的缺席若只表现为
+「设备永远不可达」，那是最难诊断的一类问题。
 
-### 规则包自带它的环境(2026.9.6.6+)
+### 规则包自带它的环境（2026.9.6.6+）
 
-上面那张表是工程**有主张**时写的。多数工程没有主张,写下的也就是空无一物:
+上面这张表，是工程有主张时要写的内容。大多数工程没有主张，
+它们要写的就是什么都不写：
 
 ```toml
 [build-dependencies.mcpp]
 plugins = { version = "0.3.0", features = ["rules-cuda"], host-module = true }
 ```
 
-这一条边就是全部声明。规则包在选中它的那个 feature、它所服务的加速器之下,声明自己
-需要哪些包、最低到哪一版:
+这一条边就是全部的声明。规则包点名自己的规则需要哪些包、需要它们的哪个版本，
+挂在选中它的那个 feature 和它所针对的加速器之下：
 
 ```toml
-# 写在规则包里,不写在你的工程里
+# in the rule package, not in your project
 [target.'cfg(accelerator = "cuda")'.feature-xlings.rules-cuda]
 "xim:cuda-nvcc"   = ">=12.9.86"
 "xim:cuda-cudart" = ">=12.9.79"
 ```
 
-**两重门,都要开。** feature 说「要不要这个规则」,selector 说「哪些构建真的下载」。
-同一个工程的 CPU-only 构建两道门都不过,一个字节都不装。
+两道闸，都必须打开。feature 回答「是否需要这条规则」；选择器回答
+「究竟哪些构建真的会下载它」。同一工程的纯 CPU 构建两道闸都不打开，
+什么都不安装。
 
-「需要哪些包、最低到哪一版」是规则作者的知识。在每个用它的工程里重写一遍,是一份会
-悄悄过期的副本——规则动了,而那些工程不会跟着动。
+是哪个包、它可以有多旧，这是规则作者的知识。让每个使用这条规则的工程都
+重复一遍，得到的是一份会静默过期的拷贝——规则挪动了，而工程没有跟着动。
 
-### 一个包一个版本(2026.9.6.6+)
+### 一个包一个版本（2026.9.6.6+）
 
-工具地址是 `[<ns>:]<name>[@<版本>]`,它的**身份是 `(namespace, name)` 二元组**。版本是
-这个包上的约束,不是它名字的一部分,所以 `xim:glibc`、`xim:glibc@2.40` 与
-`xim:glibc@>=2.38` 指的是同一个包。**一次构建只装它的一个版本。**
+一个工具地址是 `[<ns>:]<name>[@<version>]`，它的**身份是
+`(namespace, name)` 这一对**。版本是施加在这个包上的约束，从来不是名字的
+一部分，因此 `xim:glibc`、`xim:glibc@2.40`、`xim:glibc@>=2.38` 点名的都是
+同一个包。每次构建安装它的一个版本。
 
-装哪一个,分两步决定。
+选哪一个，分两步决定。
 
-**裁决——离产物更近的声明赢。** 工程压过它依赖的包,于是一个钉覆盖规则的要求:
+**裁决——离产物更近的声明胜出。** 工程胜过它所依赖的一个包，
+因此一个 pin 会盖过某条规则的要求：
 
 ```toml
-# 工程侧,当它确实有主张时
+# the project, when it does have an opinion
 [target.'cfg(accelerator = "cuda")'.xlings.workspace]
 "xim:cuda-nvcc" = "13.3.33"
 ```
 
-**不带版本的声明弃权:** 它陈述了「要这个包」而没有陈述「要哪一版」,因此不会仅仅
-因为更近就压过一条下界。两条声明都带版本且不一致时,mcpp 会报出用了哪一条——一个
-只能表现为「声明了两个版本而目录里有一个」的覆盖,是要读者自己去文件系统里重建的
-事实。
+一个不点名版本的声明是弃权：它只说明这个包是需要的，对哪个版本什么都没说，
+因此它不能仅凭距离更近就压过一条下限。当两条声明彼此不一致、且都点名了
+版本时，mcpp 报告采用的是哪一个——一次仅表现为「声明了两个版本，
+而磁盘上只有一个目录」的覆盖，是一个读者要靠自己从文件系统里重建的事实。
 
-**校验——赢家必须满足每一条落败的要求。** `>=`、`^`、`~` 以及逗号组合是**要求**。
-不满足的钉被拒绝,并同时点出两侧:
+**校验——胜出者必须满足每一条落败的要求。** `>=`、`^`、`~`
+以及逗号组合的写法都是要求。一个不满足某条要求的 pin 会被拒绝，
+并同时指出两侧：
 
 ```
 error: `xim:cuda-nvcc` is pinned to 12.0.0 by this project, and mcpp:plugins
@@ -392,56 +418,59 @@ error: `xim:cuda-nvcc` is pinned to 12.0.0 by this project, and mcpp:plugins
        requirement decide.
 ```
 
-裸版本是**选择**而不是要求:两条互不相同的精确钉走裁决并被报告,不被拒绝。只有被
-陈述出来的要求才谈得上违反。
+一个裸版本是一次*选择*，不是一条要求：两个不同的精确 pin 会被裁决并报告，
+而不是被拒绝。只有一条被陈述的要求才能被违反。
 
-**这是一次比较,不是一次搜索。** 版本由裁决选定、再被检查,所以 mcpp 从不需要问索引
-「有哪些版本」,也就不带约束求解器。代价被写出来而不是藏起来:一个求解器本可满足的
-组合——工程写 `>=8.0`、规则写 `8.5.0`、而索引里最新是 8.3——会被拒绝,而拒绝消息里
-写着怎么往下走。
+**这是一次比较，不是一次搜索。** 版本先被裁决、再被校验，因此 mcpp
+从不需要去问索引存在哪些版本，也不携带约束求解器。代价被明说而不是被隐藏：
+一个求解器本可以满足的组合——工程的 `>=8.0`、规则的 `8.5.0`、索引中最新的
+是 8.3——会被直接拒绝，拒绝信息说明如何处理。
 
-范围在两个方向上都被求解。`>=2026.1` 装到满足它的最高已发布版本,`>=2099.1` 作为
-不可满足被拒绝,而 `mcpp::xpkg_dir` 回答满足该范围的最高**已安装**版本——声明了下界
-的规则找得到下界带进来的东西。
+范围在两个方向上都会被解析。`>=2026.1` 安装满足它的最高已发布版本，
+`>=2099.1` 因无法满足而被拒绝，`mcpp::xpkg_dir` 给出满足该范围的
+**已安装**最高版本——由此，一条声明了下限的规则能够找到那个下限
+带进来的东西。
 
-### 工程没点名的工具,其版本的来源
+### 工程没点名的工具，其版本的来源
 
-| 工程声明了 | 版本来自 |
+| 工程的声明 | 版本来自 |
 |---|---|
-| `[xlings.workspace]`,无 `subos` | 机器的环境,工程自己的条目叠在上面 |
-| `[xlings.workspace]` 与 `subos = "<名>"` | 那个环境自己的 workspace;机器的不适用 |
-| 两者都没有 | 机器的环境 |
+| `[xlings.workspace]`，不带 `subos` | 机器自身的环境，工程自己的条目叠加在其上 |
+| `[xlings.workspace]` 且 `subos = "<name>"` | 该环境自己的 workspace；机器的不生效 |
+| 两者都不写 | 机器自身的环境 |
 
-中间那行不是遗漏。指名的环境有自己的已安装集合,把机器的版本带进去会指向那里不
-存在的版本。**写 subos 就是要隔离,不写就是要机器的环境加上自己的条目。**
+中间一行不是遗漏。一个具名环境有它自己已安装的集合，把机器的版本带进去
+只会点名一些根本不在那里的版本。点名一个环境，是工程要求隔离的方式；
+不写，则是工程要求「机器的环境，加上自己那些条目叠加在上面」的方式。
 
-在工程内执行的 `xlings use` 压过这张表,直到 mcpp 重写环境为止——它是最后合并的
-那一层。
+在工程内部执行的一次 `xlings use` 优先于这张表，直到 mcpp 重写该环境为止，
+因为它是最后被合并的一层。
 
-### `deps`,已被取代
+### `deps`，已被取代
 
-`deps = ["xim:qemu-riscv@9.2.4-1"]` 是同一句话在 2026.9.3 之前的拼法。它仍然生效,
-并且会被报告一次,同时给出该写的 `[xlings.workspace]` 那一行。**不拒绝**——拒绝会
-落到**依赖**的 manifest 上,而钉了那个包精确版本的工程改不了它。
+`deps = ["xim:qemu-riscv@9.2.4-1"]` 是同一句陈述在 2026.9.3 之前的写法。
+它仍然被采纳，并被报告一次，同时给出应当改写成的 `[xlings.workspace]`
+那一行。它不会被拒绝，因为拒绝会触及*依赖*的 manifest，
+而钉住了那个包某个精确版本的工程无法编辑它。
 
-### `envs`,已移除
+### `envs`，已移除
 
-`[xlings.envs]` 曾被物化进 `.xlings.json`,而没有任何东西读它:程序的环境由它自己
-的包声明,环境的环境由那个环境声明。现在这个键是错误,并同时点名这两者。索引里没有
-任何包用过它。
+`[xlings.envs]` 过去被物化进 `.xlings.json`，却没有任何东西读取它：
+一个程序的环境由它自己的包声明，一个环境的环境由那个环境本身声明。
+这个键现在是错误，并同时点名两者。索引中没有任何东西用过它。
 
 ## 8. 相关章节
 
-- [30 - build.mcpp](30-build-mcpp.md) —— 构建程序收到的契约,含它运行时的
-  `PATH`。
-- [91 - 工具链内部](91-toolchain-internals.md) —— 运行时选择、`RuntimeBinding`
-  快照与降级规则。
-- [04 - mcpp.toml](04-mcpp-toml.md) —— manifest 的其余部分。
+- [30 —— 构建程序：`build.mcpp`](30-build-mcpp.md) —— 构建程序收到的契约，
+  包括它运行时所用的 `PATH`。
+- [91 —— 工具链内幕](91-toolchain-internals.md) —— 运行时选择、
+  `RuntimeBinding` 快照，以及降级规则。
+- [04 —— mcpp.toml](04-mcpp-toml.md) —— manifest 的其余部分。
 
 ## 当前边界
 
-- **工具不能以加速器为条件。** 加速器在依赖图之后才解析,因此这样的工具会被声明而
-  永远装不上 —— 一次「工具干脆不在」却仍然成功的构建。写了这种条件的 manifest 会被
-  拒绝。
-- 离产物更近的那条声明胜出,且覆盖会被报告。不满足另一方所述要求的钉子会被拒绝并
-  点名两边,而不是与之并存安装。
+- **工具不能以加速器为条件。** 加速器在依赖图之后才解析，因此这样的工具
+  会被声明、却永远不会被安装——一次成功的构建里那个工具干脆缺席。
+  写了这样一条的 manifest 会被拒绝。
+- 离产物更近的声明胜出，覆盖会被报告。一个不满足对侧所陈述要求的 pin
+  会被拒绝，并同时指出两侧，而不是与之并存安装。
diff --git a/docs/zh/24-openkal-cross.md b/docs/zh/24-openkal-cross.md
index 01bc59737..38292a3b1 100644
--- a/docs/zh/24-openkal-cross.md
+++ b/docs/zh/24-openkal-cross.md
@@ -1,86 +1,95 @@
 # 24 —— 基于 openkal 的交叉构建
 
-**读者:**从本机为另一个操作系统做交叉构建的人。
+**读者：** 从本机为另一个操作系统做交叉构建的人。
 
-**本章回答的那一个问题:**一份源码树怎样为多个 hosted 目标构建,而本机并没有它们
-的工具链。
+**本章回答的那一个问题：** 一份源码树怎样为多个 hosted target 构建，而本机
+并没有它们各自的工具链。
 
-**不在这里:**没有操作系统的目标,那是 [40 —— 裸机](40-baremetal.md);以及目标
-怎样命名,那是 [21 —— 目标三元组](21-the-target-triple.md)。
+**不在这里：** 没有操作系统的 target，那是 [40 —— 裸机](40-baremetal.md)；
+以及 target 怎样命名，那是 [21 —— 目标三元组](21-the-target-triple.md)。
 
-传统的交叉构建由载荷承担。一份工具链为一个目标而构建,它的驱动只有一个答案,
-到达第二个目标意味着获取第二份工具链。因此一个发行方必须发布的载荷数,
-等于它支持的宿主-目标对数。
+传统的交叉构建由载荷承担。一份工具链为一个 target 构建，它的驱动器只有一个
+答案，到达第二个 target 意味着获取第二份工具链。因此一个发行方必须发布的
+载荷数，等于它所支持的宿主-目标对数。
 
-openkal 改变了「被交叉的是什么」。目标侧 —— 平台接口、C 库、编译器运行时与
-C++ 运行时 —— 成为一组由依赖图解析、并由当前运行的编译器从源码构建的包。
-留给编译器的是代码生成,而一个 Clang 二进制发出它被构建时所包含的每一种对象格式。
+openkal 改变的是「被交叉的是什么」。目标侧 —— 平台接口、C 库、编译器运行时
+与 C++ 运行时 —— 变成一组由依赖图解析、并由当前运行的编译器从源码编译的包。
+留给编译器的只剩代码生成，而一个 Clang 二进制会发出它被构建时所支持的每一种
+对象格式。
 
-本文陈述该模型、工程需要书写的内容、生态所供给的内容,以及已被实测的界限。
+本文陈述这个模型、一个工程要书写的内容、生态供给的内容，以及已被实测过的
+界限。
 
 ## 论断
 
-一个由 N 个平台与 M 个架构构成的生态,需要的是一个接口的 N 份实现,
-而不是 N×M 份工具链。这个计数来自目标侧所在的位置:一个从源码构建的包,
-是为编译器被要求发出的那个目标而构建的,因此一份平台实现只写一次,
-就到达编译器支持的每一个架构。
+一个由 N 个平台与 M 个架构构成的生态，需要的是一个接口的 N 份实现，而不是
+N×M 份工具链。这个计数来自目标侧所在的位置：一个从源码构建的包，是为编译器
+被要求发出的那个 target 而构建的，因此一份平台实现只需写一次，就能到达编译器
+支持的每一个架构。
 
-该论断由一个三宿主 × 三目标的矩阵验证,每一格构建同一份源码并运行其结果。
+这个论断由一个三宿主 × 三目标的矩阵验证，每一格构建同一份源码并运行其结果。
 
-## 三层,三组宏(mcpp 2026.9.18+)
+## 三层，三组宏（mcpp 2026.9.18+）
 
-一次基于 openkal 的构建回答三个不同的问题,而在这项能力之前,一个宏(`_WIN32`)同时
-回答了其中两个——这正是每一次 openkal-Windows 失败的根因,其诊断都指向一份缺失的平台
-头文件:代码本想问「这是不是 openkal」,却用了一个实际意味着「Windows CRT 是否在场」的宏。
+一次基于 openkal 的构建要回答三个不同的问题，而在这项能力落地之前，一个宏
+（`_WIN32`）同时回答了其中两个 —— 这正是每一次 openkal-Windows 失败的根因，
+它们的诊断无一例外指向某份缺失的平台头文件：代码本想问的是「这是不是
+openkal」，用的却是一个实际含义为「Windows CRT 是否在场」的宏。
 
 | 宏族 | 陈述 | 定义者 | 例子 |
 |---|---|---|---|
-| 内核 ABI | `kal_*` 可调用,且在每个平台上行为一致 | 提供 `mcpp:kernel-abi=openkal` 的层 | `__OPENKAL__` |
-| C 环境 | 源码看到的 C 环境形状 | 提供 `mcpp:c-abi=<impl>` 的层,通过 [`[c-abi]`](22-target-side.md#c-abi-包陈述它呈现的-c-环境mcpp-2026918) | `__unix__`、`_WIN32`、`__MINGW32__` |
+| 内核 ABI | `kal_*` 可调用，且在每个平台上行为一致 | 提供 `mcpp:kernel-abi=openkal` 的那一层 | `__OPENKAL__` |
+| C 环境 | 源码所见 C 环境的形状 | 提供 `mcpp:c-abi=<impl>` 的那一层，经由 [`[c-abi]`](22-target-side.md#c-abi-包陈述它呈现的-c-环境mcpp-2026918) | `__unix__`、`_WIN32`、`__MINGW32__` |
 | 系统与架构 | 底层操作系统与处理器 | 目标三元组 | `__linux__`、`__APPLE__`、`__x86_64__` |
 
-还有第四件事,搭着 C 环境这一行的便车,但并不是同一个问题:链接器产出的**目标文件
-格式**——PE、ELF、Mach-O——是**目标三元组**的属性,不是 `presents` 选出来的那个 C 环境
-的属性,二者可以不一致。Windows 上 `presents = "posix"` 链接出来的仍然是 PE;第三方可移植
-代码里,给这个特定组合——「PE 格式 + 呈现 POSIX 的 C 环境」——起名字的唯一办法,是
-`__CYGWIN__`/`__CYGWIN32__`,所以 Cygwin 式的实现让它们保持**定义**,而不是把它折进上面
-三行里的任何一行——完整的权衡说明见
-[22 自己的说明](22-target-side.md#c-abi-包陈述它呈现的-c-环境mcpp-2026918)。自
-2026.9.21.1 起,`__CYGWIN__` 不再是那个事实的唯一名字:mcpp 为每个目标定义
-`__MCPP_TARGET_<OS>__`(见 `docs/21`「mcpp 定义的宏」),于是需要在被呈现的环境之下得知
-目标的源码,有了一个 mcpp 自己拥有的名字。`__CYGWIN__` 在生态的已安装头迁移到新名字期间
-仍然定义着,之后才撤销。把两者中的任何一个当成第四个 C 环境宏来读,而不是它们实际是的
-样子——一个关于**目标**的事实,而不是关于其上呈现的环境——正是这一整节想要提前避免的
-那种混淆。
-
-**`__OPENKAL__` 的规则。** 只要解析出的 `kernel-abi` 层的接口名是 `openkal`,引擎就为目标侧的
-每一个编译单元定义它——取自层的取值,绝不取自包名,因此第二个 `mcpp:kernel-abi=openkal` 的
-实现不需要引擎改动。
-
-*允许:* 用它决定某处调用点是否调用 `kal_*`。它在每个目标上含义相同,因此这样用绝不会把
-平台信息夹带进本该与实现无关的源码。
-
-*禁止:* 用它选择头文件、推断 `_WIN32` 是否为真、绕开缺失的 SDK,或者区分
-`linux`/`windows`/`macos`。那些是 C 环境层或平台层的问题——在清单里写
-`cfg(c-abi = "…")` 或 `cfg(kernel-abi = "…")`(谓词语法见
-[22 —— 对已解析目标侧的适配](22-target-side.md#对已解析目标侧的适配))。
-
-**平台单元。** 自己需要平台原生环境的包,从不读 `__OPENKAL__` 或别的宏去推断这件事——边界
-是清单里写明的,不是从源码推断出来的,跨越它的一切仍然只能是定宽类型(SPEC §5.4)。两类
-不同的包,通过两条不同的路径拿到 `[package] c-environment = "platform"`(docs/22):
-
-- 提供 `mcpp:kernel-abi=<impl>` 的包(比如 openkal-windows),这个值是**推导**出来的,
-  单凭 `provides` 就够——这样的包按定义本身就是平台边界,所以它自己完全不需要写这个键,
-  每一个已经发布的实现也都覆盖到了,不需要发新版本。
-- 一个普通包,不是 kernel-abi 提供者,但自身确有平台绑定的单元——比如
-  [06 私有依赖模式](06-features-and-capabilities.md#平台-sdk-依赖保持私有)下的一个平台
-  shim——**显式**声明这个键,因为引擎没有 `provides` 条目可供推导(设计 §5.3)。
-
-两者都能用得上的地方,显式声明的键总是优先于推导(docs/22 自己的优先级说明)——但今天还
-没有办法反着写「不是 platform」,所以实践中真正用得上这条优先级的,只有一种少见情形:
-一个 kernel-abi 提供者,居然还是需要图里呈现的那个 C 环境。
-
-## 工程书写的内容
+还有第四件事搭着 C 环境这一行的便车，但并不是同一个问题：链接器产出的
+**对象文件格式** —— PE、ELF、Mach-O —— 是**目标三元组**的属性，不是
+`presents` 选出的那个 C 环境的属性，二者可以互不一致。Windows 上
+`presents = "posix"` 链接出来的仍然是 PE；第三方可移植代码给这个特定组合 ——
+「PE 格式配上呈现 POSIX 的 C 环境」—— 起名字的唯一办法，是
+`__CYGWIN__`/`__CYGWIN32__`，所以 Cygwin 式的实现让它们保持**已定义**，而不
+是把它们折进上面三行里的任何一行 —— 完整的权衡说明见
+[22 自己的说明](22-target-side.md#c-abi-包陈述它呈现的-c-环境mcpp-2026918)。
+自 2026.9.21.1 起，`__CYGWIN__` 不再是那个事实的唯一名字：mcpp 为每一个
+target 定义 `__MCPP_TARGET_<OS>__`（见 `docs/21`「mcpp 定义的宏」），于是
+需要在一个被呈现的环境之下得知目标本身的源码，就有了一个 mcpp 自己拥有的
+名字。`__CYGWIN__` 会在生态的已安装头文件迁移到新名字期间继续保留定义，之后
+才撤销。把这两者中的任何一个当成第四个 C 环境宏来读，而不是把它们读成它们
+实际是的样子 —— 一个关于**目标**的事实，而不是关于其上被呈现的环境的事实 ——
+正是这一整节想要提前避免的那种混淆。
+
+**`__OPENKAL__` 的规则。** 只要解析出的 `kernel-abi` 层的接口名是
+`openkal`，引擎就为目标侧的每一个编译单元定义它 —— 取自层自己的取值，绝不
+取自包名，因此第二个提供 `mcpp:kernel-abi=openkal` 的实现不需要引擎改动。
+
+*允许的用法：* 用它来判断某处调用点是否要调用 `kal_*`。它在每个 target 上
+含义相同，因此这样使用它绝不会把平台信息夹带进本该与实现无关的源码。
+
+*禁止的用法：* 用它选择一个头文件、推断 `_WIN32` 是否为真、绕开一个缺失的
+SDK，或者区分 `linux`/`windows`/`macos`。那些是 C 环境层或平台层的问题 ——
+应改在清单里写 `cfg(c-abi = "…")` 或 `cfg(kernel-abi = "…")`（谓词语法见
+[22 —— 对已解析目标侧的适配](22-target-side.md#对已解析目标侧的适配)）。
+
+**平台单元。** 自身需要平台原生环境的包，从不通过读取 `__OPENKAL__` 或其他
+任何宏来推断这件事 —— 边界写在清单里，不从源码推断，而跨越这道边界的一切
+仍然只能是定宽类型（SPEC §5.4）。两类不同的包，经由两条不同的路径到达
+`[package] c-environment = "platform"`（docs/22）：
+
+- 一个提供 `mcpp:kernel-abi=<impl>` 的包（比如 openkal-windows），这个值对
+  它是**推导**出来的，单凭 `provides` 就够 —— 这样的包按定义本身就是平台
+  边界，因此它完全不需要自己写这个键，每一个已经发布过的实现也都自动覆盖，
+  不必发新版本。
+- 一个普通包，本身不是 kernel-abi 的提供者，却确实带有自己平台绑定的单元 ——
+  比如 [06 私有依赖模式](06-features-and-capabilities.md#平台-sdk-依赖保持私有)
+  下的一个平台 shim —— 需要**显式**声明这个键，因为引擎没有 `provides`
+  条目可供推导（设计 §5.3）。
+
+两种途径都能用得上的地方，显式声明的键永远优先于推导（docs/22 自己的优先级
+说明）—— 但目前还没有办法反着写出「不是 platform」，因此实践中这条优先级
+真正用得上的地方只有一种少见情形：一个 kernel-abi 的提供者，居然还需要图所
+呈现的那个 C 环境。
+
+## 工程要写的内容
 
 ```toml
 [dependencies]
@@ -90,10 +99,10 @@ openkal-llvm-runtime = "0.1.1"
 default = "llvm@22.1.8"
 ```
 
-两行。第一行选定目标侧的三个层;第二行命名一个编译器,
-并且对其余一切来自何处只字未提。
+两行。第一行选定目标侧的三个层；第二行命名一个编译器，并且对其余一切来自
+何处只字未提。
 
-目标在命令行上给出:
+target 在命令行上给出：
 
 ```bash
 mcpp build --target x86_64-linux
@@ -101,135 +110,141 @@ mcpp build --target aarch64-macos
 mcpp build --target x86_64-windows-gnu
 ```
 
-宿主目标不需要 `[target.<三元组>]` 段,源码中也不需要任何预处理指令。
-可运行的示例见 [examples/06-openkal-cross](../../examples/06-openkal-cross)。
+一个 hosted target 不需要 `[target.<triple>]` 段，源码中也不需要任何预处理
+指令。可运行的示例见 [examples/06-openkal-cross](../../examples/06-openkal-cross)。
 
 ## 生态供给的内容
 
 | 包 | 层 | 内容 |
 |---|---|---|
-| `openkal` | — | 规范,以及声明它的那些 C++ 模块 |
-| `openkal-linux` | `kernel-abi` | 参考实现,建立在 Linux 系统调用之上 |
+| `openkal` | — | 规范本身，以及声明它的那些 C++ 模块 |
+| `openkal-linux` | `kernel-abi` | 参考实现，建立在 Linux 系统调用之上 |
 | `openkal-macos` | `kernel-abi` | 建立在 macOS 的系统调用面之上 |
-| `openkal-windows` | `kernel-abi` | 建立在 Win32 与对象管理器之上,不使用任何 C 运行时符号 |
-| `openkal-opensbi` | `kernel-abi` | 建立在 RISC-V 的 SBI 之上,无操作系统 |
-| `openkal-uefi` | `kernel-abi` | 建立在 UEFI Boot Services 之上,在操作系统存在之前 |
-| `openkal-musl` | `c-abi` | 被重定向到 openkal 的 musl,只移植一次 |
-| `openkal-llvm-runtime` | `compiler-runtime`、`c++-abi` | compiler-rt builtins、libunwind、libc++abi 与 libc++,为 openkal-musl 配置 |
+| `openkal-windows` | `kernel-abi` | 建立在 Win32 与对象管理器之上，不使用任何 C 运行时符号 |
+| `openkal-opensbi` | `kernel-abi` | 建立在 RISC-V 的 Supervisor Binary Interface 之上，无操作系统 |
+| `openkal-uefi` | `kernel-abi` | 建立在 UEFI Boot Services 之上，在操作系统存在之前 |
+| `openkal-musl` | `c-abi` | 被重定向到 openkal 上的 musl，只移植过一次 |
+| `openkal-llvm-runtime` | `compiler-runtime`、`c++-abi` | compiler-rt 内建函数、libunwind、libc++abi 与 libc++，为 openkal-musl 配置 |
 
-一个工程命名其中最后一个。其余由它的依赖推出。
+一个工程命名其中最后一个，其余的由它的依赖推出。
 
 ## 编译器必须是 LLVM 的原因
 
-`openkal-llvm-runtime` 把这项要求声明出来,而不是留待被发现:
+`openkal-llvm-runtime` 把这项要求直接声明出来，而不是留给使用者自己去发现：
 
 ```toml
 requires = ["mcpp:compiler=llvm"]
 ```
 
-它的源码是 libc++ 的,其中 `std` 模块源尤其由 Clang 编译。
-把那份源码交给 GCC,会在 libc++ 自己的头文件深处失败,
-其消息命名一个读者从未打开过的文件:
+它的源码就是 libc++ 的源码，其中的 `std` 模块源尤其只由 Clang 编译。把那份
+源码交给 GCC，会在 libc++ 自己的头文件深处失败，报错信息里点名的是一个读者
+从未打开过的文件：
 
 ```
 fatal error: __config: No such file or directory
 ```
 
-有了这项声明,构建在编译任何东西之前拒绝该组合,
-并指出选择一个满足它的编译器的那条命令。
+有了这项声明，构建会在编译任何东西之前就拒绝这种组合，并指出用哪条命令可以
+选中一个满足它的编译器。
 
 ## 目标的选定
 
-mcpp 自身词表的目标行可以携带一条工具链约定。该约定命名的是
-**供给该目标 C 库的那份载荷**,并且仅在两个条件同时成立时生效:
-清单对该目标未作陈述,且依赖图中没有任何东西供给该目标的系统。
+mcpp 自身词表里的目标行可以携带一条工具链约定。这条约定命名的是**供给该
+target C 库的那份载荷**，并且只在两个条件同时成立时才生效：清单对该 target
+没有任何陈述，且依赖图中没有任何东西供给该 target 的系统。
 
-第二个条件只有在图被解析之后才可知。因此一个 C 库来自 `openkal-musl` 的工程
-保留它所要求的编译器,而一个没有依赖的工程仍然收到该行所命名的载荷。
-两种行为均经实测;提前按任一方向决定,对另一方向都是错的。
+第二个条件只有在图被解析完之后才可知。因此一个 C 库来自 `openkal-musl` 的
+工程，仍然保留它自己要求的那个编译器，而一个没有依赖的工程，则仍然拿到该行
+所命名的载荷。两种行为都经过实测；提前朝任何一个方向硬性决定，对另一个方向
+都是错的。
 
 ## 环境段
 
-在 Linux 上,目标三元组的第三段命名 C 库。在 openkal 之下 C 库来自图,
-因此一个命名了 C 库的三元组陈述的是一项图未必兑现的请求:
+在 Linux 上，目标三元组的第三段命名的是 C 库。而在 openkal 之下，C 库来自
+依赖图，因此一个命名了 C 库的三元组，陈述的只是一项图未必会兑现的请求：
 
 ```
-mcpp build --target x86_64-linux-gnu     # 请求 glibc
+mcpp build --target x86_64-linux-gnu     # asks for glibc
       c-abi   musl   (openkal-musl@0.3.3, graph)
 ```
 
-以图为准。省略该段即不作请求,并产出相同的产物:
+以图为准。省略这一段等于不作请求，产出的是同一个产物：
 
 ```
 mcpp build --target x86_64-linux
 ```
 
-该段存在且不一致时,构建报出这一点。它是报出而非拒绝,
-因为该段是被忽略而非被违反。在一台宿主上实测 `x86_64-linux` 与 `x86_64-linux-musl`:两个可执行文件不同,strip 之后逐字节相同。差异在调试信息里,它记录了输出目录,而目录以三元组命名。代码是同一份代码。
+当这一段存在且与图的结果不一致时，构建会报出这一点。它是一次报告而不是一次
+拒绝，因为这一段是被忽略而不是被违反。在一台宿主上实测 `x86_64-linux` 与
+`x86_64-linux-musl`：两个可执行文件本身不同，strip 之后逐字节相同。差异全在
+调试信息里，它记录的是输出目录，而目录名又是按三元组起的。代码是同一份代码。
 
-在 Windows 上,同一段命名的是对象 ABI —— `gnu` 是 PE 加 GNU ABI,
-`msvc` 是 PE 加微软的 —— 而两者都与不止一种 C 库相容。
-因此该项报出被限定在该段命名 C 库的那些平台上。
+在 Windows 上，同一段命名的是对象 ABI —— `gnu` 表示 PE 配 GNU ABI，`msvc`
+表示 PE 配微软的 ABI —— 而两者都与不止一种 C 库相容。因此这一项不一致报告的
+适用范围，被限定在这一段确实命名一个 C 库的那些平台上。
 
-沉默作为**诊断**是对的,作为**报告**是不够的。读者看到
+沉默作为**诊断**是对的，作为**报告**却不够。读者看到
 
 ```
 Target x86_64-windows-gnu → x86_64-w64-windows-gnu
        c-abi   musl   (openkal-musl@0.3.3, graph)
 ```
 
-在其中找不到一行叫 `gnu`,于是把它映到最像 C 库名字的那一行。
+在其中找不到一行叫 `gnu`，于是把它映射到最像 C 库名字的那一行上去。
 
-对这次构建的产物实测:
+对这次构建的产物实测：
 
 | 观测 | 值 |
 |---|---|
-| 导入的库 | `ntdll`、`KERNEL32`、`SHELL32` —— 无 `msvcrt`,无 `ucrtbase` |
-| Itanium 修饰符号(`_Z…`) | 4507 |
-| MSVC 修饰符号(`?…`) | 0 |
+| 导入的库 | `ntdll`、`KERNEL32`、`SHELL32` —— 没有 `msvcrt`，也没有 `ucrtbase` |
+| Itanium 修饰符号（`_Z…`） | 4507 |
+| MSVC 修饰符号（`?…`） | 0 |
 
-第一行说明 `c-abi musl` 是老实的:MinGW 的 C 运行时一点没链进来。
-后两行是 `gnu` 实际选中的东西 —— Itanium C++ ABI,而不是微软那套。
+第一行说明 `c-abi musl` 是老实的：MinGW 的 C 运行时一点没被链接进来。后两行
+则是 `gnu` 真正选中的东西 —— Itanium C++ ABI，而不是微软那一套。
 
-而它**不对应报告里的任何一行**,这正是要点。五层记录的是每一层
-**由谁供给**;`gnu` 命名的是这些**对象遵循哪套约定**,是若干层必须一致的
-横切事项。把它读成 `c++-abi libc++` 是第二个错误答案:libc++ 是标准库的
-一个实现,libstdc++ 是另一个,两者都坐在 Itanium ABI 上。
+它**不对应报告里的任何一行**，而这正是要点所在。五个层记录的是每一层**由谁
+供给**；`gnu` 命名的是这些**对象所遵循的约定**，这是一件若干层必须彼此一致
+的横切事项。把它读成 `c++-abi libc++` 是第二个错误答案：libc++ 是标准库的
+一个实现，libstdc++ 是另一个，两者都坐落在 Itanium ABI 之上。
 
-因此报告直接说出那套 ABI 本身 —— 它的名字不出现在任何一行里,
-于是不会被误当成某一层:
+因此报告直接说出那套 ABI 本身的名字 —— 它不出现在任何一行里，所以不会被
+误当成某一层：
 
 ```
 Target x86_64-windows-gnu → x86_64-w64-windows-gnu   (gnu selects the Itanium C++ ABI, not a C library)
 ```
 
-该段在每个平台上承载不同的轴 —— Linux 上是 C 库,Windows 上是对象 ABI,
-没有操作系统时是对象格式 —— 因此记录的是**它是哪一个**,
-而不是一个只记录「是否为第一种」的布尔。
+这一段在不同平台上承载的是不同的轴 —— 在 Linux 上是 C 库，在 Windows 上是
+对象 ABI，在没有操作系统时是对象格式 —— 因此记录的是**它究竟是哪一个**，而
+不是一个只记录「是不是第一种」的布尔值。
 
 ## 这个模型下的 Android、Web 与 iOS
 
-mcpp 在 2026.9.11.3 里加出目标行的这三个平台不是同一个问题。决定每一个的是它的
-实现相对一个 C 库该落在哪一侧,而三个答案各不相同。
+mcpp 在 2026.9.11.3 里新增目标行的这三个平台，并不是同一个问题。决定每一个
+平台答案的，是它的实现相对一个 C 库应该落在哪一侧，而三个平台的答案各不
+相同。
 
-### Android 共用 Linux 的实现,一行都不用改
+### Android 共用 Linux 的实现，一行都不用改
 
-`openkal-linux` 写在 Linux 内核自己的系统调用接口上,不向任何 C 库借用任何东西 ——
-这正是它能被放到一个 C 库**底下**的原因。Android 的内核**就是** Linux,给定架构上
-的系统调用 ABI 完全相同,而 `src/sys.h` 按 `__x86_64__` / `__aarch64__` 分支,也就是
-按**架构**而不是按操作系统。它里面没有任何属于 glibc 或 bionic 的东西。
+`openkal-linux` 写在 Linux 内核自己的系统调用接口上，不向任何 C 库借用任何
+东西 —— 这正是它能被放到一个 C 库**底下**的原因。Android 的内核**就是**
+Linux，给定架构上的系统调用 ABI 完全相同，而 `src/sys.h` 是按
+`__x86_64__` / `__aarch64__` 分支的，也就是按**架构**而不是按操作系统分支。
+它里面没有任何属于 glibc 或 bionic 的东西。
 
-所以一个可移植程序不需要新增任何一行。`cfg(os = "linux")` 对一个 Android triple
-**为真**,因为 Android 是 `linux` OS 上的一个 `env` 值 ——
-[21 — 目标三元组](21-the-target-triple.md) 记着这处建模决定 —— 于是实现由一个
-Linux 消费者本来就会写的那一行选出:
+所以一个可移植的程序不需要新增任何一行。`cfg(os = "linux")` 对一个 Android
+三元组**为真**，因为 Android 是 `linux` 这个 OS 上的一个 `env` 取值 ——
+[21 —— 目标三元组](21-the-target-triple.md) 记着这处建模决定 —— 于是实现
+由一个 Linux 消费者本来就会写的那一行选出：
 
 ```toml
 [target.'cfg(os = "linux")'.dependencies]
 openkal-linux = "0.12.0"
 ```
 
-实测 2026-09-11,一个只针对 openkal 写的程序 —— 没有 C 库,也没有 `import std`:
+实测于 2026-09-11，一个只针对 openkal 写的程序 —— 没有 C 库，也没有
+`import std`：
 
 ```
 mcpp build --target x86_64-linux-android
@@ -237,98 +252,105 @@ mcpp build --target x86_64-linux-android
     ->  ELF 64-bit LSB pie, x86-64, interpreter /system/bin/linker64
 
 mcpp build --target aarch64-linux-android
-    ->  ELF 64-bit LSB pie, ARM aarch64, 同一个 interpreter
+    ->  ELF 64-bit LSB pie, ARM aarch64, same interpreter
 ```
 
-而那个 x86_64 产物被推到一台 API 24 的模拟器镜像上执行:
+而那个 x86_64 产物被推送到一台 API 24 的模拟器镜像上执行：
 
 ```
 openkal: 1-2-3          exit 0
 ```
 
-`openkal-linux` 自己也能为两个 Android 目标原样编译,这是两条里较弱的那一条,值得
-分开陈述:前者说的是**实现**构建得起来,后者说的是**它上面的程序**跑得起来。
-
-### iOS 共用 macOS 的实现,而 SDK 是被定位的而不是被打包的
-
-同样的论证在 Apple 这一侧成立:iOS 与 macOS 共用 Darwin 内核、同一套调用号、同一
-套调用约定,而 `openkal-macos` 是按同样方式按架构分支的。两者之间不同的是 SDK 与
-部署目标标志,而这两样都属于构建工具而不属于实现 —— 所以 iOS 是清单里的一行 `cfg`,
-不是一个新包。
-
-**被阻塞的是 SDK,而解开它的是把问题问得更小。** iPhoneOS 与 iPhoneSimulator 的
-SDK 在 Xcode 里且不可再分发,这界定的是**打包**它们。它没有界定**定位**它们:
-`aarch64-macos` 早在这三行存在之前就以完全相同的切分方式是 `verified` —— `xim:llvm`
-负责编译,机器自己的 macOS SDK 通过 `xcrun` 被找到。iOS 三行取的是同一种切分加上
-第二个 SDK,所以它们钉 `llvm@22.1.8` 且不带 `sysroot` 条目:那一列命名的是一个包,
-而一个被定位的目录不是包。
-
-对这份文档的后果是,这三行不再是一个结构性论证。`openkal-macos` 能为它们编译,而
-读者需要知道的是:SDK 是一个具名的宿主依赖 —— 这个平台恰好新增两个,另一个是
-`simctl` —— 并且它的缺失是一次点名 SDK 的拒绝,而不是一次悄悄产出 macOS 产物的
-构建。
-
-### Web 需要过一份新的实现,而 `openkal-emscripten` 就是它
-
-Emscripten 是三者里**改变模型**而不是扩展表格的那一个。那里没有内核,也没有系统
-调用可发:Emscripten 在一个 JavaScript 宿主之上供给它自己的 C 库。所以给它写的
-openkal 实现不可能按 `openkal-linux` 的方式写 —— 落在一个 C 库底下 —— 而必须落在
-一个 C 库**之上**。规范恰好允许这一点(「一个实现可以建立在一个 C 库之上、之下,
-或者不依赖 C 库」),所以这是**新软件**而不是一个共用决定。
-
-`openkal-emscripten` 是这个生态里第一份按那个方向写的实现。那个方向让代码变薄而
-不是变容易:每个函数大体是一次转发加一次错误翻译,而它必须做对的地方,恰好是 C 库
-的词汇与 openkal 的词汇**不对应**的那些地方 —— 一个是对齐而不是页的粒度、一个分辨
-率被浏览器有意变粗的单调时钟、一个在 node 下存在而在页面里不存在的终端。
-
-**一个不完整的面也可以是一个符合规范的面,而规范写明了怎么做。** 6.2 条给出三个
-时刻,每一个都是相应信息最早存在的时刻,而这份实现的三组各取一种处理:
+`openkal-linux` 自己也能为两个 Android target 原样编译，这是两条论断中较弱
+的一条，值得分开陈述：前一条说的是**这份实现**构建得起来，后一条说的是**建
+在它之上的程序**运行得起来。
+
+### iOS 共用 macOS 的实现，SDK 是被定位而不是被打包的
+
+同样的论证在 Apple 这一侧成立：iOS 与 macOS 共用 Darwin 内核、同一套系统
+调用号、同一套调用约定，`openkal-macos` 也按同样的方式按架构分支。两者之间
+真正不同的是 SDK 与部署目标标志，而这两样都属于构建工具而不属于实现 ——
+所以 iOS 只是清单里的一行 `cfg`，不需要一个新包。
+
+**被阻塞的是 SDK 本身，而解开它的方法是把问题问得更小。** iPhoneOS 与
+iPhoneSimulator 的 SDK 随 Xcode 分发、不可再分发，这界定的是**打包**它们；
+它并不界定**定位**它们：`aarch64-macos` 早在这三行存在之前，就已经以完全
+相同的切分方式达到 `verified` —— `xim:llvm` 负责编译，机器自己的 macOS
+SDK 通过 `xcrun` 被找到。iOS 的这几行采用的是同一种切分，只是加了第二个
+SDK，所以它们把 `llvm@22.1.8` 钉死，且不带 `sysroot` 条目：那一列命名的是
+一个包，而一个被定位到的目录不是包。
+
+对本文而言，其后果是这几行不再是一个结构性的论证。`openkal-macos` 能为它们
+编译，读者需要知道的只是：SDK 是一项具名的宿主依赖 —— 这个平台恰好新增了
+两项，另一项是 `simctl` —— 而它的缺失会得到一次点名该 SDK 的拒绝，而不是一次
+悄悄产出 macOS 产物的构建。
+
+### Web 需要一份全新的实现，`openkal-emscripten` 正是它
+
+Emscripten 是这三者中**改变模型**而不是扩展模型的那一个。那里没有内核，也
+没有系统调用可发：Emscripten 在一个 JavaScript 宿主之上供给它自己的 C 库。
+因此给它写的 openkal 实现不可能按 `openkal-linux` 的方式来写 —— 落在一个
+C 库**底下**—— 而必须落在一个 C 库**之上**。规范恰好允许这一点（「一个实现
+可以建立在一个 C 库之上、之下，或者根本不依赖 C 库」），所以这是一份**新
+软件**，而不是一个共用决定。
+
+`openkal-emscripten` 是这个生态里第一份按那个方向写的实现。那个方向让代码
+变薄，却不让它变得容易：每个函数大体是一次转发加一次错误翻译，而它必须做对
+的地方，恰恰是 C 库的词汇与 openkal 的词汇**不对应**的那些地方 —— 一个是
+对齐而不是页的粒度、一个分辨率被浏览器有意变粗的单调时钟、一个在 node 下
+存在却在页面里不存在的终端。
+
+**一个不完整的面也可以是一个符合规范的面，而规范写明了该怎么做。** 6.2 条
+给出三个时刻，各自是相应信息最早存在的时刻，而这份实现的三组接口各自得到一种
+处理：
 
 | 组 | 处理 | 理由 |
 |---|---|---|
-| `stream`、`fs`、`time`、`env`、`memory`、`random`、`abort`、`terminal` | 提供,转发到 Emscripten 的 libc | MEMFS 与 JavaScript 宿主服务了其中每一项 |
-| `net`、`datagram`、`timeout` | 提供,由能力字报告哪些可被实际运用 | 调用是真的,而承载它们的是一个 WebSocket 代理,所以 `kal_net_props` 既不声称 IPv6 也不声称半关闭 |
-| `process`、`exec`、`space` | 不提供 | 那里没有 fork、没有 exec,也没有第二个地址空间 |
+| `stream`、`fs`、`time`、`env`、`memory`、`random`、`abort`、`terminal` | 提供，转发到 Emscripten 自己的 libc | MEMFS 与 JavaScript 宿主服务了其中每一项 |
+| `net`、`datagram`、`timeout` | 提供，由能力字报告哪些确实可用 | 调用是真的，承载它们的是一个 WebSocket 代理，所以 `kal_net_props` 既不声称支持 IPv6，也不声称支持半关闭 |
+| `process`、`exec`、`space` | 不提供 | 那里没有 fork、没有 exec，也没有第二个地址空间 |
 
-第三行是值得直说的那个决定:**一个缺席的符号就是那份报告。** 实测:
+第三行是值得直说的那个决定：**一个缺席的符号，本身就是那份报告。** 实测：
 
 ```
 wasm-ld: error: obj/main.o: undefined symbol: kal_process_spawn
 ```
 
-这正是 6.2 条的第二个时刻。提供一个返回错误的 `kal_process_spawn` 会是规范禁止的
-那种形状 —— 存在而永远失败,而调用方无法把它与一个条件区分开 —— 并且会把一个在
-链接期已知的事实挪到运行期。
+这正是 6.2 条里的第二个时刻。若提供一个 `kal_process_spawn`、只让它返回
+一个错误，会是规范所禁止的那种形状 —— 存在却永远失败，调用方无法把它同一个
+条件区分开来 —— 并且会把一个在链接期就已知的事实，挪到运行期才能知道。
 
-`openkal.task` 由一个 feature 承载,理由是这个平台特有的:线程需要 `-pthread`,
-而那个开关选定的是另一份 C 库构建、另一个内存模型和另一套加载器契约。不带这个
-feature 时,那个翻译单元是空的,八个符号不存在 —— 与上面三个缺席接口同一种处理。
-带上它时它们存在,而 `kal_interfaces()` 跟随链接本身,而不是跟随一个由包自己发明
-的名字。
+`openkal.task` 由一个 feature 承载，理由是这个平台特有的：线程需要
+`-pthread`，而这个开关选定的是另一份 C 库构建、另一个内存模型和另一套加载器
+契约。不带这个 feature 时，那个翻译单元是空的，那八个符号也不存在 —— 与上面
+三个缺席的接口是同一种处理。带上它时它们就存在，`kal_interfaces()` 跟随的是
+链接结果本身，而不是包自己发明出来的一个名字。
 
-以上都不取代载荷那条路。`wasm32-emscripten` 仍然走普通那条路 —— `xim:emsdk` 自带
-编译器、sysroot 和一份 libc++ 的模块面,所以一个用 `import std` 的程序就能为 Web
-构建并运行,而 openkal 完全不参与,这正是那一行的 `verified` 层级所记录的。openkal
-是一个程序想让一份源码落在若干平台接口之上时才会用到的东西。
+以上都不能取代载荷那条路。`wasm32-emscripten` 仍然走普通的那条路 ——
+`xim:emsdk` 自带编译器、sysroot 与一份 libc++ 的模块面，所以一个使用
+`import std` 的程序照样能为 Web 构建并运行，openkal 完全不参与，这正是该行
+的 `verified` 层级所记录的东西。openkal 是一个程序想让一份源码立于若干平台
+接口之上时才会用到的东西。
 
 ### 表
 
 | 平台 | 实现 | 状态 |
 |---|---|---|
-| Linux(glibc、musl) | `openkal-linux` | 参考实现 |
-| Android(两个 ABI) | `openkal-linux`,原样 | 构建通过;它上面的程序在模拟器上跑过 |
-| macOS | `openkal-macos` | 在 macOS 的系统调用面上 |
-| iOS、iOS 模拟器 | `openkal-macos`,原样 | Darwin 就是 Darwin;SDK 被定位而不是被打包 |
-| Windows | `openkal-windows` | 在 Win32 与对象管理器上 |
-| Web(Emscripten) | `openkal-emscripten` | 写在 C 库**之上**;十五个接口里的十二个 |
+| Linux（glibc、musl） | `openkal-linux` | 参考实现 |
+| Android（两种 ABI） | `openkal-linux`，原样复用 | 构建通过；建在它之上的程序在一台模拟器上运行过 |
+| macOS | `openkal-macos` | 建在 macOS 的系统调用面之上 |
+| iOS、iOS 模拟器 | `openkal-macos`，原样复用 | Darwin 就是 Darwin；SDK 被定位而不是被打包 |
+| Windows | `openkal-windows` | 建在 Win32 与对象管理器之上 |
+| Web（Emscripten） | `openkal-emscripten` | 写在一个 C 库**之上**；十五个接口中的十二个 |
 
 ## 裸机
 
-一个没有操作系统的目标,是同一个模型,只是平台层由固件而非内核供给。
-`riscv64-none-elf` 之上的 OpenSBI 运行与宿主目标相同的源码,含 `import std`,
-因为它所使用的标准库是图供给的那份,而不是编译器自带的那份。
+一个没有操作系统的 target，是同一个模型，只是平台层由固件而非内核供给。
+`riscv64-none-elf` 之上的 OpenSBI 运行的是与 hosted target 相同的源码，含
+`import std`，因为它所使用的标准库是依赖图供给的那份，而不是编译器自带的
+那份。
 
-有两样东西必须声明,两者都是板子的性质而非默认值:
+有两样东西必须声明，两者都是板子本身的性质，而不是默认值：
 
 ```toml
 [target.riscv64-none-elf]
@@ -337,12 +359,12 @@ runner  = ["qemu-system-riscv64", "-machine", "virt", "-nographic",
            "-no-reboot", "-bios", "default", "-kernel"]
 ```
 
-`sysroot = ""` 选定零 libc 档。使用哪个机器模型与哪种固件模式是板子的事实,
-而一个去猜测它的引擎,是另一块板子必须与之搏斗的引擎。
+`sysroot = ""` 选定的是零 libc 档。使用哪种机器模型、哪种固件模式，是板子
+自己的事实，而一个替板子去猜测的引擎，是另一块板子必须与之搏斗的引擎。
 
-hosted 交叉目标使用同一个键,配用户态模拟器(2026.9.2.1)。在 x86_64 宿主上构建的
-`aarch64-linux-musl` 产物,在工程声明后通过 `qemu-aarch64-static` 执行;提供模拟器的包
-按能安装它的宿主声明:
+一个 hosted 交叉 target 使用同一个键，配上一个用户态模拟器（2026.9.2.1）。
+在 x86_64 宿主上构建出的一个 `aarch64-linux-musl` 产物，在工程声明后经由
+`qemu-aarch64-static` 执行；提供该模拟器的包，按能安装它的那些宿主去声明：
 
 ```toml
 [xlings.workspace]
@@ -352,136 +374,145 @@ hosted 交叉目标使用同一个键,配用户态模拟器(2026.9.2.1)。在 x8
 runner = ["qemu-aarch64-static"]
 ```
 
-没有这个键时,`mcpp run` 报告内核的拒绝(`Exec format error`)与应当写的键,`mcpp test`
-把每个测试报告为未运行并以 2 退出。能原生执行该产物的宿主传 `--no-runner`。规则见
-[04 —— mcpp.toml](04-mcpp-toml.md) §2.7.3。
+没有这个键时，`mcpp run` 会报出内核的拒绝（`Exec format error`）以及应当
+写的那个键，`mcpp test` 会把每个测试都报告为未运行并以 2 退出。能原生执行
+该产物的宿主传 `--no-runner`。规则见 [04 —— mcpp.toml](04-mcpp-toml.md)
+§2.7.3。
 
-### 源码是同一份,程序不是
+### 源码是同一份，程序却不是
 
-「同一份源码」是关于工具链与标准库的断言,而它成立:`import std` 可用,
-C++ 运行时是图供给的那份,没有任何 `#if` 区分目标。它不是「任何程序都能
-为任何目标构建」的断言,而规范把原因写得很清楚。
+「同一份源码」是一个关于工具链与标准库的断言，而它成立：`import std` 可用，
+C++ 运行时是依赖图供给的那份，没有任何 `#if` 区分不同的 target。但它不是
+「任何程序都能为任何 target 构建」的断言，规范对其中的原因写得很明确。
 
-一个裸机后端提供一部分接口而不提供另一部分。`openkal-opensbi` 提供
-`abort`、`stream`、`memory`、`env` 与 `time`;它不提供文件系统也不提供任务,
-因为这台机器没有。6.1 条把这种缺席定为链接期的事实:
+一个裸机后端只提供一部分接口，不提供另一部分。`openkal-opensbi` 提供
+`abort`、`stream`、`memory`、`env` 与 `time`；它不提供文件系统也不提供
+任务，因为这台机器根本没有这些东西。6.1 条把这种缺席定为一个链接期的事实：
 
-> 实现不提供的接口,作为链接期定义是缺席的,使用它的消费者链接失败。
+> 一个实现不提供的接口，作为一个链接期定义是缺席的，使用它的消费方链接失败。
 
-因此能力字回答的问题比它初看上去更窄。它说的是一个实现**在它提供的接口内**
-如何表现 —— 名字是否区分大小写、一个时钟的粒度是多少。接口是否存在,
-由更早的东西回答:依赖图,以及退而求其次的链接器。
+因此一个能力字回答的问题，比它初看上去要窄。它说的是一个实现**在它提供的
+接口之内**如何表现 —— 名字是否区分大小写、一个时钟的粒度是多少。接口是否
+存在这件事，由更早的东西回答：依赖图，退而求其次由链接器回答。
 
-这个区分容易丢,因为查询是数据对象上的内联函数:一个程序**只是提问**
-「有没有文件系统」,就取了 `kal_fs_props` 的地址,于是在整份源码没有任何
-文件系统调用的情况下链接失败。在后端把那个字定义为零可以消掉这个错误,
-而它恰是该条禁止的唯一补法 —— 程序随后越过了链接器存在的意义。
-这条路走过,发布为 `openkal-opensbi@0.1.3`,并已撤回。
+这个区分容易被丢掉，因为这类查询是数据对象上的内联函数：一个程序**仅仅是
+提问**「有没有文件系统」，就已经取了 `kal_fs_props` 的地址，于是在整份源码
+里没有任何一处文件系统调用的情况下链接失败。在后端里把那个字定义为零，能够
+消掉这个报错，而这恰恰是该条款所禁止的唯一补法 —— 程序因此越过了链接器本该
+在此处拦住它的那个点。这条路被走过，发布为
+`openkal-opensbi@0.1.3`，随后又被撤回。
 
 ### 到达一台裸 x86_64 机器的两条路线
 
-一台没有操作系统的 x86_64 机器有两种到达方式,区别在于**谁加载这个程序**。
+一台没有操作系统的 x86_64 机器有两种不同的到达方式，区别在于**谁在加载**
+这个程序。
 
 | 路线 | 目标 | 平台层 | 入口 |
 |---|---|---|---|
-| UEFI 应用 | `x86_64-windows-gnu` | `openkal-uefi` | 固件,Boot Services 可用 |
-| 内核,或裸机 | `x86_64-none-elf` | 无,或 `openarch` | 复位向量,其下一无所有 |
+| UEFI 应用 | `x86_64-windows-gnu` | `openkal-uefi` | 固件，Boot Services 可用 |
+| 内核，或裸机 | `x86_64-none-elf` | 无，或 `openarch` | 复位向量，其下一无所有 |
 
-UEFI 应用是 PE/COFF,经微软 x64 调用约定进入。两者都是 LLVM 工具链已有的性质,
-因此它的目标与一个 Windows 程序是同一个三元组,而固件函数指针被直接调用。
-把它与一次 Windows 构建区分开的,是图解析出的平台接口实现,
-以及三个选定 `IMAGE_SUBSYSTEM_EFI_APPLICATION` 的链接 flag。
+一个 UEFI 应用是 PE/COFF，经微软 x64 调用约定进入。这两点都是 LLVM 工具链
+已经具备的性质，因此它的 target 与一个 Windows 程序使用同一个三元组，固件
+函数指针被直接调用。把它与一次 Windows 构建区分开的，是依赖图解析出的平台
+接口实现，再加上三个选定 `IMAGE_SUBSYSTEM_EFI_APPLICATION` 的链接 flag。
 
-一个内核没有固件服务可以调用。它的目标是 `x86_64-none-elf`,即零 libc 档:
-编译行上没有 C 库,链接上没有库目录,`#include <stdio.h>` 不解析。
-程序在它自己的 `_start` 被进入,并直接触达硬件。
+一个内核没有固件服务可以调用。它的 target 是 `x86_64-none-elf`，即零 libc
+档：编译行上没有 C 库，链接上没有库目录，`#include <stdio.h>` 无法解析。
+程序在它自己的 `_start` 处被进入，直接触达硬件。
 
-`openarch` 是这类程序所建立于其上的层。它不是平台接口,也不应答
-`mcpp:kernel-abi`;它是**架构机制** —— 执行上下文、陷阱、每 CPU 状态与地址空间 ——
-作为一个跨若干指令集的接口呈现,每个指令集一个后端包。
-一个内核依赖它,并供给自己的平台层,或者不供给。
+`openarch` 是这类程序赖以建立的那一层。它不是一个平台接口，也不应答
+`mcpp:kernel-abi`；它是**架构机制**本身 —— 执行上下文、陷阱、逐 CPU 状态与
+地址空间 —— 以一个跨越若干指令集的接口呈现，每个指令集配一个后端包。一个
+内核依赖它，并供给自己的平台层，或者什么都不供给。
 
 ### x86_64 裸机需要引擎侧工作的原因
 
-`riscv64-none-elf` 与 `aarch64-none-elf` 是表中的行,除此之外别无他物:
-Clang 对两者都有 BareMetal 工具链,自行驱动它们的链接并到达 `ld.lld`。
-它对 x86_64 没有,于是那个三元组落到通用的 GCC 工具链,而后者的链接器是宿主的 `g++`:
+`riscv64-none-elf` 与 `aarch64-none-elf` 只是表里的两行，仅此而已：Clang
+对两者都有 BareMetal 工具链，会自行驱动它们的链接并到达 `ld.lld`。它对
+x86_64 没有这样的工具链，因此那个三元组落到通用的 GCC 工具链上，而后者的
+链接器是宿主的 `g++`：
 
 ```
 g++: error: unrecognized command-line option '-fuse-ld=…/ld.lld'
 ```
 
-对裸 x86_64 三元组的每一种拼写都实测过,且无法由任何 flag 纠正。
-因此该行携带一个链接器 emulation,由 mcpp 自己调用 `ld.lld` ——
-这也是为什么必须证明宿主工具链没有参与这样一次链接。
+对裸 x86_64 三元组的每一种拼写都做过实测，且无法用任何 flag 纠正。因此这一
+行携带一个链接器 emulation，由 mcpp 自己调用 `ld.lld` —— 这也是为什么必须
+证明宿主工具链没有参与这样一次链接。
 
 ## 已实测的界限
 
-三条,记录在此是因为每一条都由构建而非由阅读发现。
+三条，之所以记录在此，是因为每一条都是由构建发现的，而不是由阅读发现的。
 
-**一个后端必须定义每一个能力字。** 规范的查询是属性对象上的 inline 函数,
-因此一个仅仅询问是否存在文件系统的程序,会取 `kal_fs_props` 的地址。
-一个省略了自身所缺层的能力字的后端,使该问题恰恰在这个问题为之存在的那类机器上
+**一个后端必须定义每一个能力字。** 规范里的查询是属性对象上的内联函数，因此
+一个仅仅提问「有没有文件系统」的程序，就已经取了 `kal_fs_props` 的地址。一个
+省略了自身所缺各层能力字的后端，会让这个问题恰恰在它为之存在的那一类机器上
 链接失败。
 
-**同一层的两个供给者是错误而非选择。** C 库、平台接口与 C++ 运行时互斥。
-选错不会使链接失败,它产出一个能够运行且间歇性不能运行的程序。
+**同一层出现两个供给者是一个错误，不是一个可选项。** C 库、平台接口与 C++
+运行时三者互斥。选错并不会让链接失败，它产出的是一个能够运行、却又间歇性
+不能运行的程序。
 
-**载荷的 C++ 运行时不能位于外来的 C 库之上。** 它的 `__config_site` 记录了
-它被构建时的配置。解析器的结构在默认路径上阻止该组合,
-而一条诊断覆盖工程显式覆写该契约的那些路径。
+**一份载荷的 C++ 运行时不能建立在一个外来的 C 库之上。** 它的
+`__config_site` 记录着它被构建时的配置。解析器的结构在默认路径上就阻止了
+这种组合，而一条诊断覆盖了工程显式覆写该契约的那些路径。
 
 ## 边界
 
-五个层各自只保证自己那一层,层与层之间的边界正是包自身适配工作的所在。
-
-**`kernel-abi = openkal` 只保证经过 `kal_*` 的行为,不保证再远的事。** 规范本身的
-接口与平台无关;缺失的能力在链接期暴露,缺失的属性由 props 查询回答。它不说明
-上面架着哪个 C 库、平台 SDK 是否可达,也不说明包其余源码是否可移植。
-
-**`c-abi = musl` 是独立的一层,有独立的保证。** 建在 openkal 的 `kernel-abi` 之上
-不等于建在某个特定的 C 库之上 —— musl 只是这一层的一种实现,由与 `kernel-abi`
-相同的依赖图解析得到;头文件或 CRT 差异(`<io.h>`、`_WIN32` 所假定的 Windows
-CRT、`TargetConditionals.h`)永远是 `c-abi` 这一层的问题,从来不是 `kernel-abi`
-的问题。一个把实际分歧记到「openkal」头上、而分歧其实出在 musl 上的包,是适配错了
-轴 —— openkal 自己的头文件什么都不 `#include`,与任何平台 SDK 都不冲突;
-会和宿主 SDK 的声明冲突的是 musl 的头文件(#662)。
-
-**平台依赖是合法的,而且必须来自依赖图,并且只对声明它的包私有。** 一个绑定到
-某个平台的包 —— 它需要该平台的头文件或导入库才能实现某个功能 —— 在
-`[feature-deps.<feature>]` 下用 `visibility = "private"` 依赖该平台 SDK,
-使这个依赖只到达它自己的翻译单元,永远不会到达消费方。
+五个层各自只保证自己那一层，层与层之间的边界，正是每个包自身适配工作应当
+所在的地方。
+
+**`kernel-abi = openkal` 只保证跨越 `kal_*` 的行为，再远的事它不保证。**
+规范本身的接口与平台无关；一项缺失的能力在链接期暴露，一项缺失的属性由 props
+查询回答。它不说明上面架着哪个 C 库，不说明某个平台 SDK 是否可达，也不说明
+包其余那部分源码是否可移植。
+
+**`c-abi = musl` 是独立的一层，有独立的保证。** 建在 openkal 的
+`kernel-abi` 之上，并不因此就是建在某个特定 C 库之上 —— musl 只是这一层的
+一种实现，由与 `kernel-abi` 相同的依赖图解析得到；一处头文件或 CRT 差异
+（`<io.h>`、`_WIN32` 所假定的 Windows CRT、`TargetConditionals.h`）永远是
+`c-abi` 这一层的问题，从来不是 `kernel-abi` 那一层的问题。一个把分歧记到
+「openkal」头上、而真正的分歧出在 musl 身上的包，是适配错了那根轴 ——
+openkal 自己的头文件什么都不 `#include`，不与任何平台 SDK 冲突；会和宿主
+SDK 的声明相冲突的，是 musl 的头文件（#662）。
+
+**平台依赖是合法的，但必须来自依赖图，并且只对声明它的那个包私有。** 一个
+绑定到某个平台的包 —— 它需要该平台的头文件或导入库才能实现某项功能 ——
+应在 `[feature-deps.<feature>]` 下用 `visibility = "private"` 依赖该平台
+SDK，使这个依赖只到达它自己的翻译单元，永远不会到达消费方。
 [06 —— Feature 与能力](06-features-and-capabilities.md#平台-sdk-依赖保持私有)
-陈述了这个模式与清单写法。不合法的是转而依赖**宿主**恰好装着的那一份 —— 这正是
-#662 关掉的头文件隔离缺口所要堵上的:平台依赖不在图中就应当是构建失败,
-而不是被静默地换了一份。
-
-**一个镜像只有一个 C 运行时和一个 C++ 运行时。** "platform-bound" 指的是平台的
-操作系统 API 表面,不是它的 C 库。一个 platform-bound 的包可以调用 Win32、
-WinSock 或 Cocoa —— 这些是带有 C 接口的系统库 —— 前提是跨越边界的只有句柄和
-普通值。它不能链接按 ucrt、msvcrt、libSystem 或 glibc 编译的静态库,也不能让
-CRT 拥有的对象跨越边界:`FILE*`、在一侧 `malloc` 在另一侧 `free`、`errno`、
-locale 状态。一个只以对着平台 CRT 编译的静态库形式分发的厂商 SDK,在 openkal
-目标上按设计就是 `n/a`,而不是遗漏。
-
-**在真正有差异的那一层上适配。** 跑在 Linux 上的 musl 和跑在 openkal 上的 musl
-共享头文件与 CRT 形状,所以头文件或 CRT 差异是 `c-abi` 的问题:
-`cfg(c-abi = "musl")`。但二者**不**共享同一套设施 —— openkal 上没有 epoll、
-没有信号处理器,`chmod` 只能改动可执行位 —— 所以设施差异首先由包**自己的**
-feature 开关回答(比如事件循环后端的选择),只有在描述文件需要自动选择时,
-才退回到组合谓词 `cfg(all(kernel-abi = "openkal", c-abi = "musl"))`。两种形式
-都不会进入包的源码:`cfg` 谓词是依赖解析时在描述文件条目之间做的选择,不是翻译
-单元能测试的宏。
-
-**源码不得识别具体是哪一个实现。** 一处 `kal_*` 调用点不会去问自己跑在
-`openkal-linux` 还是 `openkal-macos` 之上;一处 musl 调用点不会去问自己下面是
-真正的 Linux 还是 openkal。实现只在依赖解析时选择一次,这一选择之上的一切都只
-读一个接口。
+陈述了这个模式与对应的清单写法。不合法的是转而依赖宿主上恰好装着的那一份 ——
+这正是 #662 所关闭的头文件隔离缺口要堵住的东西：一个平台依赖若不在依赖图中，
+应当是一次构建失败，而不是被静默换成别的东西。
+
+**一个镜像只能有一个 C 运行时和一个 C++ 运行时。** 「platform-bound」指的是
+平台的操作系统 API 表面，不是它的 C 库。一个 platform-bound 的包可以调用
+Win32、WinSock 或 Cocoa —— 这些是带 C 接口的系统库 —— 前提是跨越这道边界的
+只有句柄与普通值。它不能链接一个按 ucrt、msvcrt、libSystem 或 glibc 编译的
+静态库，也不能让 CRT 所拥有的对象跨越这道边界：一个 `FILE*`、在一侧
+`malloc` 而在另一侧 `free` 的内存、`errno`、locale 状态。一个只以针对平台
+CRT 编译的静态库形式分发的厂商 SDK，在一个 openkal target 上按设计就是
+`n/a`，这不是一处遗漏。
+
+**在真正存在差异的那一层上适配。** 跑在 Linux 上的 musl 与跑在 openkal 上
+的 musl，共享头文件与 CRT 的形状，因此一处头文件或 CRT 差异是一个 `c-abi`
+问题：`cfg(c-abi = "musl")`。但两者**不**共享同一套设施 —— openkal 上没有
+epoll，没有信号处理器，`chmod` 只能改动可执行位 —— 因此一处设施差异，首先
+应由包**自己的** feature 开关回答，只要存在这样一个开关（比如某个事件循环
+后端的选择），只有在一份描述文件需要自动做选择时，才退回到一个组合谓词：
+`cfg(all(kernel-abi = "openkal", c-abi = "musl"))`。两种形式都不会进入包的
+源码：一个 `cfg` 谓词是在依赖解析时于若干描述文件条目之间做的选择，不是一个
+翻译单元能够测试的宏。
+
+**源码不得侦测当前具体是哪一份实现。** 一处 `kal_*` 调用点不会去问自己此刻
+跑在 `openkal-linux` 还是 `openkal-macos` 之上；一处 musl 调用点不会去问
+自己下面是真正的 Linux 还是 openkal。实现只在依赖解析时被选择一次，而这一
+选择之上的一切代码，读到的都只是一个接口。
 
 ## 参考
 
-[docs/22 — 目标侧](22-target-side.md) 给出五个层、四种来源与规则。
-[docs/06 — Feature 与能力](06-features-and-capabilities.md) 给出
-`[feature-deps.<name>]` 与依赖私有可见性。
-[SPEC-002](../specs/target-side.md) 给出能力语法的规范性陈述。
-
+[docs/22 —— 目标侧](22-target-side.md) 给出五个层、四种来源，以及相应的
+规则。[docs/06 —— Feature 与能力](06-features-and-capabilities.md) 给出
+`[feature-deps.<name>]` 与依赖私有可见性。[SPEC-002](../specs/target-side.md)
+给出能力语法的规范性陈述。
diff --git a/docs/zh/30-build-mcpp.md b/docs/zh/30-build-mcpp.md
index 014aa6759..80c2d41c7 100644
--- a/docs/zh/30-build-mcpp.md
+++ b/docs/zh/30-build-mcpp.md
@@ -1,23 +1,23 @@
-# 30 —— 构建程序:`build.mcpp`
+# 30 —— 构建程序：`build.mcpp`
 
 [English](../30-build-mcpp.md) | **简体中文**
 
-**读者:**构建里需要一步 mcpp 没有规则的工作的作者 —— 代码生成、嵌入资源、
-一项检查,或者第二个编译器。
+**读者：**构建里需要一步 mcpp 没有规则的工作的作者 —— 代码生成、嵌入资源、
+一项检查，或者第二个编译器。
 
-**本章回答的那一个问题:**怎样把这份工作加进构建图,使它像其余部分一样被定序、
+**本章回答的那一个问题：**怎样把这份工作加进构建图，使它像其余部分一样被定序、
 进指纹、可增量。
 
-**不在这里:**把这一步打包给别的工程用,那是
-[31 —— 编写规则包](31-authoring-a-rule-package.md);以及这一步要跑的工具,那是
+**不在这里：**把这一步打包给别的工程用，那是
+[31 —— 编写规则包](31-authoring-a-rule-package.md)；以及这一步要跑的工具，那是
 [23 —— 项目环境](23-the-project-environment.md)。
 
 绝大多数工程只需要 `mcpp.toml`。需要构建期逻辑时 —— 探测主机、生成源码、依据环境
 决定某个编译开关——就在工程根目录放一个 `build.mcpp`。它是 mcpp 版的 Zig `build.zig`
-/ Cargo `build.rs`,但用 **C++** 编写:不引入第二种语言,而且 mcpp 自己吃自己的狗粮。
+/ Cargo `build.rs`，但用 **C++** 编写：不引入第二种语言，而且 mcpp 自己吃自己的狗粮。
 
-mcpp 用当前工具链编译 `build.mcpp`,并在主构建**之前**运行它。程序通过向 stdout 打印
-`mcpp:` 指令与 mcpp 通信,这些指令会增补本次构建。
+mcpp 用当前工具链编译 `build.mcpp`，并在主构建**之前**运行它。程序通过向 stdout 打印
+`mcpp:` 指令与 mcpp 通信，这些指令会增补本次构建。
 
 ## 快速示例
 
@@ -27,72 +27,72 @@ mcpp 用当前工具链编译 `build.mcpp`,并在主构建**之前**运行它。
 #include <fstream>
 
 int main() {
-    // 生成一份源码,主构建会编译 + 链接它。
+    // Generate a source the main build will compile + link.
     std::ofstream("src/generated.cpp") << "const char* banner() { return \"hi\"; }\n";
 
-    std::puts("mcpp:generated=src/generated.cpp");   // 加入构建
-    std::puts("mcpp:cxxflag=-DHAVE_BANNER=1");        // 为所有 C++ TU 定义宏
+    std::puts("mcpp:generated=src/generated.cpp");   // add it to the build
+    std::puts("mcpp:cxxflag=-DHAVE_BANNER=1");        // define a macro for all C++ TUs
 
     if (std::getenv("USE_FAST")) std::puts("mcpp:cxxflag=-DFAST_PATH=1");
-    std::puts("mcpp:rerun-if-env-changed=USE_FAST");  // USE_FAST 变化时重跑我
+    std::puts("mcpp:rerun-if-env-changed=USE_FAST");  // re-run me when USE_FAST changes
     return 0;
 }
 ```
 
 ```bash
-mcpp build      # 编译 + 运行 build.mcpp,然后构建工程
+mcpp build      # compiles + runs build.mcpp, then builds the project
 ```
 
 ## 指令
 
-把这些打印到 stdout(每行一条)。任何不以 `mcpp:` 开头的行都会被忽略,因此可以
+把这些打印到 stdout（每行一条）。任何不以 `mcpp:` 开头的行都会被忽略，因此可以
 自由打印诊断日志。
 
 | 指令 | 作用 |
 |---|---|
-| `mcpp:cxxflag=<flag>`              | 给 C++ 编译追加 `<flag>`;`<flag>` 按[编译 flag 的写法](04-mcpp-toml.md#编译-flag-的写法-mcpp-20269171)读取(2026.9.17.1+) |
-| `mcpp:cflag=<flag>`                | 给 C 编译追加 `<flag>`,读法相同 |
+| `mcpp:cxxflag=<flag>`              | 给 C++ 编译追加 `<flag>`；`<flag>` 按[编译 flag 的写法](04-mcpp-toml.md#编译-flag-的写法-mcpp-20269171)读取（2026.9.17.1+） |
+| `mcpp:cflag=<flag>`                | 给 C 编译追加 `<flag>`，读法相同 |
 | `mcpp:link-lib=<name>`             | 链接 `-l<name>` |
-| `mcpp:link-search=<dir>`           | 增加库搜索目录(`-L`;相对路径按工程根目录解析) |
-| `mcpp:cfg=<name>`                  | 为 C 与 C++ 同时定义 `-D<name>`;`<name>` 是一个值,与 `defines` 条目相同 |
-| `mcpp:generated=<path>`            | 把生成的源码加入构建。**相对路径在根工程按工程根解析,在依赖的 build.mcpp 里按 `MCPP_OUT_DIR` 解析** —— 两种角色都可能出现的包应发绝对路径(见下文) |
-| `mcpp:source=<path>` *(0.0.100+)*  | 把一份**既有**源文件选入构建(绝对路径,或相对包根)。下游效果与 `generated=` 相同;语义区别在于文件是程序*选中*的(tarball payload / vendored 源树)而非程序写出的——例如对大型源码包做 per-target 源选择 |
-| `mcpp:include-dir=<dir>` *(0.0.100+)* | 为本包自身 TU 增加一个**私有** include 目录(`-I`;绝对路径或相对包根,自动规范化)。取代过去 `cxxflag=-I` + `cflag=-I` 的双重裸发 |
-| `mcpp:include-dir-after=<dir>` *(0.0.100+)* | 同 `include-dir`,但排在系统目录**之后**搜索(`-idirafter`)——用于会遮蔽系统头的 payload 源树 |
-| `mcpp:runner=<token>` *(2026.8.19.2+)* | 执行本次构建产物的命令的**一个 argv token**(宿主跑不了它时)。一个 token 一次调用、按顺序;产物路径会被追加(或替换 `{}`)。**到达消费者**。可执行文件要发**绝对路径**,且**只能有一个**依赖提供它 |
-| `mcpp:link-flag=<flag>` *(2026.9.6.5+)* | 加一条本程序**算出来的**链接标志,原样传递。这是 `link-lib` / `link-search` / `link-script` 各自命名一类东西之后留下的出口:生成的版本脚本(`-Wl,--version-script=`)、运行时接管 C 库符号用的 `-Wl,--wrap=malloc`、以及 `-Wl,--exclude-libs,ALL`(静态吞入的第三方不得成为本包 ABI 的一部分)。按发出顺序追加在 `[build] ldflags` 之后。**到达消费者**,与 `[build] ldflags` 一致 —— 理由见下 |
-| `mcpp:windows-subsystem=<target>:<value>` *(2026.9.12.2+)* | 设置**本包**可执行目标 `<target>` 的 PE 子系统(`console` 或 `windows`),与 `[targets.<target>] windows_subsystem`(docs/04)是同一字段。只到达该目标的链接,不到达其他目标或消费者,在非 PE 目标上不产生任何标志。本包未以 `kind = "bin"` 声明该目标、取值不在集合内、取值与 mcpp.toml 的声明矛盾,这三种情形都在应用任何指令之前被拒绝 |
-| `mcpp:windows-entry=<target>:<value>` *(2026.9.12.2+)* | 设置可执行目标 `<target>` 的入口函数(`main`、`wmain`、`WinMain` 或 `wWinMain`),与 `windows_entry` 是同一字段;作用域与拒绝条件同 `windows-subsystem` |
-| `mcpp:deploy=<from>\t<to>` *(2026.9.12.3+,protocol 11)* | 把本程序生成或选中的一个文件放到产物旁边的 `<to>`(相对可执行文件所在目录)——`[runtime] deploy`(docs/04 §2.11)的构建程序形态。`<from>` 可以是绝对路径(某个 action 自己声明的输出),也可以按包根解析;用 TAB 分隔,因为一个绝对的 Windows `<from>` 本身含冒号。**到达消费者**,并入同一个被 `link-lib`/`link-search`/`link-flag` 喂入的 `LinkIntent`——见下 |
-| `mcpp:link-script=<path>` *(2026.8.19+)* | 用这个**链接脚本**链接(`-T`;相对路径按包根解析,发出的是绝对路径,因为链接是在构建目录里跑的)。与 `include-dir` 不同,它**到达消费者** —— 板子的内存布局恰恰是消费者写不出来的那一项 |
+| `mcpp:link-search=<dir>`           | 增加库搜索目录（`-L`；相对路径按工程根目录解析） |
+| `mcpp:cfg=<name>`                  | 为 C 与 C++ 同时定义 `-D<name>`；`<name>` 是一个值，与 `defines` 条目相同 |
+| `mcpp:generated=<path>`            | 把生成的源码加入构建。**相对路径在根工程按工程根解析，在依赖的 build.mcpp 里按 `MCPP_OUT_DIR` 解析** —— 两种角色都可能出现的包应发绝对路径（见下文） |
+| `mcpp:source=<path>` *(0.0.100+)*  | 把一份**既有**源文件选入构建（绝对路径，或相对包根）。下游效果与 `generated=` 相同；语义区别在于文件是程序*选中*的（tarball payload / vendored 源树）而非程序写出的——例如对大型源码包做 per-target 源选择 |
+| `mcpp:include-dir=<dir>` *(0.0.100+)* | 为本包自身 TU 增加一个**私有** include 目录（`-I`；绝对路径或相对包根，自动规范化）。取代过去 `cxxflag=-I` + `cflag=-I` 的双重裸发 |
+| `mcpp:include-dir-after=<dir>` *(0.0.100+)* | 同 `include-dir`，但排在系统目录**之后**搜索（`-idirafter`）——用于会遮蔽系统头的 payload 源树 |
+| `mcpp:runner=<token>` *(2026.8.19.2+)* | 执行本次构建产物的命令的**一个 argv token**（宿主跑不了它时）。一个 token 一次调用、按顺序；产物路径会被追加（或替换 `{}`）。**到达消费者**。可执行文件要发**绝对路径**，且**只能有一个**依赖提供它 |
+| `mcpp:link-flag=<flag>` *(2026.9.6.5+)* | 加一条本程序**算出来的**链接标志，原样传递。这是 `link-lib` / `link-search` / `link-script` 各自命名一类东西之后留下的出口：生成的版本脚本（`-Wl,--version-script=`）、运行时接管 C 库符号用的 `-Wl,--wrap=malloc`、以及 `-Wl,--exclude-libs,ALL`（静态吞入的第三方不得成为本包 ABI 的一部分）。按发出顺序追加在 `[build] ldflags` 之后。**到达消费者**，与 `[build] ldflags` 一致 —— 理由见下 |
+| `mcpp:windows-subsystem=<target>:<value>` *(2026.9.12.2+)* | 设置**本包**可执行目标 `<target>` 的 PE 子系统（`console` 或 `windows`），与 `[targets.<target>] windows_subsystem`（docs/04）是同一字段。只到达该目标的链接，不到达其他目标或消费者，在非 PE 目标上不产生任何标志。本包未以 `kind = "bin"` 声明该目标、取值不在集合内、取值与 mcpp.toml 的声明矛盾，这三种情形都在应用任何指令之前被拒绝 |
+| `mcpp:windows-entry=<target>:<value>` *(2026.9.12.2+)* | 设置可执行目标 `<target>` 的入口函数（`main`、`wmain`、`WinMain` 或 `wWinMain`），与 `windows_entry` 是同一字段；作用域与拒绝条件同 `windows-subsystem` |
+| `mcpp:deploy=<from>\t<to>` *(2026.9.12.3+,protocol 11)* | 把本程序生成或选中的一个文件放到产物旁边的 `<to>`（相对可执行文件所在目录）——`[runtime] deploy`（docs/04 §2.11）的构建程序形态。`<from>` 可以是绝对路径（某个 action 自己声明的输出），也可以按包根解析；用 TAB 分隔，因为一个绝对的 Windows `<from>` 本身含冒号。**到达消费者**，并入同一个被 `link-lib`/`link-search`/`link-flag` 喂入的 `LinkIntent`——见下 |
+| `mcpp:link-script=<path>` *(2026.8.19+)* | 用这个**链接脚本**链接（`-T`；相对路径按包根解析，发出的是绝对路径，因为链接是在构建目录里跑的）。与 `include-dir` 不同，它**到达消费者** —— 板子的内存布局恰恰是消费者写不出来的那一项 |
 | `mcpp:warning=<text>` *(2026.8.21.2+)* | 对用户说一句话并**继续**。唯一一条不改变编译行、链接行与源码集的指令。它**穿过构建缓存** —— 见下 |
-| `mcpp:fact=<name>=<version>` *(2026.9.5.2+)* | 陈述程序**测得的机器事实**(`cuda.driver=12.4`)。在编译任何东西之前与 floor 比较;见下 |
-| `mcpp:floor=<name> >= <version>` *(2026.9.5.2+)* | 陈述本包对该量的**下界**。不满足 ⇒ 构建被拒并给出两侧取值(`version-floor-unmet`);没有人陈述事实的下界保持沉默 |
+| `mcpp:fact=<name>=<version>` *(2026.9.5.2+)* | 陈述程序**测得的机器事实**(`cuda.driver=12.4`)。在编译任何东西之前与 floor 比较；见下 |
+| `mcpp:floor=<name> >= <version>` *(2026.9.5.2+)* | 陈述本包对该量的**下界**。不满足 ⇒ 构建被拒并给出两侧取值（`version-floor-unmet`）；没有人陈述事实的下界保持沉默 |
 | `mcpp:rerun-if-changed=<path>`     | 该文件变化时重跑 `build.mcpp` |
 | `mcpp:rerun-if-env-changed=<VAR>`  | 该环境变量变化时重跑 `build.mcpp` |
 
-程序**请求**构建边(开关、库、源码),它**不能**新增注册表依赖——请把依赖图保持在
-`mcpp.toml` 里声明式管理(包括平台条件依赖 `[target.windows.dependencies]`)。
-`build.mcpp` 用于*叶子*决策:开关、代码生成、链接需求。
+程序**请求**构建边（开关、库、源码），它**不能**新增注册表依赖——请把依赖图保持在
+`mcpp.toml` 里声明式管理（包括平台条件依赖 `[target.windows.dependencies]`）。
+`build.mcpp` 用于*叶子*决策：开关、代码生成、链接需求。
 
-`link-flag` 刻意**不**私有,而这一点值得说明,因为相反的选择看上去更安全。编译接口有
-一个声明式的公开对应物(`[build] include_dirs`),所以构建期程序若能加宽它就是绕过了
-manifest —— 这正是 `include-dir` 私有的理由。链接标志没有这个分裂:`[build] ldflags`
-本来就传播给消费者,因此一个私有的"算出来"形态会与它自己的声明式孪生行为不一致。
+`link-flag` 刻意**不**私有，而这一点值得说明，因为相反的选择看上去更安全。编译接口有
+一个声明式的公开对应物（`[build] include_dirs`），所以构建期程序若能加宽它就是绕过了
+manifest —— 这正是 `include-dir` 私有的理由。链接标志没有这个分裂：`[build] ldflags`
+本来就传播给消费者，因此一个私有的"算出来"形态会与它自己的声明式孪生行为不一致。
 
-后果写明而不藏起来:一个依赖发出 `-Wl,--version-script=`,该标志也会落到消费者的链接
-行上,而那通常不是它的本意。这个隐患不是新的 —— 依赖在 `[build] ldflags` 里写同一条
-标志一直如此 —— 所以这条指令加宽的是**谁能算出这个值**,不是**这个值能到达哪里**。
+后果写明而不藏起来：一个依赖发出 `-Wl,--version-script=`，该标志也会落到消费者的链接
+行上，而那通常不是它的本意。这个隐患不是新的 —— 依赖在 `[build] ldflags` 里写同一条
+标志一直如此 —— 所以这条指令加宽的是**谁能算出这个值**，不是**这个值能到达哪里**。
 
-`include-dir`/`include-dir-after` 刻意保持**私有**(Cargo 纪律):只染色本包自身的
-TU,绝不向消费者传播。需要消费者可见的 include 目录属于公共接口,应写在声明式
-manifest/描述符里(`[build] include_dirs`),而不是构建期程序里。
+`include-dir`/`include-dir-after` 刻意保持**私有**（Cargo 纪律）：只染色本包自身的
+TU，绝不向消费者传播。需要消费者可见的 include 目录属于公共接口，应写在声明式
+manifest/描述符里（`[build] include_dirs`），而不是构建期程序里。
 
-## 类型化 API:`import mcpp;`(推荐)
+## 类型化 API：`import mcpp;`（推荐）
 
-除打印裸字符串外,`build.mcpp` 也可以写成**模块优先**形式——`import mcpp;`,不需要
-`#include`。`mcpp` 模块**内置在 mcpp 二进制里**(因此始终与当前这版 mcpp
-的协议匹配),按需编译;它的函数只是 emit 上面那些指令:
+除打印裸字符串外，`build.mcpp` 也可以写成**模块优先**形式——`import mcpp;`，不需要
+`#include`。`mcpp` 模块**内置在 mcpp 二进制里**（因此始终与当前这版 mcpp
+的协议匹配），按需编译；它的函数只是 emit 上面那些指令：
 
 ```cpp
 // build.mcpp
@@ -113,88 +113,88 @@ int main() {
 |---|---|
 | `mcpp::cxxflag(s)` / `mcpp::cflag(s)` | `mcpp:cxxflag=` / `mcpp:cflag=` |
 | `mcpp::link_lib(s)` / `mcpp::link_search(s)` | `mcpp:link-lib=` / `mcpp:link-search=` |
-| `mcpp::define(s)` | `mcpp:cfg=`(即 `-D<s>`) |
+| `mcpp::define(s)` | `mcpp:cfg=`（即 `-D<s>`） |
 | `mcpp::generated(p)` | `mcpp:generated=` |
 | `mcpp::source(p)` | `mcpp:source=` |
 | `mcpp::include_dir(d)` / `mcpp::include_dir_after(d)` | `mcpp:include-dir=` / `mcpp:include-dir-after=` |
 | `mcpp::rerun_if_changed(p)` / `mcpp::rerun_if_env_changed(v)` | 对应的 `rerun-*` 指令 |
-| `mcpp::rerun_if_changed_glob(pat)` *(2026.8.6.2+)* | `mcpp:rerun-if-changed-glob=` —— 匹配 `pat` 的文件**集合**发生变化时重跑(见下) |
-| `mcpp::dep_bin(pkg, tool)` *(2026.8.5.1+)* | 读 `MCPP_DEP_<PKG>_BIN_<TOOL>` —— 依赖构建出的 **host 工具**的绝对路径(见下) |
+| `mcpp::rerun_if_changed_glob(pat)` *(2026.8.6.2+)* | `mcpp:rerun-if-changed-glob=` —— 匹配 `pat` 的文件**集合**发生变化时重跑（见下） |
+| `mcpp::dep_bin(pkg, tool)` *(2026.8.5.1+)* | 读 `MCPP_DEP_<PKG>_BIN_<TOOL>` —— 依赖构建出的 **host 工具**的绝对路径（见下） |
 | `mcpp::link_flag(s)` *(2026.9.6.5+)* | `mcpp:link-flag=` |
 | `mcpp::windows_subsystem(target, value)` / `mcpp::windows_entry(target, value)` *(2026.9.12.2+)* | `mcpp:windows-subsystem=` / `mcpp:windows-entry=` |
 | `mcpp::deploy(from, to)` *(2026.9.12.3+,protocol 11)* | `mcpp:deploy=<from>\t<to>` —— 见下 |
 | `mcpp::link_script(p)` *(2026.8.19+)* | `mcpp:link-script=` |
 | `mcpp::runner(tok)` *(2026.8.19.2+)* | `mcpp:runner=` —— 见下 |
-| `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | `[xlings.workspace]` 里声明的包的载荷目录 —— 本 manifest 声明的,或编进本构建程序的某个依赖声明的(2026.9.6.6+);没声明或没安装时返回 `""`(见下) |
+| `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | `[xlings.workspace]` 里声明的包的载荷目录 —— 本 manifest 声明的，或编进本构建程序的某个依赖声明的（2026.9.6.6+）；没声明或没安装时返回 `""`（见下） |
 | `mcpp::warning(text)` *(2026.8.21.2+)* | `mcpp:warning=` —— 见下 |
-| `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` —— **声明一个构建图节点**,而不是在这里把活干了(见下) |
+| `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` —— **声明一个构建图节点**，而不是在这里把活干了（见下） |
 
-### `warning` —— 成功了,而且仍然被听见(2026.8.21.2+)
+### `warning` —— 成功了，而且仍然被听见（2026.8.21.2+）
 
-构建程序的输出**只在程序非零退出时**到达用户:mcpp 抓取它,并在失败时打印抓到的东西。
-于是 `std::printf` 或 `std::fprintf(stderr, ...)` 写的提示,在**恰恰需要它的那些成功
+构建程序的输出**只在程序非零退出时**到达用户：mcpp 抓取它，并在失败时打印抓到的东西。
+于是 `std::printf` 或 `std::fprintf(stderr, ...)` 写的提示，在**恰恰需要它的那些成功
 构建**上一个字都不显示。
 
 ```cpp
 if (const char* dir = mcpp::xpkg_dir("xim", "qemu-riscv"); dir && *dir) {
     mcpp::runner(std::format("{}/bin/qemu-system-riscv64", dir).c_str());
-    // …… 其余 argv ……
+    // … the rest of the argv …
 } else {
-    mcpp::warning("qemu-riscv 未安装,于是 `mcpp run` 没有 runner。"
-                  "装一次即可:  xlings install qemu-riscv -y");
+    mcpp::warning("qemu-riscv is not installed, so `mcpp run` has no runner. "
+                  "Install it once:  xlings install qemu-riscv -y");
 }
 ```
 
-**它之所以存在,是因为两个替代方案都更差,而且都试过。** 写到 stderr 的提示在成功
-构建上什么都不打印。非零退出也不对:`mcpp build` 并不需要模拟器,让一个正确的构建失败,
+**它之所以存在，是因为两个替代方案都更差，而且都试过。** 写到 stderr 的提示在成功
+构建上什么都不打印。非零退出也不对：`mcpp build` 并不需要模拟器，让一个正确的构建失败，
 是用一句缺失的话换一条坏掉的命令。
 
-用它来说一个程序**已经正确处理**、但用户会想知道的情况 —— 最常见的是「我没找到 X,所以
-我没有配置任何依赖它的东西」。要报错就非零退出,那条路径的输出已经会被打印。
+用它来说一个程序**已经正确处理**、但用户会想知道的情况 —— 最常见的是「我没找到 X，所以
+我没有配置任何依赖它的东西」。要报错就非零退出，那条路径的输出已经会被打印。
 
 **它不会让构建失败。** `mcpp build` 仍然退出 0。
 
-**它带归属。** 该行显示为 `<包名>: <文字>`,因为一个 workspace 里可能有好几个程序在说话,
+**它带归属。** 该行显示为 `<包名>: <文字>`，因为一个 workspace 里可能有好几个程序在说话，
 而读者需要知道该打开哪一份清单。
 
-**它穿过构建缓存。** 构建程序的结果是被缓存的,命中时不再运行 —— 所以一条只活在运行
-路径上的提示,会在工程的第一次构建出现、之后再也不出现,而那读起来像「问题已解决」。
+**它穿过构建缓存。** 构建程序的结果是被缓存的，命中时不再运行 —— 所以一条只活在运行
+路径上的提示，会在工程的第一次构建出现、之后再也不出现，而那读起来像「问题已解决」。
 mcpp 在每次命中时重放它。
 
-**全工程 no-op 构建什么都不打印,包括这一条。** 无事可做时,构建根本到不了
-`build.mcpp` 阶段 —— 它同样不会报告构建了哪个目标、推断了哪些源码。touch 一下源码,提示
+**全工程 no-op 构建什么都不打印，包括这一条。** 无事可做时，构建根本到不了
+`build.mcpp` 阶段 —— 它同样不会报告构建了哪个目标、推断了哪些源码。touch 一下源码，提示
 就回来了。
 
-### 探针通道:`fact` / `floor`(2026.9.5.2+)
+### 探针通道：`fact` / `floor`（2026.9.5.2+）
 
-规则包是知道「怎么问机器它有什么」的那一方 —— 打开哪个库、调用哪个函数;
-引擎则是不该知道的那一方。于是由包来**测量**,由引擎来**比较**:
+规则包是知道「怎么问机器它有什么」的那一方 —— 打开哪个库、调用哪个函数；
+引擎则是不该知道的那一方。于是由包来**测量**，由引擎来**比较**：
 
 ```cpp
-mcpp::fact("cuda.driver", "12.4");      // 这台机器有什么
-mcpp::floor("cuda.driver >= 12.0");     // 本包需要它至少多新
+mcpp::fact("cuda.driver", "12.4");      // what this machine has
+mcpp::floor("cuda.driver >= 12.0");     // what this package needs of it
 ```
 
-在编译任何东西之前,未满足的下界会拒绝构建,并点名该量、两侧版本与陈述事实的
-包;`mcpp why toolchain --format json` 把它归类为 `reason: version-floor-unmet`。没有人陈述事实的下界
-**保持沉默**:不知道不等于不满足,由无知制造的拒绝是更坏的错误。
+在编译任何东西之前，未满足的下界会拒绝构建，并点名该量、两侧版本与陈述事实的
+包；`mcpp why toolchain --format json` 把它归类为 `reason: version-floor-unmet`。没有人陈述事实的下界
+**保持沉默**：不知道不等于不满足，由无知制造的拒绝是更坏的错误。
 
-它防住的失败在构建期本身看不见:针对比驱动更新的设备运行时构建的程序,编译
-干净、链接干净,到第一次使用才失败,而消息两边都不点名。解析了该运行时的规则包
+它防住的失败在构建期本身看不见：针对比驱动更新的设备运行时构建的程序，编译
+干净、链接干净，到第一次使用才失败，而消息两边都不点名。解析了该运行时的规则包
 在第一次编译之前就知道两个数字。
 
-**两个字符串对引擎都没有意义。** `cuda.driver` 是流过引擎的数据;引擎读到的
-是一个名字、一个关系、一个版本,第二个后端不需要改引擎。事实的拼法与包在
-`[runtime] provides` 里静态声明的一致,下界与 `[[runtime.requirements]]` 的
-`kind = "version-floor"` 一致:两条通道落进同一张表。
+**两个字符串对引擎都没有意义。** `cuda.driver` 是流过引擎的数据；引擎读到的
+是一个名字、一个关系、一个版本，第二个后端不需要改引擎。事实的拼法与包在
+`[runtime] provides` 里静态声明的一致，下界与 `[[runtime.requirements]]` 的
+`kind = "version-floor"` 一致：两条通道落进同一张表。
 
-**事实随程序的其它输出一起进缓存**,命中时被回放。要声明什么会改变它 ——
+**事实随程序的其它输出一起进缓存**，命中时被回放。要声明什么会改变它 ——
 对读出版本的那个库 `rerun_if_changed` —— 否则事实会比它描述的机器活得更久。
 
-### `runner` —— 产物的执行方式(2026.8.19.2+)
+### `runner` —— 产物的执行方式（2026.8.19.2+）
 
-板级支持包知道模拟器、机器型号和固件模式,也知道模拟器**在哪** —— 而静态 manifest
-写不出来:载荷路径里带着 home 和版本号。
+板级支持包知道模拟器、机器型号和固件模式，也知道模拟器**在哪** —— 而静态 manifest
+写不出来：载荷路径里带着 home 和版本号。
 
 ```cpp
 const char* qemu = mcpp::xpkg_dir("xim", "qemu-riscv");
@@ -203,94 +203,94 @@ for (auto a : {"-machine","virt","-nographic","-no-reboot","-kernel"})
     mcpp::runner(a);
 ```
 
-这样消费者**完全不需要 `[target.<triple>]` 段**。它若还是写了,**以它为准** ——
+这样消费者**完全不需要 `[target.<triple>]` 段**。它若还是写了，**以它为准** ——
 调试时把 `-bios default` 换成 `-bios none -semihosting` 是正当需求 —— 且 mcpp 会说明
 它覆盖了哪个依赖。
 
-**可执行文件要发绝对路径。** 裸名会经 `PATH` 解析到一个 shim,而 shim 按**拥有它
-的 home** 派发,那未必是本次构建用的 home。
+**可执行文件要发绝对路径。** 裸名会经 `PATH` 解析到一个 shim，而 shim 按**拥有它
+的 home** 派发，那未必是本次构建用的 home。
 
 **只能有一个依赖提供 runner。** 两个板级支持包都声称知道怎么跑这个产物是配置
-错误;mcpp 会**同时点名两个**并报错,而不是把它们并成一个谁也不是的 argv。
+错误；mcpp 会**同时点名两个**并报错，而不是把它们并成一个谁也不是的 argv。
 
-**在一个构建程序之内,每个名字的 token 组成一个 argv。** 每次 `mcpp::runner(tok)`
-调用追加到默认 runner,每次 `mcpp::runner(name, tok)` 调用追加到名为 `name` 的
-runner,按发出顺序,无论调用来自编译进这个程序的哪个 host module。要在两个 runner
-之间选择的程序,在发出任何一个之前完成选择。以打包格式命名的 runner 在
-`mcpp run --format <name>` 下抵达该格式的可分发物([41 —— 抵达一台设备](41-devices.md))。
+**在一个构建程序之内，每个名字的 token 组成一个 argv。** 每次 `mcpp::runner(tok)`
+调用追加到默认 runner，每次 `mcpp::runner(name, tok)` 调用追加到名为 `name` 的
+runner，按发出顺序，无论调用来自编译进这个程序的哪个 host module。要在两个 runner
+之间选择的程序，在发出任何一个之前完成选择。以打包格式命名的 runner 在
+`mcpp run --format <name>` 下抵达该格式的可分发物（[41 —— 抵达一台设备](41-devices.md)）。
 
-### 问,而不是声明:`toolchain_dir` / `sysroot_dir`(2026.8.19.4+)
+### 问，而不是声明：`toolchain_dir` / `sysroot_dir`（2026.8.19.4+）
 
 ```cpp
-const char* tc = mcpp::toolchain_dir();   // 已解析工具链的载荷根目录
-const char* sr = mcpp::sysroot_dir();     // 目标的 C 库根目录,没有则为 ""
+const char* tc = mcpp::toolchain_dir();   // the resolved toolchain's payload root
+const char* sr = mcpp::sysroot_dir();     // the TARGET's C library root, or ""
 ```
 
-一个包需要工具链自带的头(比如 freestanding 标准库子集要的 libc++ 头),或者需要
-目标 C 库里的某个**文件**(比如板级支持包要的链接脚本)时,应当**问这个目录在哪**,
+一个包需要工具链自带的头（比如 freestanding 标准库子集要的 libc++ 头），或者需要
+目标 C 库里的某个**文件**（比如板级支持包要的链接脚本）时，应当**问这个目录在哪**，
 而不是去声明一个依赖来把它拽进来。
 
-这不是写法差异。声明 `xim:llvm` 会把包**钉死在一个标准库实现**上;声明
+这不是写法差异。声明 `xim:llvm` 会把包**钉死在一个标准库实现**上；声明
 `xim:picolibc-riscv@1.8.12` 会把它钉死在**一个 C 库、一种架构、一个版本**上。而这些
 都不是一个内容全是标准规定的名字的包的属性。**问**则会跟随 `[toolchain]` 与
 `--target` 真正解析到的结果。
 
-宿主目标上 `sysroot_dir()` 为空:那里 C 库随编译器载荷或运行时绑定而来,没人需要找它。
+宿主目标上 `sysroot_dir()` 为空：那里 C 库随编译器载荷或运行时绑定而来，没人需要找它。
 
-### 驱动第二个编译器:`toolchain_sysroot` / `toolchain_binutils_dir`(2026.9.5.2+)
+### 驱动第二个编译器：`toolchain_sysroot` / `toolchain_binutils_dir`（2026.9.5.2+）
 
 ```cpp
-const char* sr = mcpp::toolchain_sysroot();        // mcpp 传的 `--sysroot`,没有则为 ""
-const char* bu = mcpp::toolchain_binutils_dir();   // mcpp 用 `-B` 指的目录,没有则为 ""
+const char* sr = mcpp::toolchain_sysroot();        // the `--sysroot` mcpp passes, or ""
+const char* bu = mcpp::toolchain_binutils_dir();   // the dir mcpp names with `-B`, or ""
 ```
 
-规则包有时必须运行一个 **mcpp 并未解析**的编译器。`nvcc` 拒绝 libc++ 宿主编译器,
-在 GCC 16 的 `<type_traits>` 上失败,因此 CUDA 规则包要从声明的载荷里另选一个宿主
-编译器;`hipcc` 与 `-fsycl-host-compiler` 面对同一个问题。
+规则包有时必须运行一个 **mcpp 并未解析**的编译器。`nvcc` 拒绝 libc++ 宿主编译器，
+在 GCC 16 的 `<type_traits>` 上失败，因此 CUDA 规则包要从声明的载荷里另选一个宿主
+编译器；`hipcc` 与 `-fsycl-host-compiler` 面对同一个问题。
 
-那个编译器对自己被放进的环境一无所知。在 sub-OS 里 C 库不在 `/usr/include`,汇编器
-不在 `/usr/bin`,于是它遇到的第一个 `#include` 就失败:
+那个编译器对自己被放进的环境一无所知。在 sub-OS 里 C 库不在 `/usr/include`，汇编器
+不在 `/usr/bin`，于是它遇到的第一个 `#include` 就失败：
 
 ```
 crt/host_config.h:218: fatal error: features.h: No such file or directory
 ```
 
 这两个答案就是 mcpp 为同一目标传给自己那个编译器的开关。把它们转发过去
-——`--sysroot=<值>` 与 `-B<值>`,经外层工具的宿主选项拼法——第二个编译器就看到
+——`--sysroot=<值>` 与 `-B<值>`，经外层工具的宿主选项拼法——第二个编译器就看到
 第一个看到的东西。
 
-**不是 `sysroot_dir()`。** 那个回答的是目标**档位**的问题,在宿主目标上为空,
-而宿主目标恰恰是这一对存在的场合。mcpp 不传某个开关时,对应的那个为空串。
+**不是 `sysroot_dir()`。** 那个回答的是目标**档位**的问题，在宿主目标上为空，
+而宿主目标恰恰是这一对存在的场合。mcpp 不传某个开关时，对应的那个为空串。
 
-### 载荷的 pkg-config 视图:`pkg_config_libdir`(2026.9.14.2+)
+### 载荷的 pkg-config 视图：`pkg_config_libdir`（2026.9.14.2+）
 
 ```cpp
 const char* dirs = mcpp::pkg_config_libdir();
 // <registry>/subos/default/usr/lib/pkgconfig:<registry>/subos/default/usr/share/pkgconfig
 ```
 
-mcpp 安装的载荷的 pkg-config 搜索路径,以平台的路径列表分隔符连接。载荷配方把自己的
-`.pc` 文件声明进这个视图,因此由载荷提供的库连同它的整个 pkg-config 闭包都能解析:
+mcpp 安装的载荷的 pkg-config 搜索路径，以平台的路径列表分隔符连接。载荷配方把自己的
+`.pc` 文件声明进这个视图，因此由载荷提供的库连同它的整个 pkg-config 闭包都能解析：
 
 ```cpp
 std::string cmd = std::string("PKG_CONFIG_LIBDIR=") + mcpp::pkg_config_libdir()
                 + " pkg-config --cflags --libs gtk4";
 ```
 
-**这是访问器,不是环境默认值。** 构建程序的环境不携带 `PKG_CONFIG_LIBDIR`,因此
-指宿主自己 pkg-config 数据库的包照旧,指载荷的包自己写明。该值与链接模式以及解析出
+**这是访问器，不是环境默认值。** 构建程序的环境不携带 `PKG_CONFIG_LIBDIR`，因此
+指宿主自己 pkg-config 数据库的包照旧，指载荷的包自己写明。该值与链接模式以及解析出
 哪个工具链无关。
 
-### 解析出的 C++ 标准库:`cxx_stdlib`(2026.9.6.3+)
+### 解析出的 C++ 标准库：`cxx_stdlib`（2026.9.6.3+）
 
 ```cpp
 const char* impl = mcpp::cxx_stdlib();   // "libstdc++" | "libc++" | "msvc-stl" | ""
 ```
 
 `compiler()` 回答不了这个问题。clang 在一台机器上链 libc++、在另一台上链
-libstdc++,两种情况都答 `clang`,而两个实现接受的东西不同——在头文件里析构一个
-指向不完整类型的 `unique_ptr`,libstdc++ 通过而 libc++ 不通过。需要按名字拒绝
-这种配置的构建程序不能去问 `compiler()`,因为那个答案会连同能工作的配置一起拒掉:
+libstdc++，两种情况都答 `clang`，而两个实现接受的东西不同——在头文件里析构一个
+指向不完整类型的 `unique_ptr`，libstdc++ 通过而 libc++ 不通过。需要按名字拒绝
+这种配置的构建程序不能去问 `compiler()`，因为那个答案会连同能工作的配置一起拒掉：
 
 ```cpp
 if (std::string_view(mcpp::cxx_stdlib()) == "libc++") {
@@ -301,50 +301,50 @@ if (std::string_view(mcpp::cxx_stdlib()) == "libc++") {
 }
 ```
 
-名字里带 `cxx` 是有意的:`MCPP_TARGET_LIBC` 是 **C** 库。两者是不同的问题,而在
-一个不断提到 glibc 与 musl 的生态里,它们不能共用一个词。
+名字里带 `cxx` 是有意的：`MCPP_TARGET_LIBC` 是 **C** 库。两者是不同的问题，而在
+一个不断提到 glibc 与 musl 的生态里，它们不能共用一个词。
 
-### 找到 `[xlings.workspace]` 的载荷:`xpkg_dir`(2026.8.19+)
+### 找到 `[xlings.workspace]` 的载荷：`xpkg_dir`（2026.8.19+）
 
-`dep_dir` 回答的是 **mcpp** 依赖。xlings 包是另一个命名空间、另一套 store 布局,
-`xpkg_dir` 是它的接口:
+`dep_dir` 回答的是 **mcpp** 依赖。xlings 包是另一个命名空间、另一套 store 布局，
+`xpkg_dir` 是它的接口：
 
 ```cpp
 // mcpp.toml
 //   [xlings]
 //   deps = ["xim:picolibc-riscv@1.8.12"]
 
-const char* sysroot = mcpp::xpkg_dir("xim", "picolibc-riscv");   // 精确
-const char* same    = mcpp::xpkg_dir("picolibc-riscv");          // 裸名
+const char* sysroot = mcpp::xpkg_dir("xim", "picolibc-riscv");   // exact
+const char* same    = mcpp::xpkg_dir("picolibc-riscv");          // bare name
 ```
 
-带命名空间的形式只对该命名空间下声明的包作答,应当优先使用;裸名形式是常见的单条
-声明的便利写法,两个命名空间都声明同一个名字时,它回答**先声明**的那个。两者在包
-未声明或未安装时都返回 `""` —— 缺失是否致命只有调用方知道,所以由它自己说。
+带命名空间的形式只对该命名空间下声明的包作答，应当优先使用；裸名形式是常见的单条
+声明的便利写法，两个命名空间都声明同一个名字时，它回答**先声明**的那个。两者在包
+未声明或未安装时都返回 `""` —— 缺失是否致命只有调用方知道，所以由它自己说。
 
-做成接口而不是给一条路径约定,是因为另一种做法是让构建程序把
-`<home>/data/xpkgs/<ns>-x-<name>/<version>` 写进代码,而那是 mcpp 可以随时改的
+做成接口而不是给一条路径约定，是因为另一种做法是让构建程序把
+`<home>/data/xpkgs/<ns>-x-<name>/<version>` 写进代码，而那是 mcpp 可以随时改的
 store 内部结构 —— 与 `dep_dir` 存在的理由相同。
 
-**带版本固定**的引用只解析到那个版本,否则什么都不返回。请求 `1.8.12` 却静默拿
-到 `1.9.0`,是那种要到产物里才被发现的答案。
+**带版本固定**的引用只解析到那个版本，否则什么都不返回。请求 `1.8.12` 却静默拿
+到 `1.9.0`，是那种要到产物里才被发现的答案。
 
-**带约束**的引用(`>=8.5.0`、`^1.2`)解析到满足它的**最高已安装版本**
-(2026.9.6.6+)。在那之前整个版本位是拿去与目录名比对的,于是一条范围装上了载荷,然后
+**带约束**的引用（`>=8.5.0`、`^1.2`）解析到满足它的**最高已安装版本**
+(2026.9.6.6+)。在那之前整个版本位是拿去与目录名比对的，于是一条范围装上了载荷，然后
 回答「没装」—— 这正是规则包无法声明下界、而每个工程都要把规则的包列表重写一遍的原因。
 
-**依赖声明的包同样被作答**(2026.9.6.6+),而且答的是这次构建**真正装上**的版本,不是
-本地 manifest 写下的那个。一个包只有一个版本:工程与规则都命名它时,离产物更近的声明赢,
+**依赖声明的包同样被作答**(2026.9.6.6+)，而且答的是这次构建**真正装上**的版本，不是
+本地 manifest 写下的那个。一个包只有一个版本：工程与规则都命名它时，离产物更近的声明赢，
 而两侧被告知同一个答案。见 [23 — The Project Environment](23-the-project-environment.md) 的「一个包一个版本」。
 
 **`[feature-xlings.<f>]` 在 `<f>` 生效时同样被作答**(2026.9.6.2+)。这张表从诞生
-起就参与供给 —— 在那里写下一个包,它就会被下载并安装 —— 但构建程序的环境只由
-`[xlings.workspace]` 填充,于是载荷明明在盘上,`xpkg_dir` 却返回 `""`。这时构建程序
-唯一说得出口的话是「请声明这个包」,而它指的那条声明作者早已写下。
+起就参与供给 —— 在那里写下一个包，它就会被下载并安装 —— 但构建程序的环境只由
+`[xlings.workspace]` 填充，于是载荷明明在盘上，`xpkg_dir` 却返回 `""`。这时构建程序
+唯一说得出口的话是「请声明这个包」，而它指的那条声明作者早已写下。
 
-### 依赖产出的 host 工具(2026.8.5.1+)
+### 依赖产出的 host 工具（2026.8.5.1+）
 
-在 `mcpp.toml` 里声明需求,然后调用它:
+在 `mcpp.toml` 里声明需求，然后调用它：
 
 ```toml
 [dependencies]
@@ -356,54 +356,54 @@ protobuf = { version = "35.1", tools = ["protoc"] }
 import mcpp;
 int main() {
     const char* protoc = mcpp::dep_bin("protobuf", "protoc");
-    // … 调用它,然后声明它产出了什么 …
+    // … invoke it, then declare what it produced …
 }
 ```
 
-mcpp 会**为构建机器**构建那个 `kind = "bin"` target(即使在 `--target` 下),
-全局缓存,并把路径交回。这个请求写在 `mcpp.toml` 而不是这里,理由和依赖本身
-一样:向依赖图索取一个额外产物是**图级别**的请求,而图必须保持可静态分析。
-完整契约(含 `[tools.overrides]` 与 `reexport = true` —— 库据此把整条工具链交给
-调用方,因此只需写**一条**依赖而不是四条)见本章*依赖产出的 host 工具*。
+mcpp 会**为构建机器**构建那个 `kind = "bin"` target（即使在 `--target` 下），
+全局缓存，并把路径交回。这个请求写在 `mcpp.toml` 而不是这里，理由和依赖本身
+一样：向依赖图索取一个额外产物是**图级别**的请求，而图必须保持可静态分析。
+完整契约（含 `[tools.overrides]` 与 `reexport = true` —— 库据此把整条工具链交给
+调用方，因此只需写**一条**依赖而不是四条）见本章*依赖产出的 host 工具*。
 
-### 用通配符声明输入:`rerun_if_changed_glob`(2026.8.6.2+)
+### 用通配符声明输入：`rerun_if_changed_glob`（2026.8.6.2+）
 
-重跑键由**声明过的**输入构成。声明具体文件是可行的;而 glob 一个目录不可行 ——
-新增一个 `.proto` 不改变任何已声明文件的哈希,于是程序不重跑,新文件静默地永远
+重跑键由**声明过的**输入构成。声明具体文件是可行的；而 glob 一个目录不可行 ——
+新增一个 `.proto` 不改变任何已声明文件的哈希，于是程序不重跑，新文件静默地永远
 不被生成。`rerun_if_changed_glob` 就是程序用来说「我的输出取决于这里有哪些文件」
-的方式:
+的方式：
 
 ```cpp
 import mcpp;
 int main() {
     mcpp::rerun_if_changed_glob("proto/**/*.proto");
-    // … 扫描目录,为每个文件声明一条 action …
+    // … scan the directory, declare one action per file …
 }
 ```
 
-模式相对 manifest 目录,`*` / `**` 的文法与 `sources = [...]` 完全一致。它的指纹
-是**排序后的匹配路径集合**,不含其他任何东西:
+模式相对 manifest 目录，`*` / `**` 的文法与 `sources = [...]` 完全一致。它的指纹
+是**排序后的匹配路径集合**，不含其他任何东西：
 
-- **不含内容** —— 字节内容重要的文件本来就该用 `rerun_if_changed` 声明,那条
-  条目已经在哈希它;
+- **不含内容** —— 字节内容重要的文件本来就该用 `rerun_if_changed` 声明，那条
+  条目已经在哈希它；
 - **不含 mtime 与 size** —— mtime 在 `git checkout`、容器构建、`rsync` 下都不
-  稳定,而 size 是比上面那个哈希更弱的信号。
+  稳定，而 size 是比上面那个哈希更弱的信号。
 
-构建输出目录与 `.git` 永远不进入集合,因此再宽的模式也不会让程序对着自己的产物
+构建输出目录与 `.git` 永远不进入集合，因此再宽的模式也不会让程序对着自己的产物
 无限重跑。
 
 **声明过的输入在快路径上同样被比较**(2026.9.5.4+)。当所有源文件都不比
-`build.ninja` 新时,工程走快路径,跳过读取构建程序缓存的那个阶段;在 2026.9.5.4
-之前,快路径只问 glob 的路径集合。数据文件既不在 `src/` 下也没有 C++ 扩展名,mtime
-扫描同样看不见它:改了它,上一次的产出原样留着,构建打印 `Finished dev in 0.00s`。
+`build.ninja` 新时，工程走快路径，跳过读取构建程序缓存的那个阶段；在 2026.9.5.4
+之前，快路径只问 glob 的路径集合。数据文件既不在 `src/` 下也没有 C++ 扩展名，mtime
+扫描同样看不见它：改了它，上一次的产出原样留着，构建打印 `Finished dev in 0.00s`。
 现在快路径按缓存记录的方式比较三类输入 —— glob 的路径集合、声明文件的内容哈希、
 声明环境变量的值 —— 因此 `rerun_if_changed` 在两条路径上含义相同。
 
-### 声明产出而非执行动作:`mcpp::action`(2026.8.5.1+)
+### 声明产出而非执行动作：`mcpp::action`（2026.8.5.1+）
 
-在**这里**直接把源码写出来是省事的路,超过一定规模就是错的:它每次 prepare 跑
-一遍、全量、串行,失败还只报「build.mcpp exited 1」。**声明**这份工作,它就成为
-构建图里的一条边 —— 增量、并行,失败能归因到具体那条边。
+在**这里**直接把源码写出来是省事的路，超过一定规模就是错的：它每次 prepare 跑
+一遍、全量、串行，失败还只报「build.mcpp exited 1」。**声明**这份工作，它就成为
+构建图里的一条边 —— 增量、并行，失败能归因到具体那条边。
 
 ```cpp
 import mcpp;
@@ -420,107 +420,107 @@ int main() {
 }
 ```
 
-四种 role,一个原语 —— `role` 只决定这条边的输出接到哪:
+四种 role，一个原语 —— `role` 只决定这条边的输出接到哪：
 
 | `role` | 输出 | 顺序 | 典型 |
 |---|---|---|---|
-| `source` | 可编译的进编译集,其余只产出、不编译 | **声明它的那个包的每条编译边都等它** | protoc、转译器、协议/IDL 生成器 |
-| `check` | 一个 stamp 文件,由 mcpp 写入 | 与编译并行;`blocking = true` 让该包的编译边等它 | clang-tidy、格式/ABI 检查 |
+| `source` | 可编译的进编译集，其余只产出、不编译 | **声明它的那个包的每条编译边都等它** | protoc、转译器、协议/IDL 生成器 |
+| `check` | 一个 stamp 文件，由 mcpp 写入 | 与编译并行；`blocking = true` 让该包的编译边等它 | clang-tidy、格式/ABI 检查 |
 | `object` | 进**链接**集 | 链接边消费它们 | 资源编译器、`objcopy` 嵌 blob、生成的 `.def`、预编译 `.o` |
-| `artifact` | 一个新文件 | 它的**输入**是链接产物,所以在链接之后跑 | 签名、打包、size budget |
+| `artifact` | 一个新文件 | 它的**输入**是链接产物，所以在链接之后跑 | 签名、打包、size budget |
 
 `artifact` 也是唯一允许写 `${mcpp.stage_dir}` 的 role —— 见下文
 [产出可分发物](#产出可分发物pack_format-与-stage_dir20269111)。另外三个跑在链接之前
-或与链接并行,没有任何已暂存的东西可读,所以 mcpp 会拒绝这个占位符,而不是把它展开成
+或与链接并行，没有任何已暂存的东西可读，所以 mcpp 会拒绝这个占位符，而不是把它展开成
 一个恰好存在的路径。
 
 全程不涉及任何 phase 机制。`object` 与 `artifact` 由 ninja 自己的文件依赖定序 ——
 这也是为什么 `artifact` 不会像朴素的「post 构建钩子」那样把自己重复施加一遍。
-`source` 与 blocking 的 `check` 则由一条 order-only 边定序:从声明它的那个包的
-编译边,指向该包的 action 产物。
+`source` 与 blocking 的 `check` 则由一条 order-only 边定序：从声明它的那个包的
+编译边，指向该包的 action 产物。
 
-> **`source` 为什么需要这条边(mcpp 2026.8.30.2+)。** 生成的 `.cpp` 会成为编译它
-> 那条边的输入,所以顺序是白得的。生成的**头文件**永远不会:它是通过 `-I` 找到的,
-> 而能记录它的 depfile 要等到某次编译成功之后才存在。在此之前,一个产物全是头文件的
+> **`source` 为什么需要这条边（mcpp 2026.8.30.2+）。** 生成的 `.cpp` 会成为编译它
+> 那条边的输入，所以顺序是白得的。生成的**头文件**永远不会：它是通过 `-I` 找到的，
+> 而能记录它的 depfile 要等到某次编译成功之后才存在。在此之前，一个产物全是头文件的
 > action 在 `build.ninja` 里有节点却无人可达 —— 不在 `default`、不在 goal 集、没有
-> 任何边消费它 —— 于是它从不执行,而编译器读到的是 mcpp 为已声明产物写下的那个空占位
-> 文件。这条边**按包**划分,因为 `include_dir` 只染色声明它的那个包自己的 TU。
+> 任何边消费它 —— 于是它从不执行，而编译器读到的是 mcpp 为已声明产物写下的那个空占位
+> 文件。这条边**按包**划分，因为 `include_dir` 只染色声明它的那个包自己的 TU。
 
 **命令自己发现依赖的 action 要声明 depfile**(mcpp 2026.9.7.1+)。`input()` 在
-`build.mcpp` 运行时就把边的输入定死了,而那时命令还没执行,所以一个靠解析源码才知道自己
+`build.mcpp` 运行时就把边的输入定死了，而那时命令还没执行，所以一个靠解析源码才知道自己
 `#include` 图的编译器没有任何通道把结果报回来 —— 改动一个命令只是**读**过的文件不会触发
-任何重建,`mcpp build` 会在一个陈旧产物上保持绿色。
+任何重建，`mcpp build` 会在一个陈旧产物上保持绿色。
 
 ```cpp
-a.depfile = dep.c_str();        // 命令会写出的路径
+a.depfile = dep.c_str();        // a path the command writes
 a.arg("--depfile").arg(dep.c_str());
 ```
 
-mcpp 为那条边写出 `depfile =` 与 `deps = gcc`,ninja 读取该文件并把它列出的文件并入这条边
-的依赖。与此相关的每个设备编译器都已经能输出它:`glslangValidator --depfile`、
+mcpp 为那条边写出 `depfile =` 与 `deps = gcc`，ninja 读取该文件并把它列出的文件并入这条边
+的依赖。与此相关的每个设备编译器都已经能输出它：`glslangValidator --depfile`、
 `glslc -MD -MF`、`slangc -depfile`、`nvcc`/`clang` 的 `-MD -MF`。
 
-> **不要同时把 depfile 声明为 `output()`。** `deps = gcc` 会让 ninja 读完即删,所以一条
+> **不要同时把 depfile 声明为 `output()`。** `deps = gcc` 会让 ninja 读完即删，所以一条
 > 承诺了该输出的边会永远是脏的。
 
-**check 的命令不必自己写 stamp**(mcpp 2026.8.29.1+)。判定是退出码,stamp 是**构建图**
-需要的记账;命令成功时由 mcpp 创建它。在此之前每个 check 都需要一个包装脚本去 touch
-那个文件 —— 而 command 是 argv、不假设有 shell,所以那个包装器**根本没法可移植地写出来**。
-已经自己写 stamp 的命令不受影响:已存在的文件不会被动。
+**check 的命令不必自己写 stamp**(mcpp 2026.8.29.1+)。判定是退出码，stamp 是**构建图**
+需要的记账；命令成功时由 mcpp 创建它。在此之前每个 check 都需要一个包装脚本去 touch
+那个文件 —— 而 command 是 argv、不假设有 shell，所以那个包装器**根本没法可移植地写出来**。
+已经自己写 stamp 的命令不受影响：已存在的文件不会被动。
 
-> stamp 缺失**不会**让构建失败。ninja 只是留着那个声明的输出不存在,并在之后**每次构建
-> 都重跑**那条边 —— 看起来像一个通过了的检查,实际上它从未被满足。
+> stamp 缺失**不会**让构建失败。ninja 只是留着那个声明的输出不存在，并在之后**每次构建
+> 都重跑**那条边 —— 看起来像一个通过了的检查，实际上它从未被满足。
 
-`object`(2026.8.7.1+)可选 `.target("name")`,可重复。它之所以需要名字:与
-`artifact` 不同,它跑在链接**之前**,没有 `${mcpp.target_file:…}` 可以反推。
-**每一个**匹配不到链接单元的名字都是错误 —— 包括写在一个匹配得上的名字旁边的那个,
+`object`（2026.8.7.1+）可选 `.target("name")`，可重复。它之所以需要名字：与
+`artifact` 不同，它跑在链接**之前**，没有 `${mcpp.target_file:…}` 可以反推。
+**每一个**匹配不到链接单元的名字都是错误 —— 包括写在一个匹配得上的名字旁边的那个，
 那正是拼错真实的样子。
 
-**优先省略它。** 不写 target 时,产物接到本次构建里该包产出的每个镜像 —— 可执行、
-动态库,**以及测试二进制**。测试二进制在这个集合里,是因为它链接的是同一份库代码:
-把它排除掉,`mcpp build` 会通过而 `mcpp test` 在这个 action 本来要提供的那个符号上
+**优先省略它。** 不写 target 时，产物接到本次构建里该包产出的每个镜像 —— 可执行、
+动态库，**以及测试二进制**。测试二进制在这个集合里，是因为它链接的是同一份库代码：
+把它排除掉，`mcpp build` 会通过而 `mcpp test` 在这个 action 本来要提供的那个符号上
 报 `undefined symbol`。改成显式点名也不行 —— 测试链接单元是从 `tests/*.cpp`
-**发现**出来的,名字不在 `mcpp.toml` 里,而写了它的 `build.mcpp` 在普通
-`mcpp build` 下会直接构建失败,因为那条链接单元根本不存在。
+**发现**出来的，名字不在 `mcpp.toml` 里，而写了它的 `build.mcpp` 在普通
+`mcpp build` 下会直接构建失败，因为那条链接单元根本不存在。
 
-如果本次构建里没有任何东西能接收这些产物(纯静态库包),mcpp 会报一条 degradation:
-这条边只能经由链接被达成,没有链接就意味着命令一次都不会跑,而构建什么都不说。
+如果本次构建里没有任何东西能接收这些产物（纯静态库包），mcpp 会报一条 degradation:
+这条边只能经由链接被达成，没有链接就意味着命令一次都不会跑，而构建什么都不说。
 
-> 把预编译对象写进 `[build].ldflags` 同样能到达链接器,但**不要**用它承载构建产物:
-> ldflags 是链接命令里的一串字符、不是图里的文件,没有任何东西跟踪它,改了它得到的是
-> `ninja: no work to do`。Windows 资源请用 [`[resources]`](04-mcpp-toml.md);
+> 把预编译对象写进 `[build].ldflags` 同样能到达链接器，但**不要**用它承载构建产物：
+> ldflags 是链接命令里的一串字符、不是图里的文件，没有任何东西跟踪它，改了它得到的是
+> `ninja: no work to do`。Windows 资源请用 [`[resources]`](04-mcpp-toml.md)；
 > `object` 是其余一切的出口。
 
-**必须写出输出文件名。** mcpp 在 prepare 期就定死源码集、fingerprint 与模块图,
-所以名字未知的产物无法构建。内容可以晚到,名字不行。畸形 action 是**硬错误**,
+**必须写出输出文件名。** mcpp 在 prepare 期就定死源码集、fingerprint 与模块图，
+所以名字未知的产物无法构建。内容可以晚到，名字不行。畸形 action 是**硬错误**，
 绝不静默跳过。
 
 **列表没有声明上的长度上限**(2026.9.13.1+)。`inputs`、`outputs` 与 `command`
-随声明增长;一棵两百个文件的生成树就是两百次 `output` 调用。2026.9.13.1 之前,
-内置模块把每个列表放在定长数组里(`inputs` 与 `outputs` 各 8192 字节的序列化
-JSON),放不下的声明会被拒绝,于是一个消费者的 checkout 深度决定了四十个文件的
-列表能否被接受。仍然有上限的是**运行期的命令**,由操作系统对进程参数的限制决定
-(Linux 上每个参数 128 KiB,Windows 的 `CreateProcess` 是 32767 个字符);那是
-工具自己命令行的上限,一个要接收几百个文件的工具用它自己的 response file 或目录
-参数来接收。引擎自己针对它的守卫量的是命令而不是边:action 的输入与输出是图上的
-边,从不进入 argv。
+随声明增长；一棵两百个文件的生成树就是两百次 `output` 调用。2026.9.13.1 之前，
+内置模块把每个列表放在定长数组里（`inputs` 与 `outputs` 各 8192 字节的序列化
+JSON），放不下的声明会被拒绝，于是一个消费者的 checkout 深度决定了四十个文件的
+列表能否被接受。仍然有上限的是**运行期的命令**，由操作系统对进程参数的限制决定
+（Linux 上每个参数 128 KiB,Windows 的 `CreateProcess` 是 32767 个字符）；那是
+工具自己命令行的上限，一个要接收几百个文件的工具用它自己的 response file 或目录
+参数来接收。引擎自己针对它的守卫量的是命令而不是边：action 的输入与输出是图上的
+边，从不进入 argv。
 
-生成**模块接口**时,把它的接口也声明出来:
+生成**模块接口**时，把它的接口也声明出来：
 
 ```cpp
 a.output(gen.c_str()).provides("my.generated").imports("std").submit();
 ```
 
-mcpp 会播下一个带着该声明的占位文件,使 prepare 期的扫描与生成器将要产出的
-内容一致 —— 与 `[modules].scan_overrides` 同一条「声明 + 验证」的取舍,build 期由
+mcpp 会播下一个带着该声明的占位文件，使 prepare 期的扫描与生成器将要产出的
+内容一致 —— 与 `[modules].scan_overrides` 同一条「声明 + 验证」的取舍，build 期由
 编译器自己的 P1689 输出复核。
 
-### 部署程序生成的东西:`deploy`(2026.9.12.3+,protocol 11)
+### 部署程序生成的东西：`deploy`（2026.9.12.3+,protocol 11）
 
-`[runtime] deploy`(docs/04 §2.11)把包里已经存在的一个文件,放到相对可执行
-文件的某个路径。它点不了一个 action 后一步才产出的文件,因为它的 `from` 按包根
-解析,并拒绝绝对路径——而一个 action 声明的输出通常是 `MCPP_OUT_DIR` 下的
-绝对路径。`mcpp::deploy` 就是同一次放置,从构建程序里发出:
+`[runtime] deploy`（docs/04 §2.11）把包里已经存在的一个文件，放到相对可执行
+文件的某个路径。它点不了一个 action 后一步才产出的文件，因为它的 `from` 按包根
+解析，并拒绝绝对路径——而一个 action 声明的输出通常是 `MCPP_OUT_DIR` 下的
+绝对路径。`mcpp::deploy` 就是同一次放置，从构建程序里发出：
 
 ```cpp
 import mcpp;
@@ -529,7 +529,7 @@ int main() {
     const std::string out = std::string(mcpp::out_dir()) + "/final/resources.bin";
     mcpp::action a;
     a.id   = "gen-resources";
-    a.role = "source";                 // 产出但不编译 —— 见上文的 `action`
+    a.role = "source";                 // produced, not compiled — see `action` above
     a.arg("resource-compiler").arg("assets/").arg(out.c_str())
      .output(out.c_str())
      .submit();
@@ -538,38 +538,38 @@ int main() {
 }
 ```
 
-- **`from` 是一个文件,不是一个目录。** prepare 期无法得知一棵生成目录里都有
-  哪些成员,因此不能成为图节点;一棵 N 个文件的生成树对应 N 个输出与 N 次
+- **`from` 是一个文件，不是一个目录。** prepare 期无法得知一棵生成目录里都有
+  哪些成员，因此不能成为图节点；一棵 N 个文件的生成树对应 N 个输出与 N 次
   `deploy` 调用。
 - **`from` 可以是绝对路径或按包根解析的相对路径。** 传入一个 action 自己声明
-  的输出,天然让拷贝边依赖上那个 action——边的输入就是 action 的输出,
-  ninja 据此排序,不必再写别的东西去串联两者。
-- **`to` 遵守与 manifest 键相同的规则**:`/` 分隔、不得含 `..` 分量,
-  `"."` 表示可执行文件自己所在的目录。违反规则的路径会被拒绝,拒绝信息指出
+  的输出，天然让拷贝边依赖上那个 action——边的输入就是 action 的输出，
+  ninja 据此排序，不必再写别的东西去串联两者。
+- **`to` 遵守与 manifest 键相同的规则**：`/` 分隔、不得含 `..` 分量，
+  `"."` 表示可执行文件自己所在的目录。违反规则的路径会被拒绝，拒绝信息指出
   该指令与声明它的包。
 - **在缓存命中时被重放。** `deploy` 指令与 `runner`、`warning` 一样进入构建
-  缓存;即使手工删掉 `bin/` 之后,一次缓存命中的重跑也会像真正跑过一样把
+  缓存；即使手工删掉 `bin/` 之后，一次缓存命中的重跑也会像真正跑过一样把
   文件恢复回来。
-- **由 `mcpp pack` 在每种格式里,按相同的相对路径暂存到打包后的可执行文件旁边**:
+- **由 `mcpp pack` 在每种格式里，按相同的相对路径暂存到打包后的可执行文件旁边**：
 
   | 格式 | `to = "myapp.resources"` 落在哪里 |
   |---|---|
   | tar、dir、AppImage、MSI | 可执行文件旁边的 `bin/myapp.resources/` |
-  | `.app`(macOS、iOS) | bundle 的可执行文件目录 |
+  | `.app`（macOS、iOS） | bundle 的可执行文件目录 |
   | `.apk` | `assets/myapp.resources/` |
-  | web | 静态目录里同一个相对路径,与 `<name>.js` 放在一起。想把文件放进 `.data` 预加载的项目改用链接标志 `--preload-file <dir>@/<to>`,那是一条普通的链接标志 |
+  | web | 静态目录里同一个相对路径，与 `<name>.js` 放在一起。想把文件放进 `.data` 预加载的项目改用链接标志 `--preload-file <dir>@/<to>`，那是一条普通的链接标志 |
 
-### 产出可分发物:`pack_format` 与 `stage_dir`(2026.9.11.1+)
+### 产出可分发物：`pack_format` 与 `stage_dir`（2026.9.11.1+）
 
-一个 `.msi`、一个 `.deb`、一个 AppImage、一个签过名的 `.app`,都不是那四个 role 的
-惯常活计,而它们全都是 `artifact`:每一个都消费**链接产物**,产出用户去安装的东西。
-引擎为它们加的是一套机制,而不是任何一种格式。
+一个 `.msi`、一个 `.deb`、一个 AppImage、一个签过名的 `.app`，都不是那四个 role 的
+惯常活计，而它们全都是 `artifact`：每一个都消费**链接产物**，产出用户去安装的东西。
+引擎为它们加的是一套机制，而不是任何一种格式。
 
-`mcpp pack --format <name>` 把 `<name>` 交给解析后的图去解决,方式与 `--target`
+`mcpp pack --format <name>` 把 `<name>` 交给解析后的图去解决，方式与 `--target`
 够到一个引擎不必逐个认识的三元组相同。`tar` 与 `dir` 仍然是 `mcpp pack` 自己拥有的
-归档形状;此外的一切都来自某个包。
+归档形状；此外的一切都来自某个包。
 
-一个提供方有两半,而这两半不许被并成一半:
+一个提供方有两半，而这两半不许被并成一半：
 
 ```cpp
 import mcpp;
@@ -577,10 +577,10 @@ import mcpp;
 #include <string_view>
 
 int main() {
-    // 第一半,无条件。
+    // Half one, unconditional.
     mcpp::provides_pack_format("appimage");
 
-    // 第二半,有条件。
+    // Half two, conditional.
     if (std::string_view(mcpp::pack_format()) != "appimage") return 0;
 
     const std::string out = std::string(mcpp::out_dir()) + "/app.AppImage";
@@ -595,134 +595,134 @@ int main() {
 }
 ```
 
-**无条件声明,有条件提交。** 声明是让引擎能回答一个发起请求的那次构建自己回答不了的
-问题:`--format bogus` 要点名**当下确实可用**的那些格式,`--help` 要说「解析后的图
+**无条件声明，有条件提交。** 声明是让引擎能回答一个发起请求的那次构建自己回答不了的
+问题：`--format bogus` 要点名**当下确实可用**的那些格式，`--help` 要说「解析后的图
 提供的任何格式」。两者读的都是一次「什么格式都没要」的 pass 收集到的集合。一个只在被
-问到时才声明的成员,对它的作者仍然照常工作 —— 作者永远传的是自己那个格式 —— 而对其他
-所有人,这个集合变成不可知的。对一个谁都没为之提交的格式,mcpp 会拒绝,而不是报告一次
+问到时才声明的成员，对它的作者仍然照常工作 —— 作者永远传的是自己那个格式 —— 而对其他
+所有人，这个集合变成不可知的。对一个谁都没为之提交的格式，mcpp 会拒绝，而不是报告一次
 「什么包都没产出」的成功打包。
 
 **`mcpp pack --format <name>` 会 prepare 两次。** 一条 `artifact` action 是一条
-ninja 边,而那棵暂存树是 mcpp 在链接**之后**产出的,所以这棵树不可能成为构建出它自己
-那一次 pass 的输入。第一次 pass 收集声明,并在任何东西被编译之前拒绝未知的格式;随后
-才是构建与暂存;第二次 pass 设上 `pack_format` 与 `pack_stage_dir`,并构建提供方提交
+ninja 边，而那棵暂存树是 mcpp 在链接**之后**产出的，所以这棵树不可能成为构建出它自己
+那一次 pass 的输入。第一次 pass 收集声明，并在任何东西被编译之前拒绝未知的格式；随后
+才是构建与暂存；第二次 pass 设上 `pack_format` 与 `pack_stage_dir`，并构建提供方提交
 的那条边。第二次 pass 里没有任何值是重新推导出来的 —— 三元组与暂存路径都是第一次
 pass 和那次暂存已经回答过的。
 
-**暂存树是一个 bundle,不是一个根文件系统。** 它就是 `--mode vendored` 的含义:
-`bin/`、`lib/`,可重定位、根在哪儿都行,并且已经过了 strip 策略、调试信息拆分与
+**暂存树是一个 bundle，不是一个根文件系统。** 它就是 `--mode vendored` 的含义：
+`bin/`、`lib/`，可重定位、根在哪儿都行，并且已经过了 strip 策略、调试信息拆分与
 `include`/`exclude`。一个 AppImage、一个 `.app`、一个 `.msi` 要的就是它现在这个样子。
-而要一棵 FHS 树的格式(`.deb`、`.rpm`)自己负责重排布局,因为一个文件该落在哪个目录是
-那个格式的知识,不是引擎的。
+而要一棵 FHS 树的格式（`.deb`、`.rpm`）自己负责重排布局，因为一个文件该落在哪个目录是
+那个格式的知识，不是引擎的。
 
-`mcpp pack --format dir` 把同一棵树写到一个路径上就停下,这是人去查看一个成员将会拿到
+`mcpp pack --format dir` 把同一棵树写到一个路径上就停下，这是人去查看一个成员将会拿到
 什么的方式。
 
 **`mcpp pack` 报告的是这次请求**引入**的那些 artifact action。** 一条无论有没有人
-要格式都在场的 action —— 一个签名 stamp、一次 size budget —— 不是可分发物,点名它会
-是一个看起来像对的错答案。这个判据里没有任何一项是成员的性质:一个只打包一个具名程序、
-从不读暂存树的格式,与一个消费整个闭包的格式被同等识别。对一个谁都没为之提交的格式,
+要格式都在场的 action —— 一个签名 stamp、一次 size budget —— 不是可分发物，点名它会
+是一个看起来像对的错答案。这个判据里没有任何一项是成员的性质：一个只打包一个具名程序、
+从不读暂存树的格式，与一个消费整个闭包的格式被同等识别。对一个谁都没为之提交的格式，
 会被点名拒绝。
 
 **写了 `${mcpp.stage_dir}` 的 action 会自动获得一条对这棵树的 manifest 的依赖。**
-mcpp 会写出 `<暂存树>.stage-manifest` —— 一个兄弟文件,永不是成员,所以它不会跑进任何
-人的安装包里 —— 逐条列出每个已暂存文件的大小与相对路径。这条依赖由引擎添加,因为「用
-了」本身就意味着「依赖」:没有它,这条边只在链接产物变化时才变脏,而一个闭包多出了某个
-依赖的共享库、同时程序自己的字节并没有变的情况,会把上一次的可分发物原地留下,并报告为
+mcpp 会写出 `<暂存树>.stage-manifest` —— 一个兄弟文件，永不是成员，所以它不会跑进任何
+人的安装包里 —— 逐条列出每个已暂存文件的大小与相对路径。这条依赖由引擎添加，因为「用
+了」本身就意味着「依赖」：没有它，这条边只在链接产物变化时才变脏，而一个闭包多出了某个
+依赖的共享库、同时程序自己的字节并没有变的情况，会把上一次的可分发物原地留下，并报告为
 已是最新。
 
 **这份 manifest 的第一行是 `closure = walked` 或 `closure = not-walked`。**
-`mcpp pack` 会先暂存程序本身与它声明过的运行期文件,再解析该产物的依赖闭包 —— 所以这棵
-树可以在闭包不完整的情况下存在:闭包里有一个名字解析不到树能携带的文件(2026.9.14.2+),
+`mcpp pack` 会先暂存程序本身与它声明过的运行期文件，再解析该产物的依赖闭包 —— 所以这棵
+树可以在闭包不完整的情况下存在：闭包里有一个名字解析不到树能携带的文件（2026.9.14.2+）,
 或者在 Windows 宿主上打包一个既非 PE 也非 Mach-O 的产物。`--format tar` 与
-`--format dir` 在这种情况下让命令失败,因为归档本身就是闭包;一个被分发出去的格式无论如何
-都会拿到这棵树,manifest 上多出第二行 `reason = <原因>`。头部之后的 `needs` 行给出每个
-被需要的名字以及满足它的东西([50 —— 机器输出](50-machine-output.md)),自行放置库的
-提供方读这些行,而不是从 `lib/` 里推断闭包。
+`--format dir` 在这种情况下让命令失败，因为归档本身就是闭包；一个被分发出去的格式无论如何
+都会拿到这棵树，manifest 上多出第二行 `reason = <原因>`。头部之后的 `needs` 行给出每个
+被需要的名字以及满足它的东西（[50 —— 机器输出](50-machine-output.md)），自行放置库的
+提供方读这些行，而不是从 `lib/` 里推断闭包。
 
-**自己暂存库的成员跟随剥离决定(2026.9.16.1+)。** `mcpp pack` 剥离程序、图构建出的每个
-共享库以及工具链运行时的暂存副本,`--no-strip` 与 `--debug-symbols` 管辖其中每一个。
-另行放置库的提供方(Android 归档里的原生库)在提交的那次 pass 中读 `mcpp::pack_strip()`
-(`"1"` 或 `"0"`)与 `mcpp::pack_debug_symbols_dir()`,于是一个开关管住包里的每个文件。
+**自己暂存库的成员跟随剥离决定（2026.9.16.1+）。** `mcpp pack` 剥离程序、图构建出的每个
+共享库以及工具链运行时的暂存副本，`--no-strip` 与 `--debug-symbols` 管辖其中每一个。
+另行放置库的提供方（Android 归档里的原生库）在提交的那次 pass 中读 `mcpp::pack_strip()`
+（`"1"` 或 `"0"`）与 `mcpp::pack_debug_symbols_dir()`，于是一个开关管住包里的每个文件。
 
-命令是 **argv 而不是 shell 字符串**(不假设存在 shell —— Windows 没有能依赖的那个),
-插值只有封闭的一组:
+命令是 **argv 而不是 shell 字符串**（不假设存在 shell —— Windows 没有能依赖的那个），
+插值只有封闭的一组：
 
 | 变量 | 含义 |
 |---|---|
 | `${mcpp.out_dir}` | 构建输出目录 |
 | `${mcpp.bin_dir}` | 产出的二进制所在目录 |
-| `${mcpp.compile_db}` | `compile_commands.json` 的路径(clang-tidy 的 `-p` 要的就是它) |
+| `${mcpp.compile_db}` | `compile_commands.json` 的路径（clang-tidy 的 `-p` 要的就是它） |
 | `${mcpp.target_file:<name>}` | target `<name>` 构建出的文件 |
-| `${mcpp.stage_dir}` *(2026.9.11.1+)* | `mcpp pack` 暂存出的那棵树,绝对路径。仅 `artifact` role 可用,且仅在 `mcpp pack --format <name>` 下可用 |
-| `${mcpp.self}` *(2026.9.13.1+)* | 引擎自己的可执行文件,绝对路径。action 的命令是没有 shell 的 argv,构建程序因此没有可移植的拷贝手段;引擎在构建运行的每台机器上都在,`${mcpp.self} stage --verify content --output <dst> <src>` 拷贝一个文件、创建目标的父目录、只在字节不同时写入。这个参数形状自 2026.9.13.1 起是契约;写下它的构建程序即以该版本为下限 |
+| `${mcpp.stage_dir}` *(2026.9.11.1+)* | `mcpp pack` 暂存出的那棵树，绝对路径。仅 `artifact` role 可用，且仅在 `mcpp pack --format <name>` 下可用 |
+| `${mcpp.self}` *(2026.9.13.1+)* | 引擎自己的可执行文件，绝对路径。action 的命令是没有 shell 的 argv，构建程序因此没有可移植的拷贝手段；引擎在构建运行的每台机器上都在，`${mcpp.self} stage --verify content --output <dst> <src>` 拷贝一个文件、创建目标的父目录、只在字节不同时写入。这个参数形状自 2026.9.13.1 起是契约；写下它的构建程序即以该版本为下限 |
 
-上面的裸 stdout 协议仍是底层基底;`import mcpp;` 是其上的类型化层。
+上面的裸 stdout 协议仍是底层基底；`import mcpp;` 是其上的类型化层。
 
-### 读取解析后的依赖图:`graph_file`(2026.9.16.1+)
+### 读取解析后的依赖图：`graph_file`（2026.9.16.1+）
 
-`mcpp::dep_dir` 按名字回答本包自己声明的依赖。一个要合并每个库贡献的东西(资源、平台源码、
-一段 Info.plist)的框架,还需要应用没有点名的那些库,而且要按「后来的贡献覆盖先前的」的
-顺序。`mcpp::graph_file()` 给出一份描述解析后依赖图的 JSON 文档:
+`mcpp::dep_dir` 按名字回答本包自己声明的依赖。一个要合并每个库贡献的东西（资源、平台源码、
+一段 Info.plist）的框架，还需要应用没有点名的那些库，而且要按「后来的贡献覆盖先前的」的
+顺序。`mcpp::graph_file()` 给出一份描述解析后依赖图的 JSON 文档：
 
 ```jsonc
 {
   "kind": "mcpp.graph",
   "version": 1,
-  "packages": [                        // 依赖排在请求它的包之前
+  "packages": [                        // dependencies before their requesters
     {
       "package": { "canonical": "spike.b@0.2.0", "namespace": "spike",
                    "name": "b", "version": "0.2.0", "source": "path" },
       "root": false,
       "requested_by": [ { "requester": "spike.a@0.1.0", "key": "spike.b",
                           "table": "dependencies" } ],
-      "link": { "form": "static", "reason": "..." },     // 仅库有
+      "link": { "form": "static", "reason": "..." },     // a library only
       "manifest_dir": "/abs/path/to/b",
       "features": [],
       "targets": [ { "name": "b", "kind": "lib" } ],
-      "metadata": { "demo": { "resources": "res" } }      // [package.metadata],原样
+      "metadata": { "demo": { "resources": "res" } }      // [package.metadata], verbatim
     }
   ]
 }
 ```
 
-- **根包的程序拿到它;依赖包的程序读到 `""`。** 根包决定这张图,而它的程序运行时这个决定的
+- **根包的程序拿到它；依赖包的程序读到 `""`。** 根包决定这张图，而它的程序运行时这个决定的
   每个输入都已确定 —— 这正是 `dep_linkage` 只提供给根包的原因。
 - **`[package.metadata.<tool>]` 是包对自身的陈述。** 引擎不解释这张表。其中的路径由读取方
-  相对于该条目的 `manifest_dir` 解析,因为只有读取方知道哪些值是路径。旧引擎忽略这张表,
+  相对于该条目的 `manifest_dir` 解析，因为只有读取方知道哪些值是路径。旧引擎忽略这张表，
   所以已发布的包可以在其使用方升级之前就写上它。
-- **文档内容属于重跑键。** 修改某个依赖的 `[package.metadata]` 会让根包的程序重跑;修改该
+- **文档内容属于重跑键。** 修改某个依赖的 `[package.metadata]` 会让根包的程序重跑；修改该
   依赖的源码不会。
-- 这些条目就是 `resolution.json` 的 `graph` 一节再加四项(`manifest_dir`、`features`、
-  `targets`、`metadata`),出自同一次推导。
+- 这些条目就是 `resolution.json` 的 `graph` 一节再加四项（`manifest_dir`、`features`、
+  `targets`、`metadata`），出自同一次推导。
 
-### `import mcpp;` 才是会演进的那一面(mcpp 2026.8.5.1+)
+### `import mcpp;` 才是会演进的那一面（mcpp 2026.8.5.1+）
 
-和 mcpp 对话有两条路,它们的**兼容性承诺不同**:
+和 mcpp 对话有两条路，它们的**兼容性承诺不同**：
 
 | | `import mcpp;` | 手写 `printf("mcpp:…")` |
 |---|---|---|
-| 兼容性 | 该模块**内置在 mcpp 二进制里**,由运行它的那个 mcpp 现场编译,程序与引擎不可能不一致 | 字符串是冻结的文本,没有任何机制校验它 |
+| 兼容性 | 该模块**内置在 mcpp 二进制里**，由运行它的那个 mcpp 现场编译，程序与引擎不可能不一致 | 字符串是冻结的文本，没有任何机制校验它 |
 | 新指令 | 以新函数的形式到来 | **不会再新增** |
 | 未知指令 | **硬错误** | 警告后忽略 |
 
-用 `import mcpp;` 的程序会自动声明它编译时对应的协议版本(`mcpp:protocol=<N>`,
-在 `main` 之前发出,无需自行编写)。mcpp 用它做两件事:
+用 `import mcpp;` 的程序会自动声明它编译时对应的协议版本（`mcpp:protocol=<N>`，
+在 `main` 之前发出，无需自行编写）。mcpp 用它做两件事：
 
-- 程序声明的协议**高于** mcpp 所理解的 → **拒绝执行**,并给出升级提示。继续跑会
-  静默丢掉构建依赖的指令,而「构建成功了但那个 flag 根本没到」是最难查的一类问题。
-- **未知指令是错误**而不是警告,而且这条错误会把**两种可能的原因都说出来**。
-  它没法只说一种:协议号是由**编译**该程序的那个 mcpp 现场打上的,并不由包本身携带
-  —— 于是一个写给新 mcpp 的包到了老 mcpp 手里,身上戴的是老引擎的号。
+- 程序声明的协议**高于** mcpp 所理解的 → **拒绝执行**，并给出升级提示。继续跑会
+  静默丢掉构建依赖的指令，而「构建成功了但那个 flag 根本没到」是最难查的一类问题。
+- **未知指令是错误**而不是警告，而且这条错误会把**两种可能的原因都说出来**。
+  它没法只说一种：协议号是由**编译**该程序的那个 mcpp 现场打上的，并不由包本身携带
+  —— 于是一个写给新 mcpp 的包到了老 mcpp 手里，身上戴的是老引擎的号。
   **两个号一致因此完全不能说明这个键是不是来自未来。**
 
-`printf` 风格的程序什么都不声明,因此保留历史上的「警告并忽略」行为。这一面
-**冻结在上表的 11 条指令**上——它仍然能用、也会继续能用,但新能力只在类型化 API 里
+`printf` 风格的程序什么都不声明，因此保留历史上的「警告并忽略」行为。这一面
+**冻结在上表的 11 条指令**上——它仍然能用、也会继续能用，但新能力只在类型化 API 里
 落地。**要长期维护的程序请用 `import mcpp;`。**
 
 #### 一个需要更新 mcpp 的包
 
-当已发布的包调用了当前 mcpp 没有的类型化函数时,点名的编译错误之后会跟着:
+当已发布的包调用了当前 mcpp 没有的类型化函数时，点名的编译错误之后会跟着：
 
 ```
        The `mcpp` build module this engine bundles does not have that name.
@@ -730,21 +730,21 @@ mcpp 会写出 `<暂存树>.stage-manifest` —— 一个兄弟文件,永不是
        this is mcpp 2026.8.19.2), or the name is misspelled …
 ```
 
-**包自己处理不了这件事**,而原因值得知道 —— 最直觉的那道防护编译不过:
+**包自己处理不了这件事**，而原因值得知道 —— 最直觉的那道防护编译不过：
 
 ```cpp
-if constexpr (requires { mcpp::runner("qemu"); })   // 名字不存在时是硬错误
+if constexpr (requires { mcpp::runner("qemu"); })   // hard error when absent
     mcpp::runner("qemu");
 ```
 
-`requires` 表达式作用在一个**不存在的限定名**上时是 ill-formed,而**不是求值为
-`false`**。所以语言内没有特性探测这条路:采用了新指令的包只能在自己的 README 里
-用文字写明版本下限,并依赖上面那条诊断。**这类包应当写清楚它需要哪个版本的 mcpp。**
+`requires` 表达式作用在一个**不存在的限定名**上时是 ill-formed，而**不是求值为
+`false`**。所以语言内没有特性探测这条路：采用了新指令的包只能在自己的 README 里
+用文字写明版本下限，并依赖上面那条诊断。**这类包应当写清楚它需要哪个版本的 mcpp。**
 
-### `import std;`(mcpp 2026.8.2.1+)
+### `import std;`（mcpp 2026.8.2.1+）
 
-`build.mcpp` 可以 `import std;`(以及 `import std.compat;`),单用或与
-`import mcpp;` 并用皆可:
+`build.mcpp` 可以 `import std;`（以及 `import std.compat;`），单用或与
+`import mcpp;` 并用皆可：
 
 ```cpp
 // build.mcpp
@@ -757,122 +757,122 @@ int main() {
 }
 ```
 
-mcpp 会把它自己构建时用的**同一份** std 模块暂存过来,缓存键是
-(工具链 × 标准 × 方言)——所以普通构建下这是零成本,产物本来就在。只有交叉构建
-(`--target …`)才会多编一份:`build.mcpp` 在**宿主**上编译并运行,而工程的目标
+mcpp 会把它自己构建时用的**同一份** std 模块暂存过来，缓存键是
+（工具链 × 标准 × 方言）——所以普通构建下这是零成本，产物本来就在。只有交叉构建
+(`--target …`)才会多编一份：`build.mcpp` 在**宿主**上编译并运行，而工程的目标
 是别的平台。
 
-`#include` 依然有效,对只需要 `std::fopen` 的程序也依然是更合适的选择——构建脚本
+`#include` 依然有效，对只需要 `std::fopen` 的程序也依然是更合适的选择——构建脚本
 没有必须模块化的要求。
 
-凡是 mcpp 能用来构建宿主程序的工具链,都能构建 `build.mcpp`,原生 MSVC 也不例外
-——模块处理读的是主构建同一批表,所以 `cl.exe` 的 `.ifc` + `/reference` 不需要
+凡是 mcpp 能用来构建宿主程序的工具链，都能构建 `build.mcpp`，原生 MSVC 也不例外
+——模块处理读的是主构建同一批表，所以 `cl.exe` 的 `.ifc` + `/reference` 不需要
 单独支持。
 
-## 环境契约(mcpp 0.0.95+)
+## 环境契约（mcpp 0.0.95+）
 
-运行中的程序以 `MCPP_*` 环境变量得到构建上下文(对应 Cargo 的环境变量族),
-也有类型化读取端:
+运行中的程序以 `MCPP_*` 环境变量得到构建上下文（对应 Cargo 的环境变量族），
+也有类型化读取端：
 
 | 变量 | 类型化读取 | 值 |
 |---|---|---|
-| `MCPP_TARGET` | `mcpp::target()` | 解析后的 canonical 三元组(交叉构建下是 `--target` 三元组,原生构建是宿主) |
-| `MCPP_TARGET_OS` *(0.0.100+)* | `mcpp::target_os()` | 目标的 OS 段(`linux`/`macos`/`windows`)——不必再手撕 `MCPP_TARGET` |
-| `MCPP_TARGET_ARCH` *(0.0.100+)* | `mcpp::target_arch()` | 目标的 arch 段(GNU 拼写:`x86_64`、`aarch64`…) |
-| `MCPP_TARGET_ENV` *(0.0.100+)* | `mcpp::target_env()` | 目标的 env 段(`gnu`/`musl`/`msvc`);三元组无 env 段(macOS)时为空串 |
+| `MCPP_TARGET` | `mcpp::target()` | 解析后的 canonical 三元组（交叉构建下是 `--target` 三元组，原生构建是宿主） |
+| `MCPP_TARGET_OS` *(0.0.100+)* | `mcpp::target_os()` | 目标的 OS 段（`linux`/`macos`/`windows`）——不必再手撕 `MCPP_TARGET` |
+| `MCPP_TARGET_ARCH` *(0.0.100+)* | `mcpp::target_arch()` | 目标的 arch 段（GNU 拼写：`x86_64`、`aarch64`…） |
+| `MCPP_TARGET_ENV` *(0.0.100+)* | `mcpp::target_env()` | 目标的 env 段（`gnu`/`musl`/`msvc`）；三元组无 env 段（macOS）时为空串 |
 | `MCPP_HOST` | `mcpp::host()` | 宿主三元组 |
-| `MCPP_PROFILE` | `mcpp::profile()` | 生效 profile 名(`dev`/`release`/…) |
-| `MCPP_TOOLCHAIN_SYSROOT` *(2026.9.5.2+)* | `mcpp::toolchain_sysroot()` | mcpp 传给自己那个编译器的 `--sysroot`;不传时为空串。供运行**第二个**编译器的规则包使用 —— 见上文「驱动第二个编译器」 |
-| `MCPP_TOOLCHAIN_BINUTILS_DIR` *(2026.9.5.2+)* | `mcpp::toolchain_binutils_dir()` | mcpp 用 `-B` 指的目录;不指时为空串(musl 与 MinGW 载荷自带汇编器与链接器) |
-| `MCPP_CXX_STDLIB` *(2026.9.6.3+)* | `mcpp::cxx_stdlib()` | 解析出的工具链使用的 C++ 标准库 —— `libstdc++`、`libc++`、`msvc-stl`;没有工具链解析时为空串。与 `MCPP_TARGET_LIBC` 不是同一个问题,后者是 C 库 |
-| `MCPP_ACCEL` *(2026.9.5.2+)* | `mcpp::accel()` | 本次构建的设备轴,已解析 —— `--accel` / `--no-accel` 优先于 `[build] accel` —— 线上形态 `cuda12.9+{sm_89} ptx>=89`;不要加速器时为空串。规则包从它推导自己的开关(`-gencode`、`--offload-arch`),架构集合因此只在 manifest 写一次。同一个值也喂给 `cfg(accelerator = "…")` 这个 layer 键 |
-| `MCPP_LANGUAGE_MODULES` *(2026.9.7.1+)* | -- | 声明它的那个包设了 `[language] modules` 时为 `1`,否则 `0`。**生成**面向消费者声明的规则读它来在模块接口与头文件之间选择,项目因此只需说一次。旧引擎不设这个变量,规则把缺席读作 `0` —— 也就是这个变量存在之前每个消费者的行为 |
-| `MCPP_PKG_NAME` *(2026.9.7.1+)* | -- | 这个程序所构建的包的 `[package] name`。规则生成的每个名字都由它推导:消费者导入的模块、访问器所在的命名空间、生成头里的符号。在它存在之前,可用的最接近的答案是 `MCPP_MANIFEST_DIR` 的末段,那是目录名 —— 于是一个叫 `vulkan-saxpy` 的包放在名为 `app` 的目录下会生成 `app.shaders`,而工作区里每一个 `<something>/app/` 都声称拥有同一个模块。旧引擎下缺席,规则把缺席读作「沿用先前的推导」 |
-| `MCPP_PKG_NAMESPACE` *(2026.9.7.1+)* | -- | `[package] namespace`。包未声明命名空间时为空。需要产出在索引范围内唯一的名字的规则用这一对而不是单用名字,因为包身份是 `(namespace, name)` |
-| `MCPP_PKG_VERSION` *(2026.9.11.1+)* | `mcpp::package_version()` | `[package] version`。每一种安装包格式都要写版本号;在这个变量之前,项目只能把版本号在成员自己的 options 里再写一遍,而那份副本会与 `[package]` 漂移,且没有任何东西能发现 |
+| `MCPP_PROFILE` | `mcpp::profile()` | 生效 profile 名（`dev`/`release`/…） |
+| `MCPP_TOOLCHAIN_SYSROOT` *(2026.9.5.2+)* | `mcpp::toolchain_sysroot()` | mcpp 传给自己那个编译器的 `--sysroot`；不传时为空串。供运行**第二个**编译器的规则包使用 —— 见上文「驱动第二个编译器」 |
+| `MCPP_TOOLCHAIN_BINUTILS_DIR` *(2026.9.5.2+)* | `mcpp::toolchain_binutils_dir()` | mcpp 用 `-B` 指的目录；不指时为空串（musl 与 MinGW 载荷自带汇编器与链接器） |
+| `MCPP_CXX_STDLIB` *(2026.9.6.3+)* | `mcpp::cxx_stdlib()` | 解析出的工具链使用的 C++ 标准库 —— `libstdc++`、`libc++`、`msvc-stl`；没有工具链解析时为空串。与 `MCPP_TARGET_LIBC` 不是同一个问题，后者是 C 库 |
+| `MCPP_ACCEL` *(2026.9.5.2+)* | `mcpp::accel()` | 本次构建的设备轴，已解析 —— `--accel` / `--no-accel` 优先于 `[build] accel` —— 线上形态 `cuda12.9+{sm_89} ptx>=89`；不要加速器时为空串。规则包从它推导自己的开关（`-gencode`、`--offload-arch`），架构集合因此只在 manifest 写一次。同一个值也喂给 `cfg(accelerator = "…")` 这个 layer 键 |
+| `MCPP_LANGUAGE_MODULES` *(2026.9.7.1+)* | -- | 声明它的那个包设了 `[language] modules` 时为 `1`，否则 `0`。**生成**面向消费者声明的规则读它来在模块接口与头文件之间选择，项目因此只需说一次。旧引擎不设这个变量，规则把缺席读作 `0` —— 也就是这个变量存在之前每个消费者的行为 |
+| `MCPP_PKG_NAME` *(2026.9.7.1+)* | -- | 这个程序所构建的包的 `[package] name`。规则生成的每个名字都由它推导：消费者导入的模块、访问器所在的命名空间、生成头里的符号。在它存在之前，可用的最接近的答案是 `MCPP_MANIFEST_DIR` 的末段，那是目录名 —— 于是一个叫 `vulkan-saxpy` 的包放在名为 `app` 的目录下会生成 `app.shaders`，而工作区里每一个 `<something>/app/` 都声称拥有同一个模块。旧引擎下缺席，规则把缺席读作「沿用先前的推导」 |
+| `MCPP_PKG_NAMESPACE` *(2026.9.7.1+)* | -- | `[package] namespace`。包未声明命名空间时为空。需要产出在索引范围内唯一的名字的规则用这一对而不是单用名字，因为包身份是 `(namespace, name)` |
+| `MCPP_PKG_VERSION` *(2026.9.11.1+)* | `mcpp::package_version()` | `[package] version`。每一种安装包格式都要写版本号；在这个变量之前，项目只能把版本号在成员自己的 options 里再写一遍，而那份副本会与 `[package]` 漂移，且没有任何东西能发现 |
 | `MCPP_PKG_DESCRIPTION` *(2026.9.11.1+)* | `mcpp::package_description()` | `[package] description`。包未声明时为空 |
 | `MCPP_PKG_LICENSE` *(2026.9.11.1+)* | `mcpp::package_license()` | `[package] license` |
-| `MCPP_PKG_AUTHORS` *(2026.9.11.1+)* | `mcpp::package_authors()` | `[package] authors`,以 `;` 连接。不用 `,`:一条 author 的惯例写法是 `Name <mail@host>`,名字里可能带逗号,以逗号连接的列表无法再切回原来的条目 |
+| `MCPP_PKG_AUTHORS` *(2026.9.11.1+)* | `mcpp::package_authors()` | `[package] authors`，以 `;` 连接。不用 `,`：一条 author 的惯例写法是 `Name <mail@host>`，名字里可能带逗号，以逗号连接的列表无法再切回原来的条目 |
 | `MCPP_PKG_REPO` *(2026.9.11.1+)* | `mcpp::package_repo()` | `[package] repo` |
-| `MCPP_TARGET_MIN_PLATFORM_VERSION` *(2026.9.12.3+)* | `mcpp::min_platform_version()` | 项目对这个三元组的下限,用平台自己的措辞:macOS 上是 `[build] macos_deployment_target` 或引擎自带的默认值 `14.0`;iOS 上是 `[build] ios_deployment_target` 原样给出,项目没写就是空;`*-linux-android` 上是 `[target.<triple>] min_api_level`,或已解析 NDK 载荷给出的回落值;其余每一行都是空。取的是有效三元组携带的那个值,并进入重跑键 |
-| `MCPP_PACK_FORMAT` *(2026.9.11.1+)* | `mcpp::pack_format()` | 本程序所处的这次 `mcpp pack` 的 `--format` 取值;任何普通构建下都为空。承载含义的正是这个空值 —— 成员据此为自己的提交加闸,于是 `mcpp build` 拿到的还是它一直以来的那张图 |
-| `MCPP_PACK_STAGE_DIR` *(2026.9.11.1+)* | `mcpp::pack_stage_dir()` | `mcpp pack` 已经把闭包暂存到的位置,绝对路径;本次构建不在打包时为空。读它来判断这次要干的活是什么形状,而把 `${mcpp.stage_dir}` 写进 action —— 这样图里的路径与程序读到的路径不可能不一致 |
-| `MCPP_PACK_STRIP` *(2026.9.16.1+)* | `mcpp::pack_strip()` | 本程序所处的这次 `mcpp pack` 剥离时为 `1`,`--no-strip` 下为 `0`;任何普通构建下都为空。自己暂存库的成员跟随它,于是一个开关管住包里的每个文件 |
-| `MCPP_PACK_DEBUG_SYMBOLS_DIR` *(2026.9.16.1+)* | `mcpp::pack_debug_symbols_dir()` | `--debug-symbols` 放置分离出的 `*.debug` 文件的位置,绝对路径;丢弃调试信息或本次构建不在打包时为空 |
-| `MCPP_DEVICE_SOURCES` *(2026.9.5.2+)* | `mcpp::device_sources()` | 本包有效 `sources` 匹配到的设备类源文件(`.cu`、`.hip`…),相对包根,一行一个;没有时为空串。引擎一个都不编译 —— 由本程序引入的规则包把每一个变成一条 `mcpp::action`。已经过收窄:构建未覆盖的 `{ glob, accel }` 条目贡献为空,因此 `--no-accel` 得到空列表 |
+| `MCPP_TARGET_MIN_PLATFORM_VERSION` *(2026.9.12.3+)* | `mcpp::min_platform_version()` | 项目对这个三元组的下限，用平台自己的措辞：macOS 上是 `[build] macos_deployment_target` 或引擎自带的默认值 `14.0`；iOS 上是 `[build] ios_deployment_target` 原样给出，项目没写就是空；`*-linux-android` 上是 `[target.<triple>] min_api_level`，或已解析 NDK 载荷给出的回落值；其余每一行都是空。取的是有效三元组携带的那个值，并进入重跑键 |
+| `MCPP_PACK_FORMAT` *(2026.9.11.1+)* | `mcpp::pack_format()` | 本程序所处的这次 `mcpp pack` 的 `--format` 取值；任何普通构建下都为空。承载含义的正是这个空值 —— 成员据此为自己的提交加闸，于是 `mcpp build` 拿到的还是它一直以来的那张图 |
+| `MCPP_PACK_STAGE_DIR` *(2026.9.11.1+)* | `mcpp::pack_stage_dir()` | `mcpp pack` 已经把闭包暂存到的位置，绝对路径；本次构建不在打包时为空。读它来判断这次要干的活是什么形状，而把 `${mcpp.stage_dir}` 写进 action —— 这样图里的路径与程序读到的路径不可能不一致 |
+| `MCPP_PACK_STRIP` *(2026.9.16.1+)* | `mcpp::pack_strip()` | 本程序所处的这次 `mcpp pack` 剥离时为 `1`，`--no-strip` 下为 `0`；任何普通构建下都为空。自己暂存库的成员跟随它，于是一个开关管住包里的每个文件 |
+| `MCPP_PACK_DEBUG_SYMBOLS_DIR` *(2026.9.16.1+)* | `mcpp::pack_debug_symbols_dir()` | `--debug-symbols` 放置分离出的 `*.debug` 文件的位置，绝对路径；丢弃调试信息或本次构建不在打包时为空 |
+| `MCPP_DEVICE_SOURCES` *(2026.9.5.2+)* | `mcpp::device_sources()` | 本包有效 `sources` 匹配到的设备类源文件（`.cu`、`.hip`…），相对包根，一行一个；没有时为空串。引擎一个都不编译 —— 由本程序引入的规则包把每一个变成一条 `mcpp::action`。已经过收窄：构建未覆盖的 `{ glob, accel }` 条目贡献为空，因此 `--no-accel` 得到空列表 |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | mcpp 提供的可写输出/暂存目录 |
-| `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | 包根(= CWD) |
-| `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | 每个活跃 feature 置 `1`(`<NAME>` 消毒规则与 `MCPP_FEATURE_` 编译宏一致) |
+| `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | 包根（= CWD） |
+| `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | 每个活跃 feature 置 `1`（`<NAME>` 消毒规则与 `MCPP_FEATURE_` 编译宏一致） |
 | `MCPP_FEATURES` | — | 活跃 feature 逗号列表 |
-| `MCPP_DEP_<NAME>_DIR` | `mcpp::dep_dir("name")` | 每个已声明依赖解析后的安装目录(限定名 `namespace.name`、canonical 名,以及无歧义时的去命名空间短名,都可用;`<NAME>` 消毒规则同 `MCPP_FEATURE_`)。依赖包的 build.mcpp **和**根工程的 build.mcpp 都能拿到(根工程的 build.mcpp 在依赖解析之后运行,0.0.100+) |
-| `MCPP_DEP_<NAME>_LINKAGE` *(2026.9.15.2+)* | `mcpp::dep_linkage("name")` | 每个依赖在本次构建中的链接形态,`static` 或 `shared`,名字与 `MCPP_DEP_<NAME>_DIR` 相同;没有库形态的依赖为空。该值就是决定链接内容的那次解析,生成的加载入口或 `dllimport` 声明因此与之一致。只有**根工程**的 build.mcpp 能拿到:根工程决定每个依赖的形态,而依赖包的程序运行在发现顺序更靠后的包之前,那些包的程序提供了答案所依赖的事实,所以在那里 `dep_linkage` 总是为空 |
-| `MCPP_GRAPH_FILE` *(2026.9.16.1+)* | `mcpp::graph_file()` | 以 JSON 文档表示的解析后依赖图,包按依赖顺序排列,每个包带其清单目录、feature、target 与 `[package.metadata]`(见[读取解析后的依赖图](#读取解析后的依赖图graph_file20269161))。只有**根工程**的 build.mcpp 能拿到;文档内容进入重跑键 |
+| `MCPP_DEP_<NAME>_DIR` | `mcpp::dep_dir("name")` | 每个已声明依赖解析后的安装目录（限定名 `namespace.name`、canonical 名，以及无歧义时的去命名空间短名，都可用；`<NAME>` 消毒规则同 `MCPP_FEATURE_`）。依赖包的 build.mcpp **和**根工程的 build.mcpp 都能拿到（根工程的 build.mcpp 在依赖解析之后运行，0.0.100+） |
+| `MCPP_DEP_<NAME>_LINKAGE` *(2026.9.15.2+)* | `mcpp::dep_linkage("name")` | 每个依赖在本次构建中的链接形态，`static` 或 `shared`，名字与 `MCPP_DEP_<NAME>_DIR` 相同；没有库形态的依赖为空。该值就是决定链接内容的那次解析，生成的加载入口或 `dllimport` 声明因此与之一致。只有**根工程**的 build.mcpp 能拿到：根工程决定每个依赖的形态，而依赖包的程序运行在发现顺序更靠后的包之前，那些包的程序提供了答案所依赖的事实，所以在那里 `dep_linkage` 总是为空 |
+| `MCPP_GRAPH_FILE` *(2026.9.16.1+)* | `mcpp::graph_file()` | 以 JSON 文档表示的解析后依赖图，包按依赖顺序排列，每个包带其清单目录、feature、target 与 `[package.metadata]`（见[读取解析后的依赖图](#读取解析后的依赖图graph_file20269161)）。只有**根工程**的 build.mcpp 能拿到；文档内容进入重跑键 |
 
-这些契约值**无条件**折入重跑键——换 target、换 profile、开关 feature 都会触发重跑,
+这些契约值**无条件**折入重跑键——换 target、换 profile、开关 feature 都会触发重跑，
 不需要任何 `rerun-if-env-changed` 声明。
 
-### `PATH` —— 项目声明的那个环境(mcpp 2026.8.25.1+)
+### `PATH` —— 项目声明的那个环境（mcpp 2026.8.25.1+）
 
-声明了 `[xlings].subos` 的项目,其构建程序运行时,该环境的 `bin` 在 `PATH` 的
-最前面:
+声明了 `[xlings].subos` 的项目，其构建程序运行时，该环境的 `bin` 在 `PATH` 的
+最前面：
 
 ```
-PATH=<被声明环境的 bin>:<mcpp 自己启动时的 PATH>
+PATH=<the declared environment's bin>:<the PATH mcpp itself was started with>
 ```
 
-于是构建程序里的裸名命令,在每一台构建它的机器上都解析到项目点名的那个环境
+于是构建程序里的裸名命令，在每一台构建它的机器上都解析到项目点名的那个环境
 里面。
 
 **只对声明了的项目生效。** 没有 `[xlings].subos` 的项目拿到的是 mcpp 启动时
-的 `PATH`,逐字节不变。把一个共享目录放到每个项目前面,会让「构建看见什么」取
-决于这台机器上还装过什么——同一台机器上的两个项目彼此一致,而同一个项目在两台
+的 `PATH`，逐字节不变。把一个共享目录放到每个项目前面，会让「构建看见什么」取
+决于这台机器上还装过什么——同一台机器上的两个项目彼此一致，而同一个项目在两台
 机器上不一致。
 
-前置而非替换的理由:构建程序理应会调 `git`、`python3` 或 shell,这些都不在
-SubOS 里。前置让被声明的环境成为默认答案;宿主仍在其后可达。
+前置而非替换的理由：构建程序理应会调 `git`、`python3` 或 shell，这些都不在
+SubOS 里。前置让被声明的环境成为默认答案；宿主仍在其后可达。
 
-**`command -v` 回答的是这台机器,不是这次构建。** 在此之前,构建程序拿
-`PATH` 去问一个被声明过的工具,可能问到无关的那个——实测于
-`qemu-system-riscv64`:答案是一个执行时报「is not installed in this subos」的
-shim,而可用的那份就在项目自己的环境里,根本不在 `PATH` 上。
+**`command -v` 回答的是这台机器，不是这次构建。** 在此之前，构建程序拿
+`PATH` 去问一个被声明过的工具，可能问到无关的那个——实测于
+`qemu-system-riscv64`：答案是一个执行时报「is not installed in this subos」的
+shim，而可用的那份就在项目自己的环境里，根本不在 `PATH` 上。
 
 这个选择就是[第 8 章](91-toolchain-internals.md)已经描述的那一个——决定项目链接
-哪个 C 库的同一条声明,多交付给了一个消费者。被声明的环境是什么、什么时候需要
-它,见[第 17 章](23-the-project-environment.md);`examples/07-project-subos/` 是
+哪个 C 库的同一条声明，多交付给了一个消费者。被声明的环境是什么、什么时候需要
+它，见[第 17 章](23-the-project-environment.md)；`examples/07-project-subos/` 是
 一个可运行的工程。
 
 ## 写一个规则包
 
-一条规则 ——「对这些 `.proto` 跑 protoc」「对这些源码跑 clang-tidy」—— 属于一个包,
+一条规则 ——「对这些 `.proto` 跑 protoc」「对这些源码跑 clang-tidy」—— 属于一个包，
 而不该被复制到每个消费者的 `build.mcpp` 里。机制是
-[`host-module = true`](../04-mcpp-toml.md);本节讲的是它里面应该长什么样。
+[`host-module = true`](../04-mcpp-toml.md)；本节讲的是它里面应该长什么样。
 
-下面这些从第一个规则包 `mcpplibs.grpcgen` 归纳而来,每一条特征都单独判过是必然还是偶然。
-它们是指引而非规则,因为其中没有一条能给出引擎可以检查的判据。
+下面这些从第一个规则包 `mcpplibs.grpcgen` 归纳而来，每一条特征都单独判过是必然还是偶然。
+它们是指引而非规则，因为其中没有一条能给出引擎可以检查的判据。
 
-**每一个设备源都必须到达某个 action**(2026.9.5.2+ 的契约,自 2026.9.6.5 起强制)。
-设备类源是引擎唯一没有编译规则的源:它经 `MCPP_DEVICE_SOURCES` 交给本包的构建程序,
-要么作为 action 回来,要么根本不会被编译。若有源没有回来,mcpp 拒绝这次构建并点名文件:
+**每一个设备源都必须到达某个 action**（2026.9.5.2+ 的契约，自 2026.9.6.5 起强制）。
+设备类源是引擎唯一没有编译规则的源：它经 `MCPP_DEVICE_SOURCES` 交给本包的构建程序，
+要么作为 action 回来，要么根本不会被编译。若有源没有回来，mcpp 拒绝这次构建并点名文件：
 
     error: `opkit`: device sources that no action compiles:
              src/backends/cuda/saxpy.cu
              src/backends/vulkan/saxpy.comp
 
-判据是 action 的**输入**,而不是「构建程序跑过了」:跑了却什么都没认领恰恰是常见情形,
+判据是 action 的**输入**，而不是「构建程序跑过了」：跑了却什么都没认领恰恰是常见情形，
 因为一条规则只取它认识的扩展名、把其余留给别人。这同时也是 action 本就需要满足的条件
-—— 编译某个文件却不把它声明为输入的 action,在那个文件变化时不会重跑 —— 所以满足这条
-判据的规则也就是能正确增量的规则。它取代的读数是链接期的 undefined reference:那条消息
-点的是符号而从不是那个文件;而 `kind = "lib"` 的目标连这条都没有,因为静态库不做解析。
+—— 编译某个文件却不把它声明为输入的 action，在那个文件变化时不会重跑 —— 所以满足这条
+判据的规则也就是能正确增量的规则。它取代的读数是链接期的 undefined reference：那条消息
+点的是符号而从不是那个文件；而 `kind = "lib"` 的目标连这条都没有，因为静态库不做解析。
 
-**一条规则只取它认领的扩展名。** `mcpp::device_sources()` 是本包设备源的**全集**,
+**一条规则只取它认领的扩展名。** `mcpp::device_sources()` 是本包设备源的**全集**，
 同一个构建程序里的每条规则读到的是同一个值。带两个后端的工程会把一个 `.cu` 和一个
-`.comp` 放进这一份清单,于是把全集拿走的规则会把编译器不接受的文件递给它。规则按扩展名
-挑选,并在本次构建没有命名它所服务的后端时安静返回 —— 带多条规则的构建程序会把它们
+`.comp` 放进这一份清单，于是把全集拿走的规则会把编译器不接受的文件递给它。规则按扩展名
+挑选，并在本次构建没有命名它所服务的后端时安静返回 —— 带多条规则的构建程序会把它们
 全部调用一遍。
 
-**没有任何东西提供的 import 会被点名拒绝。** 一个构建程序可以 import 的是:`std`、
-`std.compat`、内置的 `mcpp`,以及依赖边要来的 host 模块。此外的名字在编译器被调用之前
-就被拒绝,并给出那个本该让它可导入的键:
+**没有任何东西提供的 import 会被点名拒绝。** 一个构建程序可以 import 的是：`std`、
+`std.compat`、内置的 `mcpp`，以及依赖边要来的 host 模块。此外的名字在编译器被调用之前
+就被拒绝，并给出那个本该让它可导入的键：
 
     error: build.mcpp imports 'mcpp.rules.spirv', and no dependency provides it
     as a host module.
@@ -881,119 +881,119 @@ shim,而可用的那份就在项目自己的环境里,根本不在 `PATH` 上。
              <name> = { version = "...", host-module = true }
            declared without `host-module = true`: mcpp.plugins (in [build-dependencies])
 
-**模块名由规则的源码声明,`mcpp.*` 是保留前缀。** host 模块以其接口单元声明的名字注册,
-而不是以包名注册,所以 `export module mcpp.rules.spirv;` 就是消费者 import 的那个名字。
-官方插件集中在一个包里,`mcpp:plugins`(仓库 `mcpp-community/mcpp-plugins`):规则包命名为
-`mcpp.rules.<x>`,构建期工具命名为 `mcpp.tools.<x>`,每个成员由该包的一个 feature 选择
-(见 [`host-module = true`](../04-mcpp-toml.md))。`mcpp.build.*` 是引擎自己的模块族,
-不用于插件。引擎判定不了谁是官方,所以检查以包的**命名空间**为键,两者不一致时告警 ——
+**模块名由规则的源码声明，`mcpp.*` 是保留前缀。** host 模块以其接口单元声明的名字注册，
+而不是以包名注册，所以 `export module mcpp.rules.spirv;` 就是消费者 import 的那个名字。
+官方插件集中在一个包里，`mcpp:plugins`（仓库 `mcpp-community/mcpp-plugins`）：规则包命名为
+`mcpp.rules.<x>`，构建期工具命名为 `mcpp.tools.<x>`，每个成员由该包的一个 feature 选择
+（见 [`host-module = true`](../04-mcpp-toml.md)）。`mcpp.build.*` 是引擎自己的模块族，
+不用于插件。引擎判定不了谁是官方，所以检查以包的**命名空间**为键，两者不一致时告警 ——
 
     warning: build rule 'mcpplibs.plugins' declares the module
     'mcpp.rules.spirv'; the 'mcpp.' prefix is reserved for rules maintained by
     the mcpp project.
 
-什么都不会坏;只是这个名字声称了一个该包并不具有的来源。项目之外的规则自选前缀。
+什么都不会坏；只是这个名字声称了一个该包并不具有的来源。项目之外的规则自选前缀。
 
-**工具不是规则,而可分发物两者都不是。** 三类活计,成员的前缀说明它回答三个问题中的
-哪一个:
+**工具不是规则，而可分发物两者都不是。** 三类活计，成员的前缀说明它回答三个问题中的
+哪一个：
 
 | 前缀 | 回答的问题 | 编译编译单元 | 在构建程序里执行 |
 |---|---|---|---|
 | `rules-*` | 这个编译单元如何被编译 | 是 | 否 |
 | `tools-*` | 构建程序自己需要做什么 | 否 | 是 |
-| `dist-*` *(2026.9.11.1+)* | 链接之后出来的是什么,以及用户以什么形态安装它 | 否 | 否 |
+| `dist-*` *(2026.9.11.1+)* | 链接之后出来的是什么，以及用户以什么形态安装它 | 否 | 否 |
 
-规则说明一个编译单元如何被 mcpp 并不驱动的编译器编译:它提交一条
-action,由引擎调度。工具说明的是构建程序需要、而没有任何编译器执行的事,并在构建程序
-运行时当场做掉。`mcpp.tools.embed`(feature `tools-embed`,mcpp 2026.9.5.4+)是第一个:
-它把数据文件写成程序编译进去的头文件(字节数组或 32 位字数组),内容未变时不重写文件,
+规则说明一个编译单元如何被 mcpp 并不驱动的编译器编译：它提交一条
+action，由引擎调度。工具说明的是构建程序需要、而没有任何编译器执行的事，并在构建程序
+运行时当场做掉。`mcpp.tools.embed`（feature `tools-embed`，mcpp 2026.9.5.4+）是第一个：
+它把数据文件写成程序编译进去的头文件（字节数组或 32 位字数组），内容未变时不重写文件，
 因此无条件调用它不会带来任何重编。
 
 `examples/09-heterogeneous/cuda` 与 `examples/09-heterogeneous/vulkan` 像任何工程一样从 `mcpp:plugins`
 消费 `mcpp.rules.cuda` 与 `mcpp.rules.spirv`。
 
-**分层不得有断崖,且上层必须是下层的组合。** `generate_all(opt)` **就是**
-`submit(plan_all(opt))`,`.grpc = true` **就是** `.plugins = {cpp()}`。超过两个旋钮之后,
-无法继续下降的消费者会手写六十行绕开规则,而那六十行随后就与规则悄悄漂移。
+**分层不得有断崖，且上层必须是下层的组合。** `generate_all(opt)` **就是**
+`submit(plan_all(opt))`，`.grpc = true` **就是** `.plugins = {cpp()}`。超过两个旋钮之后，
+无法继续下降的消费者会手写六十行绕开规则，而那六十行随后就与规则悄悄漂移。
 
-**提供一对 plan/submit。** 最底层必须把计划好的边交回去,让消费者改完再提交。这是让上一段
-成立的机制,不是命名偏好。
+**提供一对 plan/submit。** 最底层必须把计划好的边交回去，让消费者改完再提交。这是让上一段
+成立的机制，不是命名偏好。
 
-**不要复制引擎已经拥有的真相。** mcpp 把每条 action 的完整 argv 写进 `build.ninja`,
+**不要复制引擎已经拥有的真相。** mcpp 把每条 action 的完整 argv 写进 `build.ninja`，
 用 `ninja -t commands` 就能取回。第二个真相源只会漂移。规则拥有的是另一半 ——
 哪些旋钮产生了这条命令 —— 它属于每条边的 `description`。
 
-**失败与提示走不同的通道。** mcpp 只在构建程序非零退出时打印抓到的输出,所以失败写 stderr
+**失败与提示走不同的通道。** mcpp 只在构建程序非零退出时打印抓到的输出，所以失败写 stderr
 并返回非零。而必须在**成功**构建上被看见的消息要走
-[`mcpp::warning`](#warning--成功了而且仍然被听见20268212);成功时的 stderr 被丢弃,
+[`mcpp::warning`](#warning--成功了而且仍然被听见20268212)；成功时的 stderr 被丢弃，
 也就是说选错通道恰好在需要它的那些构建上一言不发。
 
-**一个 `(名字, 版本)` 只对应一份载荷。** mcpp 用这个二元组标识已安装的包,所以一个重新
-打包却保持版本字符串不变的规则不会触发重装,消费者会继续跑旧规则且没有任何诊断。用哪套
-编号由作者决定 —— 与被包装的工具同版本发布是正当的(两者从同一个 tag 出去时,这个号
-告诉消费者的是真话),但载荷变了版本号就必须变。
+**一个 `(名字, 版本)` 只对应一份载荷。** mcpp 用这个二元组标识已安装的包，所以一个重新
+打包却保持版本字符串不变的规则不会触发重装，消费者会继续跑旧规则且没有任何诊断。用哪套
+编号由作者决定 —— 与被包装的工具同版本发布是正当的（两者从同一个 tag 出去时，这个号
+告诉消费者的是真话），但载荷变了版本号就必须变。
 
-**通过消费者来测它。** 规则只被 `build.mcpp` 消费,所以编译它什么都证明不了。它的测试是一个
-依赖它的示例工程:构建,并对产物做断言。
+**通过消费者来测它。** 规则只被 `build.mcpp` 消费，所以编译它什么都证明不了。它的测试是一个
+依赖它的示例工程：构建，并对产物做断言。
 
 ## 依赖包的 build.mcpp(mcpp 0.0.95+)
 
-带 `build.mcpp` 的依赖包也会被编译并运行(Cargo `build.rs` 模型——构建一个包
-即信任其构建程序),时机在其 feature 解析之后、源扫描之前。作用域照 Cargo:
-`cxxflag`/`cflag`/`cfg` 指令只染色**该包自身的 TU**;`link-lib`/`link-search`
-到达终链。其产物(二进制、缓存、`MCPP_OUT_DIR`)放在**消费方工程**的
-`target/.build-mcpp/deps/<pkg>@<ver>/` 下——registry 包根跨工程共享(且可能只读),
-绝不写入;相对 `generated=` 路径按 `MCPP_OUT_DIR` 解析,而非包根。
+带 `build.mcpp` 的依赖包也会被编译并运行（Cargo `build.rs` 模型——构建一个包
+即信任其构建程序），时机在其 feature 解析之后、源扫描之前。作用域照 Cargo:
+`cxxflag`/`cflag`/`cfg` 指令只染色**该包自身的 TU**；`link-lib`/`link-search`
+到达终链。其产物（二进制、缓存、`MCPP_OUT_DIR`）放在**消费方工程**的
+`target/.build-mcpp/deps/<pkg>@<ver>/` 下——registry 包根跨工程共享（且可能只读），
+绝不写入；相对 `generated=` 路径按 `MCPP_OUT_DIR` 解析，而非包根。
 
-### 既独立构建又被当依赖的库:发绝对路径
+### 既独立构建又被当依赖的库：发绝对路径
 
 上面这两条规则——根工程按工程根、依赖按 `MCPP_OUT_DIR`——意味着**相对**
-`generated=` 不可能两种角色都对。而一个库正好两种角色都有:自己的 CI 独立构建它,
+`generated=` 不可能两种角色都对。而一个库正好两种角色都有：自己的 CI 独立构建它，
 别人从 registry 当依赖用它。
 
-写进 `MCPP_OUT_DIR` 再发裸文件名,在依赖角色下能用,在根工程下则失败:
+写进 `MCPP_OUT_DIR` 再发裸文件名，在依赖角色下能用，在根工程下则失败：
 
 ```
 error: build.mcpp declared generated source 'foo.cppm' but it does not exist after the run
 ```
 
-正确做法是写进 `MCPP_OUT_DIR`(包根可能只读),并发**绝对**路径:
+正确做法是写进 `MCPP_OUT_DIR`（包根可能只读），并发**绝对**路径：
 
 ```cpp
 const auto out = std::filesystem::path(mcpp::out_dir()) / "foo.cppm";
-// ... 写文件 ...
+// ... write it ...
 mcpp::generated(out.string().c_str());
 ```
 
-`mcpp::out_dir()` 恒为绝对路径,因此两种角色下都正确,不需要判断自己处在哪一种。
+`mcpp::out_dir()` 恒为绝对路径，因此两种角色下都正确，不需要判断自己处在哪一种。
 
-生成**模块接口**是可以的:`.cppm` 走与其他源文件相同的扫描,所以一个生成出来的、
+生成**模块接口**是可以的：`.cppm` 走与其他源文件相同的扫描，所以一个生成出来的、
 声明 `export module …` 的文件可以被该包自己的 TU import。
 
-## 增量:声明输入(避免无谓重跑)
+## 增量：声明输入（避免无谓重跑）
 
-mcpp **不会**每次构建都重跑 `build.mcpp`。它会缓存程序产出的指令,只有当它依赖的东西
-变化时才重跑:
+mcpp **不会**每次构建都重跑 `build.mcpp`。它会缓存程序产出的指令，只有当它依赖的东西
+变化时才重跑：
 
-- `build.mcpp` 源码本身,
-- 工具链,
-- 任何用 `rerun-if-changed` 声明的文件,
-- 任何用 `rerun-if-env-changed` 声明的环境变量,
-- (或某个 `generated` 产物 / `source=` 选中的文件丢失了),
-- (或该缓存是由一个对某条指令解释不同的 mcpp 写下的——条目带一个格式 **epoch**,
-  遇到不认识的 epoch 就重跑一次,而不是把值按错误的含义重放)。
+- `build.mcpp` 源码本身，
+- 工具链，
+- 任何用 `rerun-if-changed` 声明的文件，
+- 任何用 `rerun-if-env-changed` 声明的环境变量，
+- （或某个 `generated` 产物 / `source=` 选中的文件丢失了），
+- （或该缓存是由一个对某条指令解释不同的 mcpp 写下的——条目带一个格式 **epoch**,
+  遇到不认识的 epoch 就重跑一次，而不是把值按错误的含义重放）。
 
-因此必须**声明输入**:如果程序读了 `config.h` 或 `USE_FAST` 变量,就分别 emit
+因此必须**声明输入**：如果程序读了 `config.h` 或 `USE_FAST` 变量，就分别 emit
 `mcpp:rerun-if-changed=config.h` / `mcpp:rerun-if-env-changed=USE_FAST`。这用一份明确的
 输入/输出契约取代了过去「进程退出码为 0 就当成功」的猜测——让增量构建保持正确。
 
-无变化时输出 `build.mcpp up to date (cached)`;否则是 `build.mcpp compiling` /
+无变化时输出 `build.mcpp up to date (cached)`；否则是 `build.mcpp compiling` /
 `running`。
 
-## 依赖产出的 host 工具(mcpp 2026.8.5.1+)
+## 依赖产出的 host 工具（mcpp 2026.8.5.1+）
 
 一个包能构建出消费者在**构建期**需要的二进制 —— `protoc`、`grpc_cpp_plugin`、
-`flatc`、`moc`、转译器。在依赖上声明:
+`flatc`、`moc`、转译器。在依赖上声明：
 
 ```toml
 [dependencies]
@@ -1001,47 +1001,47 @@ protobuf = { version = "35.1",   tools = ["protoc"] }
 grpc     = { version = "1.83.0", tools = ["grpc_cpp_plugin"] }
 ```
 
-每个名字必须是该包的一个 `kind = "bin"` target。mcpp 会**为构建机器**构建它,
+每个名字必须是该包的一个 `kind = "bin"` target。mcpp 会**为构建机器**构建它，
 并把绝对路径以 `MCPP_DEP_<PKG>_BIN_<TOOL>` 交给 `build.mcpp` —— 用
-`mcpp::dep_bin("protobuf", "protoc")` 读取(见 [30 — build.mcpp](30-build-mcpp.md))。
+`mcpp::dep_bin("protobuf", "protoc")` 读取（见 [30 — build.mcpp](30-build-mcpp.md)）。
 
-四条值得知道的性质:
+四条值得知道的性质：
 
-- **永远是 host 二进制。** 即使 `mcpp build --target <triple>`,工具依然为**本机**
-  构建 —— 代码生成器必须在这里跑。它是一次独立的、面向 host 的子构建:工具包
-  自己的 `[toolchain]`、自己的依赖解析生效,不需要与当前构建一致。安全的原因是
+- **永远是 host 二进制。** 即使 `mcpp build --target <triple>`，工具依然为**本机**
+  构建 —— 代码生成器必须在这里跑。它是一次独立的、面向 host 的子构建：工具包
+  自己的 `[toolchain]`、自己的依赖解析生效，不需要与当前构建一致。安全的原因是
   可执行文件与工程代码**零 ABI 接触**。
-- **单一版本轴。** 工具的版本**就是**依赖的版本,所以「protoc 与其运行时不匹配」
-  这种情况**不可表达**。(把工具单独打包正是会出这个问题,而且它在**运行期**才咬人,
-  不是编译期。)
-- **默认关闭。** 没人要就什么都不构建,成本由消费者付。包用 `[features]` +
-  `required_features` 给昂贵的部分加门(protobuf 的 `protoc` 需要 libprotoc 的
-  ~157 个额外 TU,只用运行时的人绝不该编译它)。
-- **全局缓存**,按 包的源码 × host 工具链 × feature × 自身依赖闭包 键控 —— 每台机器
-  构建一次,而不是每个工程一次。
-
-**这个键里有源码,以每种来源能给出的形式。** 已发布的版本不可变,所以对来自索引的
-工具,版本本身就标识了源码。`git` 工具按解析出的 commit 键控。`path` 工具没有随源码
-移动的版本,所以按树的印记键控:每个普通文件的相对路径、大小与修改时间,不计
+- **单一版本轴。** 工具的版本**就是**依赖的版本，所以「protoc 与其运行时不匹配」
+  这种情况**不可表达**。（把工具单独打包正是会出这个问题，而且它在**运行期**才咬人，
+  不是编译期。）
+- **默认关闭。** 没人要就什么都不构建，成本由消费者付。包用 `[features]` +
+  `required_features` 给昂贵的部分加门（protobuf 的 `protoc` 需要 libprotoc 的
+  ~157 个额外 TU，只用运行时的人绝不该编译它）。
+- **全局缓存**，按 包的源码 × host 工具链 × feature × 自身依赖闭包 键控 —— 每台机器
+  构建一次，而不是每个工程一次。
+
+**这个键里有源码，以每种来源能给出的形式。** 已发布的版本不可变，所以对来自索引的
+工具，版本本身就标识了源码。`git` 工具按解析出的 commit 键控。`path` 工具没有随源码
+移动的版本，所以按树的印记键控：每个普通文件的相对路径、大小与修改时间，不计
 `target/`、`.git/`、`.mcpp/` 与 compile database。于是改动工具的 emitter 在下一次构建
-到达消费者,改回去也到达,而没有变化的树仍是 store 命中、不重建。在
+到达消费者，改回去也到达，而没有变化的树仍是 store 命中、不重建。在
 [`examples/12-a-new-device-language`](../../examples/12-a-new-device-language/)
-上实测;此前这个键只有版本,改动 emitter 之后 `mcpp run` 打印的是上一次的答案,直到
-版本被抬高。树被编辑时条目会累积;`mcpp cache clean` 清空 store,路径是
+上实测；此前这个键只有版本，改动 emitter 之后 `mcpp run` 打印的是上一次的答案，直到
+版本被抬高。树被编辑时条目会累积；`mcpp cache clean` 清空 store，路径是
 `<mcpp cache dir>/tool/<index>/<name>@<version>[+<source>]/`。
 
-**工具构建写出的路径长度有界(2026.9.15.2+)。** 子构建在
-`<mcpp cache dir>/tool/.build/<hash>/` 中进行,这个目录由条目与消费工程命名,不嵌套在
-条目之内,二进制发布后即被删除。构建程序从自身包之外选入的源文件(例如用
-`mcpp::source` 选入依赖根下的文件)编译到
-`obj/<包>/__pkg/<所属包>/<在该包内的路径>`;没有任何包包含它时,编译到
-`obj/<包>/__ext/<其目录的哈希>/`。因此地址不随两个包之间的距离增长。在 Windows 上,
-引擎自己的构建步骤(`dyndep`、`stage`、BMI 相关的边、`coff-def` 与检查戳)以
-extended-length 路径打开文件。在这些改动之前,一个工具的扫描产物在 Windows runner
-上达到 271 个字符而无法读取(#641)。
+**工具构建写出的路径长度有界（2026.9.15.2+）。** 子构建在
+`<mcpp cache dir>/tool/.build/<hash>/` 中进行，这个目录由条目与消费工程命名，不嵌套在
+条目之内，二进制发布后即被删除。构建程序从自身包之外选入的源文件（例如用
+`mcpp::source` 选入依赖根下的文件）编译到
+`obj/<包>/__pkg/<所属包>/<在该包内的路径>`；没有任何包包含它时，编译到
+`obj/<包>/__ext/<其目录的哈希>/`。因此地址不随两个包之间的距离增长。在 Windows 上，
+引擎自己的构建步骤（`dyndep`、`stage`、BMI 相关的边、`coff-def` 与检查戳）以
+extended-length 路径打开文件。在这些改动之前，一个工具的扫描产物在 Windows runner
+上达到 271 个字符而无法读取（#641）。
 
-action 自己的跟踪与 store 的键是两回事。把工具列进 action 输入的规则,会在那个文件的
-字节变化时重跑 —— 实测直接覆盖 store 里的二进制,产物随之改变。
+action 自己的跟踪与 store 的键是两回事。把工具列进 action 输入的规则，会在那个文件的
+字节变化时重跑 —— 实测直接覆盖 store 里的二进制，产物随之改变。
 
 ### `[tools.overrides]` —— 使用已有的二进制
 
@@ -1050,20 +1050,20 @@ action 自己的跟踪与 store 的键是两回事。把工具列进 action 输
 "compat.protobuf:protoc" = "/usr/bin/protoc"
 ```
 
-或者不改 manifest(CI、发行版打包):
+或者不改 manifest（CI、发行版打包）：
 
 ```bash
 MCPP_TOOL_PROTOBUF_PROTOC=/usr/bin/protoc mcpp build
 ```
 
-命中 override 会**完全跳过构建**。每个同类系统都提供这条逃生舱(vcpkg 的
-`VCPKG_HOST_TRIPLET`、CMake 的 `LLVM_NATIVE_TOOL_DIR`、Qt 的 `QT_HOST_PATH`),
-理由一样:一个在本机构建不出来的工具**不能是死路**。它**刻意不进** cache key ——
+命中 override 会**完全跳过构建**。每个同类系统都提供这条逃生舱（vcpkg 的
+`VCPKG_HOST_TRIPLET`、CMake 的 `LLVM_NATIVE_TOOL_DIR`、Qt 的 `QT_HOST_PATH`），
+理由一样：一个在本机构建不出来的工具**不能是死路**。它**刻意不进** cache key ——
 逃生舱不是可复现输入。
 
 ### `host-module = true` —— 可复用的构建规则以包分发
 
-一条规则(比如「对这些 `.proto` 跑 protoc」)应该**写一次**,而不是复制进每个
+一条规则（比如「对这些 `.proto` 跑 protoc」）应该**写一次**，而不是复制进每个
 消费者的 `build.mcpp`。把它做成普通的 mcpp 库包再 import:
 
 ```toml
@@ -1078,43 +1078,43 @@ import protobufgen;
 int main() { return protobufgen::generate({"schema"}) ? 0 : 1; }
 ```
 
-mcpp 会把该包的 lib 根模块**为 host 编译,且与 `build.mcpp` 在同一条命令里** ——
-这正是 BMI 能用的前提:一个模块接口只对「在 standard / dialect / 编译器身份上与
+mcpp 会把该包的 lib 根模块**为 host 编译，且与 `build.mcpp` 在同一条命令里** ——
+这正是 BMI 能用的前提：一个模块接口只对「在 standard / dialect / 编译器身份上与
 它一致」的编译可导入。
 
-于是规则**有版本、能测试、能通过既有的包管理器分发**,而且是用 **C++** 写的
-—— 不引入第二门语言,这正是 `build.mcpp` 存在的理由。
+于是规则**有版本、能测试、能通过既有的包管理器分发**，而且是用 **C++** 写的
+—— 不引入第二门语言，这正是 `build.mcpp` 存在的理由。
 
 **模块名是规则源码自己声明的那个**(mcpp 2026.8.29.1+)。`export module
-acme.rules.protobuf;` 就以 `acme.rules.protobuf` 被 import,与包叫什么无关。
-模块名是作者定义的 API,不镜像包身份 —— 普通库包一直遵循的就是这条规则。
+acme.rules.protobuf；` 就以 `acme.rules.protobuf` 被 import，与包叫什么无关。
+模块名是作者定义的 API，不镜像包身份 —— 普通库包一直遵循的就是这条规则。
 
-2026.8.29.1 之前 host 模块这条路径注册的是裸 `package.name`,于是声明名与包名
-分叉的规则包在 GCC 上能构建、在 Clang 与 MSVC 上失败:GCC 的 BMI 隐式落在
-`gcm.cache` 且按**声明名**索引,而另外两者拿到的是显式的 `<name>=<bmi>` 映射。
-因此包名不再承担任何 C++ 命名约束,`grpc-rules` 重新是合法包名。
+2026.8.29.1 之前 host 模块这条路径注册的是裸 `package.name`，于是声明名与包名
+分叉的规则包在 GCC 上能构建、在 Clang 与 MSVC 上失败：GCC 的 BMI 隐式落在
+`gcm.cache` 且按**声明名**索引，而另外两者拿到的是显式的 `<name>=<bmi>` 映射。
+因此包名不再承担任何 C++ 命名约束，`grpc-rules` 重新是合法包名。
 
-**两个规则不得声明同一个模块名。** `import` 寻址的是模块,所以两个这样的包对编译器
-不可区分,而它们的 BMI 与对象文件同名 —— 后者覆盖前者,存活的那个对象被送进链接两次。
-mcpp 拒绝这种情形,并点名两个包与各自的 interface 路径。检查的范围是一次 `build.mcpp`
-能看见的那些规则,不是索引级的全局唯一性 —— `path` 依赖与私有 registry 本来就绕得开。
+**两个规则不得声明同一个模块名。** `import` 寻址的是模块，所以两个这样的包对编译器
+不可区分，而它们的 BMI 与对象文件同名 —— 后者覆盖前者，存活的那个对象被送进链接两次。
+mcpp 拒绝这种情形，并点名两个包与各自的 interface 路径。检查的范围是一次 `build.mcpp`
+能看见的那些规则，不是索引级的全局唯一性 —— `path` 依赖与私有 registry 本来就绕得开。
 
 **`mcpp.` 前缀保留给由 mcpp 项目维护的规则。** 不在 `mcpp` 命名空间下的包声明该前缀
-的模块名时给出一条同时点名两者的警告,构建继续。之所以是警告:引擎判定不了谁是官方,
-`path` 依赖、私有镜像与内部 fork 都合法,而且从这里看都一样。
+的模块名时给出一条同时点名两者的警告，构建继续。之所以是警告：引擎判定不了谁是官方，
+`path` 依赖、私有镜像与内部 fork 都合法，而且从这里看都一样。
 
-lib 根必须在 `src/<name>.cppm`(或 `[lib] path` 指向的位置);缺失时报
+lib 根必须在 `src/<name>.cppm`（或 `[lib] path` 指向的位置）；缺失时报
 *"host module 'x': no interface unit at …"*。
 
-**一个包可以提供多条规则,由 feature 选择**(mcpp 2026.9.5.3+)。包解析后的
+**一个包可以提供多条规则，由 feature 选择**(mcpp 2026.9.5.3+)。包解析后的
 `[build] sources` 里 —— 含 feature 加入的源文件 —— 每一个模块接口单元都以它自己声明的
-名字编成一个 host 模块,lib 根排在最前。feature 单元可以 import lib 根;除此之外每个
-单元单独编译,因此只 import `std` 与 `mcpp`。只有写在清单里的源文件参与:未声明
-`sources` 的包所推断出的 `src/**` 不被读取,所以此前发布的规则包暴露的仍是它当时暴露
+名字编成一个 host 模块，lib 根排在最前。feature 单元可以 import lib 根；除此之外每个
+单元单独编译，因此只 import `std` 与 `mcpp`。只有写在清单里的源文件参与：未声明
+`sources` 的包所推断出的 `src/**` 不被读取，所以此前发布的规则包暴露的仍是它当时暴露
 的那一个模块。
 
 ```toml
-# 集合包的 manifest
+# the collection's manifest
 [build]
 sources = ["src/plugins.cppm"]                   # export module mcpp.plugins;
 
@@ -1124,74 +1124,74 @@ rules-spirv = { sources = ["rules/spirv.cppm"] } # export module mcpp.rules.spir
 ```
 
 ```toml
-# 消费者
+# a consumer
 [build-dependencies.mcpp]
 plugins = { version = "0.3.0", features = ["rules-spirv"], host-module = true }
 ```
 
 **用 `[build-dependencies]` 而不是 `[dependencies]`** —— 规则包正是 [04 §2.6.1](04-mcpp-toml.md) 描述的那种
-情形:它的库绝不该到达目标,而它的规则仍然被需要。两条轴是分开的:
-`host-module = true` 说的是**要哪一种构建期产物**,而 section 说的是**这个包是否到达
-目标**;规则包在第二条轴上的答案是"否",而 section 就是说这件事的地方。写在
-`[dependencies]` 里同样能工作 —— 这恰恰是为什么这条区分必须被**陈述**,而不能指望由
+情形：它的库绝不该到达目标，而它的规则仍然被需要。两条轴是分开的：
+`host-module = true` 说的是**要哪一种构建期产物**，而 section 说的是**这个包是否到达
+目标**；规则包在第二条轴上的答案是"否"，而 section 就是说这件事的地方。写在
+`[dependencies]` 里同样能工作 —— 这恰恰是为什么这条区分必须被**陈述**，而不能指望由
 一次失败来教会。
 
-模块集合就是 feature 集合:feature 未激活的单元不编译,import 它会以未知模块失败。
-`mcpp:plugins` 是 mcpp 项目维护的集合(仓库 `mcpp-community/mcpp-plugins`);其成员
-命名为 `mcpp.rules.<x>`(规则包)与 `mcpp.tools.<x>`(构建期工具)。
+模块集合就是 feature 集合：feature 未激活的单元不编译，import 它会以未知模块失败。
+`mcpp:plugins` 是 mcpp 项目维护的集合（仓库 `mcpp-community/mcpp-plugins`）；其成员
+命名为 `mcpp.rules.<x>`（规则包）与 `mcpp.tools.<x>`（构建期工具）。
 
-*仅构建期:* `host-module = true` 的依赖**不会**被编进、也不会被链进本工程的 target,
-它所依赖的东西也不会。它只在 `build.mcpp` 期间运行,别处都不出现。(2026.8.5.2 之前
-它还会被当作普通库再编一遍,这正是规则里 `import mcpp;` 失败的原因:在那第二次编译里
-内置模块并不存在。2026.8.29.1 之前被排除的只有规则本身,它自己的 `[dependencies]`
-仍会被编译并链进消费者的二进制,而规则却 import 不到它们。)
+*仅构建期：* `host-module = true` 的依赖**不会**被编进、也不会被链进本工程的 target,
+它所依赖的东西也不会。它只在 `build.mcpp` 期间运行，别处都不出现。（2026.8.5.2 之前
+它还会被当作普通库再编一遍，这正是规则里 `import mcpp;` 失败的原因：在那第二次编译里
+内置模块并不存在。2026.8.29.1 之前被排除的只有规则本身，它自己的 `[dependencies]`
+仍会被编译并链进消费者的二进制，而规则却 import 不到它们。）
 
-### 依赖另一个规则的规则(mcpp 2026.8.29.1+)
+### 依赖另一个规则的规则（mcpp 2026.8.29.1+）
 
-规则在自己的 `[build-dependencies]` 里声明所需之物,并可以 import 其中标了
-`host-module = true` 的条目:
+规则在自己的 `[build-dependencies]` 里声明所需之物，并可以 import 其中标了
+`host-module = true` 的条目：
 
 ```toml
-# 写在规则包自己的清单里
+# inside the rule package's manifest
 [build-dependencies]
 globbing = { path = "../globbing", host-module = true }
 ```
 
 ```cpp
-// 规则自己的接口
+// the rule's own interface
 export module tidyrule;
 import std;
 import mcpp;
 import globbing;
 ```
 
-mcpp 先编译内层规则,同一条命令、同一套 flag,因此 BMI 的一致性仍是结构性事实而不是
+mcpp 先编译内层规则，同一条命令、同一套 flag，因此 BMI 的一致性仍是结构性事实而不是
 需要事后校验的性质。
 
-消费者**不可以** import `globbing`:构建期的 provision 只在 `reexport = true` 的边上
-再跨一跳,而 mcpp 自己执行这条规则,不交给编译器 —— 在 GCC 上那个 import 会成功,
+消费者**不可以** import `globbing`：构建期的 provision 只在 `reexport = true` 的边上
+再跨一跳，而 mcpp 自己执行这条规则，不交给编译器 —— 在 GCC 上那个 import 会成功，
 然后在别人的机器上失败。
 
-*限制:* 每个 host 模块只有一个接口单元。带实现单元或多个模块的库还不能作为规则的
+*限制：* 每个 host 模块只有一个接口单元。带实现单元或多个模块的库还不能作为规则的
 构建期依赖。
 
-### `reexport = true` —— 由库替用户拉起整条工具链(2026.8.6.2+)
+### `reexport = true` —— 由库替用户拉起整条工具链（2026.8.6.2+）
 
-上面这些都由**使用工具的人**声明。当知识本来属于库时,这个位置就错了:gRPC
-的代码生成需要 protobuf 的 `protoc`,而 gRPC 包的任何使用者都不应该知道这件事。
+上面这些都由**使用工具的人**声明。当知识本来属于库时，这个位置就错了：gRPC
+的代码生成需要 protobuf 的 `protoc`，而 gRPC 包的任何使用者都不应该知道这件事。
 
 `reexport = true` 把一条边上的构建期提供物 —— 它的 `tools`、它的
-`host-module`、以及该依赖的目录 —— 交给**本包自己的消费者**:
+`host-module`、以及该依赖的目录 —— 交给**本包自己的消费者**：
 
 ```toml
-# 写在 grpc 包自己的 manifest 里
+# inside the grpc package's manifest
 [feature-deps.codegen]
-"compat.protobuf" = { version = "35.1",   tools = ["protoc"],          reexport = true }
-grpc-plugin       = { version = "1.83.0", tools = ["grpc_cpp_plugin"], reexport = true }
-grpcgen           = { version = "1.83.0", host-module = true,          reexport = true }
+"compat.protobuf" = { version = "35.1",   tools = ["protoc"],            reexport = true }
+grpc-plugin       = { version = "1.83.0", tools = ["grpc_cpp_plugin"],   reexport = true }
+grpcgen           = { version = "1.83.0", host-module = true,            reexport = true }
 ```
 
-于是使用者只写一行,再 import 那个规则:
+于是使用者只写一行，再 import 那个规则：
 
 ```toml
 [dependencies]
@@ -1205,51 +1205,51 @@ import grpcgen;
 int main() { return grpcgen::generate_all() ? 0 : 1; }
 ```
 
-- **默认关闭,并且刻意不复用边上的 `visibility`。** `visibility` 本身默认就是
-  `"public"`,复用该可见性意味着任意深度的依赖都能静默地向构建程序的工具
-  命名空间里塞东西。「把某样东西交给消费者」是一条供应链主张,必须写下来。
-- **一次声明只走一跳。** 被再导出的提供物到达声明它的那个包的消费者;要继续
-  往上走,下一个包必须自己也写 `reexport`。每个包只决定**它**交出什么。
+- **默认关闭，并且刻意不复用边上的 `visibility`。** `visibility` 本身默认就是
+  `"public"`，复用该可见性意味着任意深度的依赖都能静默地向构建程序的工具
+  命名空间里塞东西。「把某样东西交给消费者」是一条供应链主张，必须写下来。
+- **一次声明只走一跳。** 被再导出的提供物到达声明它的那个包的消费者；要继续
+  往上走，下一个包必须自己也写 `reexport`。每个包只决定**它**交出什么。
 - **feature 可以往一条已经声明过的依赖上追加请求。** gRPC 无条件依赖 protobuf,
   而它的 `codegen` feature 往同一条边加 `tools = ["protoc"], reexport = true`。
-  `tools` 与 `features` 取并集,`host-module` 与 `reexport` 取或;`version` /
+  `tools` 与 `features` 取并集，`host-module` 与 `reexport` 取或；`version` /
   `path` / `git` 不合并 —— feature 仍然无法静默覆盖无条件条目的身份。
-- **传播的是可见性,不是执行。** `dep_bin()` 只返回路径,跑不跑仍由消费者的
-  `build.mcpp` 决定;谁构建了这个工具、tool store 怎么做键,都不改变。
-- **裸名由阶梯决定,而不是靠运气。** 一旦两个库都能再导出,它们可能同时提供
-  尾名 `protobuf`。全限定的 `MCPP_DEP_<NS>_<NAME>_BIN_<TOOL>` 总是发布;裸名
-  依次绑定到 `mcpplibs.<x>`、`compat.<x>`、无命名空间的 `<x>`,最后才是「剩下
-  的唯一候选」——存在争用时 mcpp 会说出来,而不是默默选一个。
+- **传播的是可见性，不是执行。** `dep_bin()` 只返回路径，跑不跑仍由消费者的
+  `build.mcpp` 决定；谁构建了这个工具、tool store 怎么做键，都不改变。
+- **裸名由阶梯决定，而不是靠运气。** 一旦两个库都能再导出，它们可能同时提供
+  尾名 `protobuf`。全限定的 `MCPP_DEP_<NS>_<NAME>_BIN_<TOOL>` 总是发布；裸名
+  依次绑定到 `mcpplibs.<x>`、`compat.<x>`、无命名空间的 `<x>`，最后才是「剩下
+  的唯一候选」——存在争用时 mcpp 会说出来，而不是默默选一个。
 - **工具的名字与它的目录的名字完全相同。** `dep_dir`、`dep_linkage` 与 `dep_bin`
-  使用同一个推导为提供者命名:清单的 `name`、限定名 `namespace.name`,以及已绑定的尾名。
-  因此把 `namespace = "spike"` 与 `name = "installer"` 分开写的包,既是
-  `dep_bin("installer", ...)`,也是 `dep_bin("spike.installer", ...)`(mcpp 2026.9.16.1+;
-  此前它的工具只以 `installer` 发布)。
+  使用同一个推导为提供者命名：清单的 `name`、限定名 `namespace.name`，以及已绑定的尾名。
+  因此把 `namespace = "spike"` 与 `name = "installer"` 分开写的包，既是
+  `dep_bin("installer", ...)`，也是 `dep_bin("spike.installer", ...)`（mcpp 2026.9.16.1+;
+  此前它的工具只以 `installer` 发布）。
 
 #### 旧版 mcpp 读到用了这些键的 manifest
 
-不认识的依赖键会被**记为降级**并忽略(mcpp 2026.8.6.2+),因此一份为更新的
-mcpp 写的包仍然能加载,这个读取器认识的部分照常生效。在那之前它是**整份加载
-失败**且报错误导,这正是「已发布的包永远无法采用新键」的原因——与索引下限确立
-的是同一条性质:**数据不得决定程序是否可用**。
+不认识的依赖键会被**记为降级**并忽略（mcpp 2026.8.6.2+），因此一份为更新的
+mcpp 写的包仍然能加载，这个读取器认识的部分照常生效。在那之前它是**整份加载
+失败**且报错误导，这正是「已发布的包永远无法采用新键」的原因——与索引下限确立
+的是同一条性质：**数据不得决定程序是否可用**。
 
-因此,一个**依赖** `reexport` 才有那套人机工程的包,仍然需要足够新的客户端;
+因此，一个**依赖** `reexport` 才有那套人机工程的包，仍然需要足够新的客户端；
 变化在于该包的其余部分在旧客户端上不再一起失效。
 
 #### 按平台裁剪提供物
 
-一个包可能只在部分平台声明 `bin` 目标。既然现在是**库**决定请求什么,无条件的
-请求就会把「不支持的平台」变成用户改不掉的硬错。用条件段裁剪:
+一个包可能只在部分平台声明 `bin` 目标。既然现在是**库**决定请求什么，无条件的
+请求就会把「不支持的平台」变成用户改不掉的硬错。用条件段裁剪：
 
 ```toml
 [target.'cfg(not(windows))'.feature-deps.codegen]
 "compat.protobuf" = { version = "35.1", tools = ["protoc"], reexport = true }
 ```
 
-`[target.<sel>.feature-deps.<feature>]`(2026.8.6.2+)与 `[target.<sel>]` 下的
-其余依赖表(`dependencies` / `dev-dependencies` / `build-dependencies`)遵循同
-一套谓词规则,针对**解析后的 target** 求值。**feature 本身在所有平台都注册**
-—— 只有它拉进来的东西是条件性的 —— 因此在没有任何谓词匹配的平台上请求它,不是
+`[target.<sel>.feature-deps.<feature>]`（2026.8.6.2+）与 `[target.<sel>]` 下的
+其余依赖表（`dependencies` / `dev-dependencies` / `build-dependencies`）遵循同
+一套谓词规则，针对**解析后的 target** 求值。**feature 本身在所有平台都注册**
+—— 只有它拉进来的东西是条件性的 —— 因此在没有任何谓词匹配的平台上请求它，不是
 「未知 feature」错误。
 
 
@@ -1257,45 +1257,45 @@ mcpp 写的包仍然能加载,这个读取器认识的部分照常生效。在
 ## 当前边界
 
 - **在主机上运行——交叉构建下也是**(mcpp 0.0.95+)。`mcpp build --target <triple>`
-  下,程序用宿主解析的工具链编译、在宿主运行,并看到 `MCPP_TARGET` = 交叉三元组。
+  下，程序用宿主解析的工具链编译、在宿主运行，并看到 `MCPP_TARGET` = 交叉三元组。
   纯声明式的目标门控仍首选 `[target.'cfg(...)']` 表——参见
   [04 - mcpp.toml 工程文件指南](04-mcpp-toml.md)。
-- **当前工作目录是工程根目录**,因此相对路径(`src/generated.cpp`)会落在预期位置。
+- **当前工作目录是工程根目录**，因此相对路径（`src/generated.cpp`）会落在预期位置。
 - `build.mcpp` 非零退出会中止构建并打印其输出。
-- **运行有时间上限**(mcpp 2026.8.5.1+):构建程序默认有 **600 秒**,超时后 mcpp
-  杀掉它并让构建失败,错误里会点名是哪个包。可按包配置:
+- **运行有时间上限**(mcpp 2026.8.5.1+)：构建程序默认有 **600 秒**，超时后 mcpp
+  杀掉它并让构建失败，错误里会点名是哪个包。可按包配置：
 
   ```toml
   [build]
-  build_program_timeout = 1800   # 秒;0 = 不限
+  build_program_timeout = 1800   # seconds; 0 = no limit
   ```
 
-  优先级(与 `macos_deployment_target` 同构):
+  优先级（与 `macos_deployment_target` 同构）：
 
   ```
-  MCPP_BUILD_PROGRAM_TIMEOUT=<秒>   本次调用
-    > [build] build_program_timeout  拥有该 build.mcpp 的那个包的 manifest
-    > 600                            内置默认
+  MCPP_BUILD_PROGRAM_TIMEOUT=<seconds>   this invocation only
+    > [build] build_program_timeout      the manifest of the package that OWNS the build.mcpp
+    > 600                                built-in default
   ```
 
-  值取自**拥有该构建程序的包**的 manifest,因为只有它的作者知道生成器要跑多久。
-  当一个**依赖**的构建程序超时时,错误会点名要改的那份 `mcpp.toml` —— 改自己的
+  值取自**拥有该构建程序的包**的 manifest，因为只有它的作者知道生成器要跑多久。
+  当一个**依赖**的构建程序超时时，错误会点名要改的那份 `mcpp.toml` —— 改自己的
   那份不会有任何效果。
 
-  不写这个键与写 `0` 不是一回事:不写=用默认上限,`0`=完全不设上限。
+  不写这个键与写 `0` 不是一回事：不写=用默认上限，`0`=完全不设上限。
 
-  **这个上限从 mcpp 2026.8.11.1 起在所有平台生效**。此前它只在 POSIX 上生效:
-  Windows 的启动器会退回到无界路径,所以这个键——以及 `mcpp test --timeout`、
-  `--build-timeout`——在那里都是静默的空操作。现在 Windows 把子进程放进 Job 对象,
-  到期时关闭它,于是被杀掉的是**整棵进程树**而不只是直接子进程(否则一个还攥着
-  捕获管道的孙进程会让杀掉之后的读取一直挂住)。
+  **这个上限从 mcpp 2026.8.11.1 起在所有平台生效**。此前它只在 POSIX 上生效：
+  Windows 的启动器会退回到无界路径，所以这个键——以及 `mcpp test --timeout`、
+  `--build-timeout`——在那里都是静默的空操作。现在 Windows 把子进程放进 Job 对象，
+  到期时关闭它，于是被杀掉的是**整棵进程树**而不只是直接子进程（否则一个还攥着
+  捕获管道的孙进程会让杀掉之后的读取一直挂住）。
 
-  **编译**这一步刻意**不设**上限——与 `mcpp test` 同一条不对称纪律:
-  编译跑得久通常是正当的(首次构建 `std` 模块就是分钟级),杀掉它只会产生莫名其妙的
-  失败;而构建**程序**跑得久通常是卡住了,不设上限就会让整个构建挂死且毫无诊断。
+  **编译**这一步刻意**不设**上限——与 `mcpp test` 同一条不对称纪律：
+  编译跑得久通常是正当的（首次构建 `std` 模块就是分钟级），杀掉它只会产生莫名其妙的
+  失败；而构建**程序**跑得久通常是卡住了，不设上限就会让整个构建挂死且毫无诊断。
 
   > **为什么不做「超时时询问用户」**([#410](https://github.com/mcpp-community/mcpp/issues/410)):
-  > 构建程序的 stdout 已经被 dup2 进一根承载 `mcpp:` 指令协议的管道,没有交互通道;
-  > 多数构建发生在没有人看的地方(CI、流水线、ninja 的子进程),而一个卡在提示上的
-  > 构建比一个失败的构建更难诊断;并且构建结果不应该取决于一次击键。
-  > 可配置的上限 + 一条点名要改哪个文件的报错,回答的是同一个需求。
+  > 构建程序的 stdout 已经被 dup2 进一根承载 `mcpp:` 指令协议的管道，没有交互通道；
+  > 多数构建发生在没有人看的地方（CI、流水线、ninja 的子进程），而一个卡在提示上的
+  > 构建比一个失败的构建更难诊断；并且构建结果不应该取决于一次击键。
+  > 可配置的上限 + 一条点名要改哪个文件的报错，回答的是同一个需求。
diff --git a/docs/zh/31-authoring-a-rule-package.md b/docs/zh/31-authoring-a-rule-package.md
index 320952dc5..e1c81c33f 100644
--- a/docs/zh/31-authoring-a-rule-package.md
+++ b/docs/zh/31-authoring-a-rule-package.md
@@ -1,76 +1,80 @@
 # 31 —— 编写规则包
 
-**读者:**要把一步构建工作打包给别的工程使用的生态作者 —— 一种设备语言、一个
-着色器编译器、一个生成的接口,或者一项检查。
-
-**本章回答的那一个问题:**一个包怎样供给一条规则,以及消费者要写什么才能用上它。
-
-**不在这里:**给单个工程自己的构建加一步,那是
-[30 —— 构建程序](30-build-mcpp.md) —— 同一批原语,规模更小;feature 相关键本身,
-那是 [06](06-features-and-capabilities.md);以及已发布规则各自的拼法,那属于
-`mcpp:plugins`。示例:[`08-build-rules`](../../examples/08-build-rules/) 做检查与
-嵌入,[`12-a-new-device-language`](../../examples/12-a-new-device-language/) 新增
+**读者：** 要把一步构建工作打包给其他工程使用的生态作者 —— 一门设备语言、
+一个着色器编译器、一个生成的接口，或者一项检查。
+
+**本章回答的那一个问题：** 一个包怎样供给一条规则，以及消费方要写什么才能
+用上它。
+
+**不在这里：** 给单个工程自己的构建加一步，那是
+[30 —— 构建程序](30-build-mcpp.md) —— 同一批原语，规模更小；feature 相关
+的键本身，那是 [06](06-features-and-capabilities.md)；以及已发布规则各自
+的拼法，那属于 `mcpp:plugins`。示例：
+[`08-build-rules`](../../examples/08-build-rules/) 做检查与嵌入，
+[`12-a-new-device-language`](../../examples/12-a-new-device-language/) 新增
 一门语言。
 
 ## 扩展模型
 
-mcpp 的构建表面由包扩展,而不是由发布扩展。做扩展的有五个点,而经由它们进来的任何
-名字,引擎都不持有。
+mcpp 的构建表面由包扩展，而不是由发布扩展。做扩展的有五个点，经由它们进来
+的任何名字，引擎都不持有。
 
 | 扩展点 | 效果 | 声明位置 |
 |---|---|---|
-| `mcpp::action` | 构建图里的一条边:一条命令,带声明的输入与输出 | 构建程序,或它 import 的规则模块 |
-| `device_extensions` | 一个扩展名被引擎归类为**设备源**,而不是被拒绝 | 包的某个 feature |
-| `rule_module` | 消费者的构建程序 import 哪个模块来够到这条规则 | 同一个 feature |
-| `tools = [...]` | 一个**从源码为构建机构建**的生成器或编译器,用 `mcpp::dep_bin` 取到 | 一条依赖边 |
-| `[xlings]`、`[feature-xlings]` | 规则要运行的预建工具,按需安装 | 包本身,或它的某个 feature |
+| `mcpp::action` | 构建图里的一条边：一条命令，带声明的输入与输出 | 构建程序，或它 import 的规则模块 |
+| `device_extensions` | 一个扩展名被引擎归类为**设备源**，而不是被拒绝 | 包的某个 feature |
+| `rule_module` | 消费方的构建程序 import 哪个模块来够到这条规则 | 同一个 feature |
+| `tools = [...]` | 一个**从源码为构建机构建出来**的生成器或编译器，用 `mcpp::dep_bin` 取到 | 一条依赖边 |
+| `[xlings]`、`[feature-xlings]` | 规则要运行的预建工具，按需安装 | 包本身，或它的某个 feature |
 
-生态用它们建出来的东西:
+生态用它们建出来的东西：
 
 | 扩展面 | 所在包 | 使用的扩展点 |
 |---|---|---|
-| CUDA、HIP、SYCL、Ascend C | `mcpp:plugins`,各一个 feature([42](42-heterogeneous-builds.md)) | 驱动厂商编译器的 action,加上按加速器设闸的载荷 |
+| CUDA、HIP、SYCL、Ascend C | `mcpp:plugins`，各一个 feature（[42](42-heterogeneous-builds.md)） | 驱动厂商编译器的 action，加上按加速器设闸的载荷 |
 | Slang | `mcpp:plugins` 的 `rules-slang` | `device_extensions = [".slang"]` —— 第一门无需引擎点名即被支持的语言 |
-| GLSL 与 HLSL 到 SPIR-V,以及其上的模块 | `mcpp:plugins` 的 `rules-spirv` | 每个着色器一条 action,加上一个生成的模块 |
-| 设备与 C++ 之间的岛边界 | `mcpp.tools.island` | 一个生成器,加上 `mcpp::generated` |
+| GLSL 与 HLSL 到 SPIR-V，以及其上的模块 | `mcpp:plugins` 的 `rules-spirv` | 每个着色器一条 action，加上一个生成的模块 |
+| 设备与 C++ 之间的岛边界 | `mcpp.tools.island` | 一个生成器，加上 `mcpp::generated` |
 | 作为可链接对象的资源文件 | [`08-build-rules`](../../examples/08-build-rules/) | `role = "object"` |
 | 能让构建失败的检查 | [`08-build-rules`](../../examples/08-build-rules/) | `role = "check"` |
-| 引擎从未听说过的语言 | [`12-a-new-device-language`](../../examples/12-a-new-device-language/) | `device_extensions`,加上经 `tools = [...]` 构建出来的编译器 |
+| 引擎从未听说过的语言 | [`12-a-new-device-language`](../../examples/12-a-new-device-language/) | `device_extensions`，加上经 `tools = [...]` 构建出来的编译器 |
 
 ### 这个模型能表达的形态
 
-**一门新语言,不论由什么编译它。** 规则声明它认领的扩展名、为每个源提交一条
-action,并把编译器列进这条 action 的输入。这个编译器可以是厂商工具包、一个 LLVM
-前端、一个发出设备二进制的解释器,也可以是规则包自己从源码构建出来的程序。它产出
-的是设备二进制、目标文件还是 C++,由 action 的 `role` 决定,别无其他。引擎始终不
-学习这门语言:它学到的是「某个扩展名是设备源」以及「某条 action 认领它」。
-
-**预处理与代码生成。** `role = "source"` 的 action 产出 C++,由声明它的包随后编译,
-而该包的每一条编译边都等它。输入可以是模板、接口定义、一张表,或另一条 action 的
-输出 —— 串联是常规做法,因为 action 之间由文件定序并计入指纹。
-
-**一个一半是 C++、一半是另一种语言的文件。** 归类发生在任何规则运行之前,所以带着
-引擎自有扩展名的文件按 C++ 编译,永远到不了规则那里。因此一个携带外来代码块的源要
-用规则认领的扩展名,再由规则把它拆开:抽出来的 C++ 走 `role = "source"`,外来的那
-一半走规则自己的编译器,两者之间的缝就是
-[42 —— 异构构建](42-heterogeneous-builds.md) 里的 `extern "C"` 边界。本仓库今天没有
-任何包是这个形态。
+**一门新语言，不论由什么编译它。** 一条规则声明它认领的扩展名，为每个源
+提交一条 action，并把编译器列进这条 action 的输入。这个编译器可以是厂商
+工具包、一个 LLVM 前端、一个发出设备二进制的解释器，也可以是规则包自己从
+源码构建出来的程序。它产出的是设备二进制、目标文件还是 C++，由 action 的
+`role` 决定，别无其他。引擎始终不学习这门语言：它学到的是"某个扩展名是
+设备源"以及"某条 action 认领它"。
+
+**预处理与代码生成。** `role = "source"` 的 action 产出 C++，由声明它的包
+随后编译，而该包的每一条编译边都要等它。输入可以是一个模板、一份接口
+定义、一张表，或另一条 action 的输出 —— 串联是常规做法，因为 action 之间
+由文件定序、并计入指纹。
+
+**一个一半是 C++、一半是另一种语言的文件。** 归类发生在任何规则运行之前，
+所以一个带着引擎自有扩展名的文件按 C++ 编译，永远到不了规则那里。因此一个
+携带外来代码块的源，要使用规则认领的扩展名，再由规则把它拆开：抽出来的 C++
+走 `role = "source"`，外来的那一半走规则自己的编译器，两者之间的缝就是
+[42 —— 异构硬件构建](42-heterogeneous-builds.md) 里的 `extern "C"` 边界。
+本仓库今天没有任何包是这个形态。
 
 ### 边界
 
-**声明不能重新归类引擎已经拥有的东西。** 依赖的 `device_extensions` 在内建角色
-**之后**才被查询,所以规则包认领不了 `.cpp`、`.cppm`、`.c` 或 `.S`。这些是引擎自己
-的词汇,一个包不得把文件从中挪走。认领它们不会被诊断,也不产生任何效果:实测把
-`".cpp"` 加进某条规则的 `device_extensions`,消费者的 `main.cpp` 仍按 C++ 编译,
-构建成功。
+**声明不能重新归类引擎已经拥有的东西。** 一个依赖的 `device_extensions`
+在内建角色**之后**才被查询，所以一个规则包认领不了 `.cpp`、`.cppm`、`.c`
+或 `.S`。这些是引擎自己的词汇，一个包不得把文件从中挪走。认领它们不会被
+诊断，也不产生任何效果：实测把 `".cpp"` 加进某条规则的 `device_extensions`,
+消费方的 `main.cpp` 仍按 C++ 编译，构建成功。
 
-**模块接口的扩展名是工程的轴,不是规则的轴。** 把接口写成 `.ixx` 的工程声明
-`[build] module_extensions`([04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md))。没有
-任何规则包的键能新增一个,因为模块接口要被扫描 import、要产出 BMI、还要进链接 ——
-这是三项引擎行为,而不是一条要跑的命令。
+**模块接口的扩展名是工程的轴，不是规则的轴。** 把接口写成 `.ixx` 的工程
+声明 `[build] module_extensions`（[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md)）。
+没有任何规则包的键能新增一个，因为一个模块接口要被扫描 import、要产出
+BMI、还要进链接 —— 这是三项引擎行为，而不是一条要跑的命令。
 
-**两张表都不包含的扩展名会被点名拒绝**,所以写错的 `device_extensions` 会立刻显形,
-而不是把一个源默默丢掉:
+**两张表都不包含的扩展名会被点名拒绝**，所以写错的 `device_extensions` 会
+立刻显形，而不是把一个源默默丢掉：
 
 ```
 error: scanner errors:
@@ -82,16 +86,16 @@ error: scanner errors:
 
 ## 规则包的定义
 
-三部分,没有一部分是 mcpp 特有的:
+三部分，没有一部分是 mcpp 特有的：
 
 | 部分 | 内容 |
 |---|---|
-| 一个包 | 普通的 `mcpp.toml`,有版本与许可证 |
-| 一个模块 | 一个 `.cppm`,导出 `options` 与一个提交构建边的函数 |
-| 一个 feature | 选中它的开关,也是它自己的依赖挂靠的地方 |
+| 一个包 | 普通的 `mcpp.toml`，有版本与许可证 |
+| 一个模块 | 一个 `.cppm`，导出 `options` 与一个提交构建边的函数 |
+| 一个 feature | 选中它的开关，也是它自己的依赖挂靠的地方 |
 
-引擎里没有规则名,也没有厂商名。消费者命名这个包、激活一个 feature,构建程序
-import 那个模块。
+引擎里没有规则名，也没有厂商名。消费方命名这个包、激活一个 feature，构建
+程序 import 那个模块。
 
 ## manifest 的三个键
 
@@ -105,26 +109,27 @@ rule_module       = "example.rules.toy"
 device_extensions = [".toy"]
 ```
 
-| 键 | 对消费者的作用 |
+| 键 | 对消费方的作用 |
 |---|---|
 | `sources` | 只有 feature 激活时才编译该模块 |
-| `rule_module`(2026.9.7.1+) | 消费者构建程序 import 的模块。它隐含 `host-module = true` |
-| `device_extensions`(2026.9.7.1+) | 这些扩展名被归类为**设备源**:不做 import 扫描、不产出 BMI,且没有 action 认领时被拒绝 |
+| `rule_module`(2026.9.7.1+) | 消费方构建程序 import 的模块。它隐含 `host-module = true` |
+| `device_extensions`(2026.9.7.1+) | 这些扩展名被归类为**设备源**：不做 import 扫描、不产出 BMI，且没有 action 认领时被拒绝 |
 
 只做生成或检查、不编译某种语言的规则不声明 `device_extensions`;
-`08-build-rules` 是这个形状,它的消费者在依赖边上自己写 `host-module = true`。
+`08-build-rules` 就是这个形状，它的消费方在依赖边上自己写
+`host-module = true`。
 
-设备扩展名不在默认 source glob 里。消费者通过点名这些文件来选入:
+设备扩展名不在默认的 source glob 里。消费方通过点名这些文件来选入：
 
 ```toml
 [build]
 sources = ["src/*.cpp", "src/kernels/*.toy"]
 ```
 
-## 消费者 import 的那个模块
+## 消费方 import 的那个模块
 
-每条已发布规则遵循的写法是:一个带默认值的 `options` 结构,加一个提交边的
-`compile`(或 `generate`)函数:
+每一条已发布规则遵循的写法是：一个带默认值的 `options` 结构，加一个提交边
+的 `compile`（或 `generate`）函数：
 
 ```cpp
 export module example.rules.toy;
@@ -143,18 +148,20 @@ bool compile(options opt = {});
 }
 ```
 
-把「规划边」与「提交边」拆成两个函数的规则,给了消费者一条越过它最后一个旋钮
-而不必手写 action 的路;`08-build-rules` 的 `plan` / `submit` 就是这个形状。
+把"规划边"与"提交边"拆成两个函数的规则，给了消费方一条越过它最后一个
+旋钮、而不必手写 action 的路；`08-build-rules` 的 `plan` / `submit` 就是
+这个形状。
 
-**规则只取自己认领的扩展名,其余留给别人。** `mcpp::device_sources()` 是一个串、
-每行一个包根相对路径,而且它是这个包**全部**的设备集合。一个有两个后端的构建把
-两边的源都放进同一个列表,而构建程序里的每条规则读到的是同一个值。
+**规则只取自己认领的扩展名，其余留给别人。** `mcpp::device_sources()` 是
+一个串，每行一个包根相对路径，而且它是这个包**全部**的设备集合。一个有两个
+后端的构建把两边的源都放进同一个列表，而构建程序里的每一条规则读到的是
+同一个值。
 
-## 声明工作:`mcpp::action`
+## 声明工作：`mcpp::action`
 
 ```cpp
 mcpp::action a;
-a.id          = id.c_str();          // 包内稳定且唯一
+a.id          = id.c_str();          // stable, unique within the package
 a.role        = "source";
 a.description = desc.c_str();
 a.arg("sh").arg(script.c_str()).arg(input.c_str()).arg(output.c_str());
@@ -164,37 +171,38 @@ a.output(output.c_str());
 a.submit();
 ```
 
-这些字符串必须比 action 活得久。`a.id = ("toy:" + stem).c_str()` 交给它的是一个
-指向临时对象的指针,而该临时对象在 `submit()` 之前就已经消失。
+这些字符串必须比 action 活得久。`a.id = ("toy:" + stem).c_str()` 交给它
+的是一个指向临时对象的指针，而该临时对象在 `submit()` 之前就已经消失。
 
 ### 四种 role
 
-`role` 决定这条边的输出去哪里,以及这条边什么时候跑。
+`role` 决定这条边的输出去哪里，以及这条边什么时候跑。
 
 | `role` | 输出 | 次序 |
 |---|---|---|
 | `source` | 可编译的那些进入编译集合 | 声明它的包的每条编译边都等它 |
-| `check` | 一个 stamp 文件 | 与编译并行;`blocking = true` 让编译等它 |
+| `check` | 一个 stamp 文件 | 与编译并行；`blocking = true` 让编译等它 |
 | `object` | 进入**链接**集合 | 链接边消费它们 |
-| `artifact` | 一个新文件 | 它的输入是链接产物,所以它在链接之后跑 |
+| `artifact` | 一个新文件 | 它的输入是链接产物，所以它在链接之后跑 |
 
-### 声明的输入,以及其中的编译器
+### 声明的输入，以及其中的编译器
 
-声明的输入变化时 action 重跑。**命令调用的那个工具也是输入。** 少了它,改动规则
-自己的编译器会让每条边都是干净的,产物保留上一个编译器产生的字节 —— 一次覆盖在
-陈旧结果之上的绿色构建。
+声明的输入变化时，action 重跑。**命令调用的那个工具也是输入。** 少了它，
+改动规则自己的编译器，会让每条边都是干净的，产物保留上一个编译器产生的
+字节 —— 一次覆盖在陈旧结果之上的绿色构建。
 
-action 的命令跑在**构建目录**里,不是包根。`mcpp::device_sources()` 答的是包根
-相对路径,所以规则要先用 `mcpp::manifest_dir()` 拼成绝对路径再放上命令行。
+action 的命令跑在**构建目录**里，不是包根。`mcpp::device_sources()` 答的
+是包根相对路径，所以规则要先用 `mcpp::manifest_dir()` 拼成绝对路径，再放
+上命令行。
 
-### 命令自己发现输入时,声明 depfile
+### 命令自己发现输入时，声明 depfile
 
-一份 include 了别的文件的着色器或 kernel,有规则枚举不出来的输入。涉及的每个
-编译器都能产出 depfile ——`glslangValidator --depfile`、`glslc -MD -MF`、
-`slangc -depfile`,以及 clang 家族驱动的 `-MD -MF`:
+一份 include 了别的文件的着色器或 kernel，有一些规则枚举不出来的输入。
+涉及的每个编译器都能产出 depfile ——`glslangValidator --depfile`、
+`glslc -MD -MF`、`slangc -depfile`，以及 clang 家族驱动的 `-MD -MF`:
 
 ```cpp
-a.depfile = dep.c_str();          // 命令写出的一个路径
+a.depfile = dep.c_str();          // a path the command writes
 a.arg("--depfile").arg(dep.c_str());
 ```
 
@@ -202,14 +210,14 @@ depfile 不得同时被声明为 `output()`。
 
 ### 串接 action
 
-一个 action 可以消费另一个的产物。引擎只负责给它们定序与做指纹,而这就是一次
-device link 在引擎侧的全部内容:N 个 `artifact` action,其输出不进链接;再加一个
-`object` action 读取它们,产出真正进链接的对象。
+一个 action 可以消费另一个的产物。引擎只负责给它们定序与做指纹，而这就是
+一次 device link 在引擎侧的全部内容：N 个 `artifact` action，其输出不进
+链接；再加一个 `object` action 读取它们，产出真正进链接的对象。
 
 ## 规则自带的环境
 
-规则拥有它所驱动的那份包清单,因为运行编译器、读头文件、把库目录放上链接行的
-正是它的代码。
+一条规则拥有它所驱动的那份包清单，因为运行编译器、读头文件、把库目录放上
+链接行的正是它的代码。
 
 ```toml
 [target.'cfg(accelerator = "cuda")'.feature-xlings.rules-cuda]
@@ -217,120 +225,129 @@ device link 在引擎侧的全部内容:N 个 `artifact` action,其输出不进
 "xim:cuda-cudart" = "12.9.79"
 ```
 
-两道闸,下载一个字节之前两道都要开:feature 说这条规则要不要,
-`cfg(accelerator = ...)` 选择器说这次构建要不要为设备编译。不带加速器的构建两道
-都不开。
+两道闸，下载一个字节之前两道都要开：feature 说这条规则要不要，
+`cfg(accelerator = ...)` 选择器说这次构建要不要为设备编译。不带加速器的
+构建两道都不开。
 
-裸版本是项目可以覆盖的**选择**;`>=` 是项目不得低于的**要求**。见
-[23 —— 项目环境](23-the-project-environment.md) 的*一个包一个版本*。
+一个裸版本是项目可以覆盖的**选择**;`>=` 是项目不得低于的**要求**。见
+[23 —— 项目环境](23-the-project-environment.md) 的"一个包一个版本"一节。
 
-## 岛的边界是生成的,而且不由规则生成
+## 岛的边界是生成的，而且不由规则生成
 
-`mcpp.tools.island` 写出设备翻译单元包含的 `extern "C"` 头,以及 C++ 侧 import 的
-模块。它**不是**规则包,`mcpp:plugins` 里也没有任何东西调用它:调用它的是工程自己的
-`build.mcpp`,因为模块名与命名空间的形状是工程的决定而不是规则的。
+`mcpp.tools.island` 写出设备翻译单元包含的 `extern "C"` 头，以及 C++ 侧
+import 的模块。它**不是**规则包，`mcpp:plugins` 里也没有任何东西调用它：
+调用它的是工程自己的 `build.mcpp`，因为模块名与命名空间的形状是工程的
+决定，而不是规则的。
 
-规则欠它的只有一个字段。生成的头经由 `mcpp::tools::island::force_include_flags`
-到达岛,而这些旗标要落在设备编译器自己的命令行上 —— `cuda`、`hip`、`sycl` 与
-`ascendc` 的 `options::flags` —— 因为那个驱动不继承 `mcpp::cxxflag` 的任何东西,
-也因为把一个头强制灌进每个 C++ 翻译单元会让声明出现在模块接口的 `export module`
-之前,那是非良构的。
+规则欠它的只有一个字段。生成的头经由
+`mcpp::tools::island::force_include_flags` 到达岛，而这些旗标要落在设备
+编译器自己的命令行上 —— `cuda`、`hip`、`sycl` 与 `ascendc` 的
+`options::flags` —— 因为那个驱动不继承 `mcpp::cxxflag` 的任何东西，也因为
+把一个头强制灌进每个 C++ 翻译单元，会让声明出现在模块接口的
+`export module` 之前，那是非良构的。
 
-生成器本身见 [42 —— 异构硬件构建](42-heterogeneous-builds.md) 的*生成这个边界*。
+生成器本身见 [42 —— 异构硬件构建](42-heterogeneous-builds.md) 的"生成
+这个边界"一节。
 
 ## 报告构建应当知道的事
 
-### `warning` —— 成功了,并且仍然被听见
+### `warning` —— 成功了，并且仍然被听见
 
-`mcpp::warning` 是规则「干完了活、但有话要说」的通道:它不得不选择的宿主编译器、
-它回落到的载荷。除此之外,构建程序的输出只在非零退出时才被打印。
+`mcpp::warning` 是规则"干完了活、但有话要说"的通道：它不得不选择的宿主
+编译器，它回落到的载荷。除此之外，构建程序的输出只在非零退出时才被打印。
 
 ### `fact` / `floor` —— 探针通道
 
-规则测量,引擎在编译任何东西之前比较。
+规则测量，引擎在任何东西被编译之前比较。
 
 ```cpp
 mcpp::fact("cuda.driver", driver_version);
 mcpp::floor("cuda.driver", runtime_needs);
 ```
 
-引擎读到的是一个名字、一个关系和一个版本;名字是穿过它的数据。探不到答案的探针
-不陈述任何答案。
+引擎读到的是一个名字、一个关系和一个版本；名字是穿过它的数据。一个探不到
+答案的探针，不陈述任何答案。
 
 ## 找到规则自己的文件
 
 | 对象 | 获取方式 |
 |---|---|
-| 规则包自己的目录树 | `mcpp::dep_dir("<name>")` —— 按**消费者**在 `[dependencies]` 里写的那个名字 |
+| 规则包自己的目录树 | `mcpp::dep_dir("<name>")` —— 按**消费方**在 `[dependencies]` 里写的那个名字 |
 | `[xlings.workspace]` 声明的载荷 | `mcpp::xpkg_dir("<name>")` |
-| 由依赖构建出的宿主工具 | `mcpp::dep_bin("<pkg>", "<tool>")` |
+| 由某个依赖构建出的宿主工具 | `mcpp::dep_bin("<pkg>", "<tool>")` |
 
-`dep_dir` 按消费者 manifest 里的拼法作答。随模块一起发文件的规则要把该目录作为
-一个 option 暴露出来,好让用别的键声明这条边的消费者能提供它;并且在找不到时以
-一条点名「找的是什么」的消息拒绝,而不是拿一个空路径去执行命令。
+`dep_dir` 按消费方 manifest 里的拼法作答。随模块一起发文件的规则，要把该
+目录作为一个 option 暴露出来，好让用别的键声明这条边的消费方能提供它；并且
+在找不到时以一条点名"找的是什么"的消息拒绝，而不是拿一个空路径去执行
+命令。
 
-## 编写一个分发成员(mcpp 2026.9.11.1+)
+## 编写一个分发成员（mcpp 2026.9.11.1+）
 
-一个 `dist-*` 成员既不是规则也不是工具。它不编译编译单元,也不在构建程序运行期间把活
-干完:它消费**链接产物**,产出用户去安装的东西 —— 一个 `.msi`、一个 `.deb`、一个
-AppImage、一个签过名的 `.app`。机制是一条 `artifact` action 加上
-`mcpp pack --format <name>`,见
+一个 `dist-*` 成员既不是规则也不是工具。它不编译翻译单元，也不在构建程序
+运行期间把活干完：它消费**链接产物**，产出用户要去安装的东西 —— 一个
+`.msi`、一个 `.deb`、一个 AppImage、一个签过名的 `.app`。机制是一条
+`artifact` action 加上 `mcpp pack --format <name>`，见
 [30 —— 产出可分发物](30-build-mcpp.md#产出可分发物pack_format-与-stage_dir20269111)。
 
-本章其余内容原样适用。有六条在这里绑得更紧,每一条都是这个类别会犯、而规则不会犯的
-错。
-
-**无条件声明,有条件提交。** `provides_pack_format` 是引擎用来回答「这张图提供哪些
-格式」的东西,而回答发生在一次「什么格式都没要」的构建上。一个只在被问到时才声明的
-成员,对它的作者照常工作 —— 作者永远传自己那个格式 —— 而对其他所有人,这个集合变成
-不可知的。
-
-**同时提供 plan 与 submit。** 可分发物是交到用户手上之前的最后一环,因此它是整个构建
-里最可能需要项目自己改一笔的部分:换一个压缩等级、多带一个文件、加第二个签名。
-`generate_all(opt)` 恰好等于 `submit(plan_all(opt))`,正是让这样一笔改动不至于变成把
-成员重新实现一遍的东西。
-
-**点名输入,不要去 harvest 一个目录。** 一个解析成空的路径是无声的,而一个缺失的具名
-输入是错误。实测:一条 WiX action 绑定一个目录并 harvest 它,当那个路径在 Windows 上
-解析成空时,产出了一个**有效的、空的、52 KB 的安装包,并且没有任何诊断**。
-`${mcpp.target_file:<name>}` 就是这个机制 —— 构建程序既不知道三元组也不知道指纹,而一个
-不存在的 target 名会被拒绝,而不是展开成一个空路径。
-
-**在成功路径上,为自己的输出断言一条下界。** 只要成员能判断自己的结果是空的或不合理
-的,它就必须经 `mcpp::warning` 说出来,因为成功构建的 stderr 会被丢弃。这与上一段实测到
-的是同一个失败,只是被拦在了后一层。
-
-**在工具会被查找的那个位置声明它。** `xpkg_dir` 从 `MCPP_XPKG_*_DIR` 回答,而这些是
-mcpp 为**正在被构建的那个包**设置的。一个依赖的声明会把载荷装上,却不会让它对消费者的
-构建程序可见,所以运行载荷工具的成员要自己声明它 —— 并且在查找返回空时把这件事说出来,
-而不是指向一份读者并不拥有的 manifest。
-
-host module 是这条规则的例外,它的声明在它被编入的**每一个**构建程序里都可见
-(`tests/e2e/622`),因为 host module 自己的代码作为那些构建程序各自的一部分运行,
-而不是作为一个只经由依赖图才能看到的依赖。这正是一个成员要在自己身上声明自己
-的载荷、而拉入这个成员的项目从不重复这条声明的原因。dist 成员的载荷因此也归属
-于该成员——当工具服务于某一个 target 时归到 target 轴上,与任何其它按目标区分
-的声明一样:
+本章其余内容原样适用。有六条在这里绑得更紧，每一条都是这个类别会犯、而
+规则不会犯的错。
+
+**无条件声明，有条件提交。** `provides_pack_format` 是引擎用来回答"这张图
+提供哪些格式"的东西，而这个回答要在一次"什么格式都没要"的构建上给出。一个
+只在被问到时才声明的成员，对它的作者照常工作 —— 作者永远传自己那个格式
+——而对其他所有人，这个集合变成不可知的。
+
+**同时提供 plan 与 submit。** 可分发物是交到用户手上之前的最后一环，因此
+它是整个构建里最可能需要项目自己改一笔的部分：换一个压缩等级、多带一个
+文件、加第二个签名。`generate_all(opt)` 恰好等于 `submit(plan_all(opt))`,
+正是让这样一笔改动，不至于变成把成员重新实现一遍的东西。
+
+**点名输入，不要去 harvest 一个目录。** 一个解析成空的路径是无声的，而一个
+缺失的具名输入是错误。实测：一条 WiX action 绑定一个目录并 harvest 它，
+当那个路径在 Windows 上解析成空时，产出了一个**有效的、空的、52 KB 的
+安装包，并且没有任何诊断**。`${mcpp.target_file:<name>}` 就是这个机制 ——
+构建程序既不知道三元组也不知道指纹，而一个不存在的 target 名会被拒绝，而
+不是展开成一个空路径。
+
+**在成功路径上，为自己的输出断言一条下界。** 只要成员能判断自己的结果是
+空的或不合理的，它就必须经 `mcpp::warning` 说出来，因为成功构建的 stderr
+会被丢弃。这与上一段实测到的是同一个失败，只是被拦在了后一层。
+
+**在工具会被查找的那个位置声明它。** `xpkg_dir` 从 `MCPP_XPKG_*_DIR`
+回答，而这些是 mcpp 为**正在被构建的那个包**设置的。一个依赖的声明会把
+载荷装上，却不会让它对消费方的构建程序可见，所以运行载荷工具的成员要自己
+声明它 —— 并且在查找返回空时把这件事说出来，而不是指向一份读者并不拥有的
+manifest。
+
+host module 是这条规则的例外，它的声明在它被编入的**每一个**构建程序里
+都可见（`tests/e2e/622`），因为 host module 自己的代码，是作为那些构建
+程序各自的一部分运行的，而不是作为一个只经由依赖图才能看到的依赖。这正是
+一个成员要在自己身上声明自己的载荷、而拉入这个成员的项目从不重复这条声明
+的原因。dist 成员的载荷因此也归属于该成员 —— 当工具服务于某一个 target
+时归到 target 轴上，与其他任何按目标区分的声明一样：
 
 ```toml
 [target.'cfg(env = "android")'.feature-xlings.dist-apk]
 "xim:android-build-tools" = ""
 ```
 
-**构建不许碰网络,而被包起来的工具可能会碰。** 在 `appimagetool` 1.9.1 上实测:除非用
-`--runtime-file` 指定一份本地副本,它每次被调用都会从一个 GitHub release 下载它的
-type-2 runtime 存根。包装这类工具的成员必须从自己声明的载荷里把这个文件供上。安装期
-是下载合法的时候;构建期不是,而一个会去取东西的构建既不可复现也不能离线用。
+**构建不许碰网络，而被包起来的工具可能会碰。** 在 `appimagetool` 1.9.1 上
+实测：除非用 `--runtime-file` 指定一份本地副本，它每次被调用都会从一个
+GitHub release 下载它的 type-2 runtime 存根。包装这类工具的成员必须从
+自己声明的载荷里把这个文件供上。安装期是下载合法的时候；构建期不是，而
+一个会去取东西的构建既不可复现，也不能离线使用。
 
-**一个 `(name, version)` 只指一份载荷。** 包装签名或打包工具的成员继承了那个工具的兼容
-面,所以与被包装的工具同步版本是正当的,而且陈述了一件真事。
+**一个 `(name, version)` 只指一份载荷。** 包装签名或打包工具的成员，继承
+了那个工具的兼容面，所以与被包装的工具同步版本是正当的，而且陈述了一件
+真事。
 
 ## 当前边界
 
 - 规则包自己 `[features] default` 里的规则 feature 不隐含 `host-module`。
-  `mcpp:plugins` 声明 `default = []`;规则默认开启的规则包会被拒绝,消息点名
-  该模块与需要补的键。
-- `mcpp emit xpkg` 把 `manifest = "mcpp.toml"` 写进 `mcpp` 段,而
-  `mcpp xpkg parse` 把该键报为未知并以 1 退出。`mcpp-index` 里没有任何描述符使用
-  它(218 个里 0 个);自带 `mcpp.toml` 的包整个省略 `mcpp` 字段。见
-  [09 —— 按场景选命令](09-commands-by-scenario.md)的*当前边界*。
+  `mcpp:plugins` 声明 `default = []`；一个规则默认开启的规则包会被拒绝，
+  消息点名该模块与需要补的键。
+- `mcpp emit xpkg` 把 `manifest = "mcpp.toml"` 写进 `mcpp` 段，而
+  `mcpp xpkg parse` 把该键报为未知，并以 1 退出。`mcpp-index` 里没有任何
+  描述符使用它（218 个里 0 个）；自带 `mcpp.toml` 的包整个省略 `mcpp`
+  字段。见 [09 —— 按场景选命令](09-commands-by-scenario.md) 的"当前
+  边界"一节。
diff --git a/docs/zh/32-authoring-a-payload.md b/docs/zh/32-authoring-a-payload.md
index 02b7f32eb..6cd788fd6 100644
--- a/docs/zh/32-authoring-a-payload.md
+++ b/docs/zh/32-authoring-a-payload.md
@@ -1,29 +1,31 @@
 # 32 —— 编写一个载荷
 
-**读者:**要把一个工具或一份预编译库打包出来,好让 mcpp 工程声明它、由 mcpp 安装
-它的人。
+**读者：** 要把一个工具或一份预编译库打包出来，好让 mcpp 工程声明它、
+由 mcpp 安装它的人。
 
-**本章回答的那一个问题:**一个 `xim:` 载荷由什么构成,以及它的描述符必须说清什么,
-消费者才能点名它并得到一个能用的程序。
+**本章回答的那一个问题：** 一个 `xim:` 载荷由什么构成，以及它的描述符
+必须说清什么，消费者才能点名它并得到一个能用的程序。
 
-**不在这里:**发布供他人 `import` 的**源码包**,那是
-[11 —— 发布一个库](11-publishing-a-library.md);让**宿主**的库能被产物够到,那是
-[33 —— 编写运行时适配包](33-authoring-an-adapter.md);以及消费一个载荷,那是
-[23 —— 项目环境](23-the-project-environment.md)。
+**不在这里：** 发布供他人 `import` 的**源码包**，那是
+[11 —— 发布一个库](11-publishing-a-library.md)；让**宿主**的库能被产物
+够到，那是 [33 —— 编写运行时适配包](33-authoring-an-adapter.md)；以及
+消费一个载荷，那是 [23 —— 项目环境](23-the-project-environment.md)。
 
-在此之前:[31 —— 编写规则包](31-authoring-a-rule-package.md) —— 规则声明它所驱动的
-载荷。在此之后:[33 —— 编写运行时适配包](33-authoring-an-adapter.md)。
+在此之前：[31 —— 编写规则包](31-authoring-a-rule-package.md)——规则声明
+它所驱动的载荷。在此之后：
+[33 —— 编写运行时适配包](33-authoring-an-adapter.md)。
 
 ## 载荷的定义
 
-一切由 mcpp 安装而不编译的东西:编译器、着色器编译器、设备工具包、模拟器、探针
-驱动、预编译的 C 库。工程在 `[xlings.workspace]` 里点名它,或者规则包在
-`[feature-xlings.<f>]` 里点名它,mcpp 在构建之前把它供给到位。
+一切由 mcpp 安装而不编译的东西：编译器、着色器编译器、设备工具包、
+模拟器、探针驱动、预编译的 C 库。工程在 `[xlings.workspace]` 中点名它，
+或者规则包在 `[feature-xlings.<f>]` 中点名它，mcpp 会在构建运行之前把它
+供给到位。
 
-一个载荷在 `xim-pkgindex` 里是一个 Lua 文件:一个描述它的 `package` 表,加两个把
-它放好并登记的函数。
+一个载荷在 `xim-pkgindex` 中是一个 Lua 文件：一个描述它的 `package`
+表，加两个把它放好并登记的函数。
 
-能用的最短形态:
+能用的最短形态：
 
 ```lua
 package = {
@@ -61,42 +63,47 @@ function config()
 end
 ```
 
-`install()` 把解开的目录树放到 mcpp 会去找的位置;`config()` 登记这个载荷提供什么。
-本章其余内容,都是这两个函数在多做一些事。
+`install()` 把解开的目录树放到 mcpp 会去找的位置；`config()` 登记这个
+载荷提供什么。本章其余内容，都是这两个函数在多做一些事。
 
-### 安装钩子收到的环境(mcpp 2026.9.12.2+)
+### 安装钩子收到的环境（mcpp 2026.9.12.2+）
 
-mcpp 安装工程所依赖的包时,该包的 `install()` 在环境中收到本次构建的目标,变量名与规则同构建程序一致
-([build.mcpp](30-build-mcpp.md)):每个变量都显式写出,没有取值时为空,因此钩子不会读到从启动 mcpp 的
-进程继承来的值。
+mcpp 安装工程所依赖的包时，该包的 `install()` 会在环境中收到本次构建的
+目标，采用的变量名与遵循的规则与构建程序一致
+（[build.mcpp](30-build-mcpp.md)）：每个变量都存在，没有取值时为空，
+因此一个钩子绝不会读到从启动 mcpp 的那个进程继承来的值。
 
-| 变量 | 依赖安装时的取值 |
+| 变量 | 依赖安装期间的取值 |
 |---|---|
-| `MCPP_TARGET` | 本次构建所请求的目标三元组;原生构建时为宿主三元组 |
+| `MCPP_TARGET` | 本次构建所请求的目标三元组；原生构建时为宿主三元组 |
 | `MCPP_TARGET_OS`、`MCPP_TARGET_ARCH`、`MCPP_TARGET_ENV` | 该三元组的各段 |
 | `MCPP_COMPILER`、`MCPP_CXX_STDLIB` | 空 |
 
-工具链的取值为空,因为工具链在依赖图之后才解析:依赖图中的包可能提供目标侧的层,所以依赖安装时编译器与
-标准库都尚未确定,而猜测一个取值的钩子可能构建出错误的变体。在 Windows 上空变量即不存在的变量,
-`os.getenv` 对它返回 `nil`。工具链载荷的钩子不会收到这些变量。
+工具链相关的取值为空，因为工具链在依赖图之后才解析：图中的某个包可能
+供给目标侧的层，所以依赖安装时编译器与标准库都尚未确定，而一个猜测了
+取值的钩子可能构建出错误的变体。在 Windows 上，空变量就是不存在的
+变量，`os.getenv` 对它返回 `nil`。工具链载荷自己的钩子不会收到这些
+变量。
 
-钩子可以用目标来拒绝或给出诊断,但不得把某种变体构建进名称未体现该变体的存储目录:存储目录按包名与版本
-区分,否则第一个消费者就会替之后所有消费者决定变体。针对某一个 C++ 标准库编译的包应以
-`requires = ["mcpp:c++-abi=libstdc++"]` 陈述这一点,该需求在工具链解析之后检查
-([22 —— 目标侧](22-target-side.md))。
+钩子可以用目标来拒绝或给出诊断，但不得把某种变体构建进一个名称未体现
+该变体的存储目录：存储目录按包名与版本区分，否则第一个消费者就会替
+之后所有消费者决定变体。针对某一个 C++ 标准库编译的包应以
+`requires = ["mcpp:c++-abi=libstdc++"]` 陈述这一点，该需求会在工具链
+解析之后被检查（[22 —— 目标侧](22-target-side.md)）。
 
 ## 描述符必须做对的四件事
 
-**一个版本,两个 URL。** 每个版本都带 `GLOBAL` 与 `CN` 两个 URL 和一个 `sha256`。
-两个镜像服务同一份字节;在任一镜像后面的消费者解析到同一个哈希,而只写一个 URL 的
-描述符对半个生态不可用。
+**一个版本，两个 URL。** 每个版本都带 `GLOBAL` 与 `CN` 两个 URL，以及
+一个 `sha256`。两个镜像服务的是同一份字节；处在任一镜像之后的消费者都
+解析到同一个哈希，而只写一个 URL 的描述符对半个生态是不可用的。
 
-**`latest` 是一个引用,不是一个版本。** `["latest"] = { ref = "15.1.0" }`。它是
-消费者不点名版本时拿到的东西,移动它是一个刻意的动作 —— 钉在 `15.1.0` 的消费者
-不受影响。
+**`latest` 是一个引用，不是一个版本。** `["latest"] = { ref = "15.1.0" }`。
+它是消费者不点名版本时拿到的东西，移动它是一个刻意的动作——钉在
+`15.1.0` 的消费者不受影响。
 
-**`archs` 与平台表是解析要读的东西。** 只为 `linux` 与 `x86_64` 发布的载荷就这样
-声明,于是别的平台上的消费者会被**点名拒绝**,而不是拿到一个跑不起来的东西。
+**`archs` 与平台表是解析要读的东西。** 只为 `linux` 与 `x86_64` 发布的
+载荷就这样声明，于是别的平台上的消费者会被**点名拒绝**，而不是拿到一个
+跑不起来的东西。
 
 **依赖是带下界的 `xim:` 地址。**
 
@@ -108,9 +115,10 @@ deps = { "xim:gcc-runtime@>=15", "xim:glibc@>=2.38" },
 
 只会解包的载荷不可用。三条声明把一个目录变成构建能消费的东西。
 
-**路径上的一个程序。** `xvm.add(package.name)` 登记该载荷的 `bin/`,于是 mcpp 能
-按裸名找到这个程序。规则包应当**写程序名,不写路径** —— mcpp 会搜索图中每个被声明
-载荷的 `bin/`,然后才是 `PATH`,并且能准确报出它搜过哪些目录。
+**路径上的一个程序。** `xvm.add(package.name)` 登记该载荷的 `bin/`，于是
+mcpp 能按裸名找到这个程序。规则包应当**写程序名，不写路径**——mcpp 会
+搜索图中每一个被声明载荷的 `bin/`，然后才是 `PATH`，并且能准确报出它
+搜过哪些目录。
 
 **消费者要链接或加载的库。**
 
@@ -120,17 +128,18 @@ exports = {
 },
 ```
 
-`elfpatch` 从每个依赖里读这一项,写进消费者的 `RPATH` —— 这正是一叠载荷不需要任何人
-设 `LD_LIBRARY_PATH` 就能解析的原因。
+`elfpatch` 从每个依赖里读这一项，写进消费者的 `RPATH`——这正是一叠载荷
+不需要任何人设置 `LD_LIBRARY_PATH` 就能解析的原因。
 
-**头文件,好让这个环境里的编译器能对着它构建。** `sysroot.declare_libs(...)` 与
-头文件声明把载荷放进 SubOS 的 sysroot 视图。**是声明而不是复制** —— xlings 会随包
-一起移除它们,而一份复制会比它的主人活得更久。
+**头文件，好让这个环境里的编译器能对着它构建。**
+`sysroot.declare_libs(...)` 与头文件声明把载荷放进 SubOS 的 sysroot
+视图。**是声明而不是复制**——xlings 会随包一起移除它们，而一份复制会
+比它的主人活得更久。
 
-## 从检出目录解析配方(2026.9.14.2+)
+## 从检出目录解析配方（2026.9.14.2+）
 
-未合入分支上的配方,在发布之前可由消费者通过 mcpp home 的 `config.toml` 中的索引覆盖
-来解析:
+未合入分支上的一份配方，在发布之前可由消费者通过 mcpp home 的
+`config.toml` 中的索引覆盖来解析：
 
 ```toml
 # $MCPP_HOME/config.toml
@@ -138,32 +147,34 @@ exports = {
 url = "/work/xim-pkgindex"      # a checkout of the branch
 ```
 
-下一条命令把该条目写入 registry 的 `.xlings.json` 并打印一行;此后索引跟随该检出
-目录,包括第一次构建之后才提交的内容:
+下一条命令会把该条目写入 registry 的 `.xlings.json` 并打印一行；此后
+索引跟随该检出目录，包括第一次构建之后才提交的内容：
 
 ```
        Index xim -> /work/xim-pkgindex ([index.repos.xim] in config.toml)
 ```
 
-从该索引安装时,`Provisioning` 旁边会重复这一行。删去这张表后,下一条命令恢复
-registry 原先的条目,除非该条目在 mcpp 写入之后被改动过。以上对已经运行过的 home
-同样成立;2026.9.14.2 之前的 mcpp 只在创建 home 时应用这张表。
+从该索引安装时，`Provisioning` 旁边会重复这一行。删去这张表后，下一条
+命令会恢复 registry 原先的条目，除非该条目在 mcpp 写入之后被改动过。
+以上对已经运行过的 home 同样成立；2026.9.14.2 之前的 mcpp 只在创建
+home 时应用这张表。
 
-## 档位:需要载荷的命令
+## 档位：需要载荷的命令
 
 ```toml
 "xim:qemu-arm" = { version = "9.2.4-1", when = "run" }
 ```
 
-`when` 是选中该载荷的那个 feature 之外的**第二道独立闸门**。feature 说**谁**需要这个
-工具;档位说**什么时候**。模拟器是运行时需要、编译时不需要的,所以一个只构建固件、
-从不烧录的 CI 任务**一个字节都不下载**。
+`when` 是选中该载荷的那个 feature 之外的**第二道独立闸门**。feature
+说的是**谁**需要这个工具；档位说的是**什么时候**。模拟器是运行时需要、
+编译时不需要的，所以一个只构建固件、从不烧录的 CI 任务**一个字节都不
+下载**。
 
 ## 当前边界
 
-- 载荷发布到 `xim-pkgindex` —— 那是一个独立仓库,有它自己的评审;mcpp 里没有任何
-  东西发布载荷。
-- `latest` 与「表里版本号最大的那个」是两个不同的问题,想要最新已发布版本的消费者
-  应当点名 `latest`。
-- 载荷自己的 CI 无法核验消费者能否解析到它:那是「对着已发布描述符做沙箱核验」的
-  用途,也是唯一核验**已发布字节**而不是工作树的东西。
+- 载荷发布到 `xim-pkgindex`——那是一个独立仓库，有它自己的评审；mcpp
+  本身没有任何东西负责发布载荷。
+- `latest` 与「表里版本号最大的那个」是两个不同的问题，想要最新已发布
+  版本的消费者应当点名 `latest`。
+- 载荷自己的 CI 无法核验消费者能否解析到它：那正是「对着已发布描述符
+  做沙箱核验」的用途，也是唯一核验**已发布字节**而不是工作树的东西。
diff --git a/docs/zh/33-authoring-an-adapter.md b/docs/zh/33-authoring-an-adapter.md
index 7e0c8670d..8ad9be164 100644
--- a/docs/zh/33-authoring-an-adapter.md
+++ b/docs/zh/33-authoring-an-adapter.md
@@ -1,77 +1,79 @@
 # 33 —— 编写运行时适配包
 
-**读者:**要让**宿主**提供的某个库能被 mcpp 产物在 Linux 上够到的人 —— 图形驱动、
-Vulkan ICD、某个专有运行时。
+**读者：**要把**宿主**上已经装好的某个库，接到一个 mcpp 在 Linux 上构建出的产物
+手里的人 —— 图形驱动、Vulkan ICD、某个专有运行时。
 
-**本章回答的那一个问题:**为什么产物看不见一个明明装在机器上的库,以及一个包要
-声明什么才能修好它。
+**本章回答的那一个问题：**产物为什么看不见一个明明装在机器上的库，以及一个包
+要声明什么才能修好它。
 
-**不在这里:**打包一个由 mcpp 安装的库,那是
-[32 —— 编写一个载荷](32-authoring-a-payload.md) —— 只要那个库**可以**被再分发,它
-就是正确答案;以及运行时契约的字段,那是
-[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) 的 `[runtime]`。
+**不在这里：**打包一个由 mcpp 安装的库，那是
+[32 —— 编写一个载荷](32-authoring-a-payload.md)；只要那个库**可以**被再分发，
+那一章才是正确答案。运行时契约本身的字段是
+[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) 的 `[runtime]` 一节。
 
-在此之前:[32 —— 编写一个载荷](32-authoring-a-payload.md)。在此之后:
-[34 —— 编写板级支持包](34-authoring-a-bsp.md)。
+在此之前：[32 —— 编写一个载荷](32-authoring-a-payload.md)。
+在此之后：[34 —— 编写板级支持包](34-authoring-a-bsp.md)。
 
-## 它为之存在的那次失败
+## 这一机制要解决的那次失败
 
-库装好了。加载器也找到了它的 manifest。`dlopen` 仍然失败:
+库已经装好，加载器也找到了它的 manifest，`dlopen` 依然失败：
 
 ```
 DRIVER: Found the following files: /usr/share/vulkan/icd.d/lvp_icd.json …
 ERROR:  libvulkan_lvp.so: cannot open shared object file
 ```
 
-库就在 `/usr/lib/x86_64-linux-gnu`。够不到它们的是**进程**:mcpp 构建出的二进制跑在
-mcpp 自己的 glibc 之下,带着它自己的搜索路径,
+库就摆在 `/usr/lib/x86_64-linux-gnu` 里。够不到它的是**进程**本身：mcpp 构建出的
+二进制运行在 mcpp 自己的 glibc 之下，带着自己的一条搜索路径，
 
 ```
 interp: …/xpkgs/xim-x-glibc/2.39/lib64/ld-linux-x86-64.so.2
 rpath : …/xim-x-glibc/2.39/lib64:…/xim-x-gcc/…/lib64:$ORIGIN
 ```
 
-于是从那个进程内部发起的、按裸 soname 的 `dlopen`,**根本不会去搜索宿主的库路径**。
-没有任何东西坏掉;产物只是不往那里看 —— 而这正是 mcpp 构建可复现的那条性质本身。
+于是这个进程内部发起的、按裸 soname 的 `dlopen`，根本不会去搜宿主的库路径。没有
+任何东西坏掉；产物只是没往那里看 —— 而这一点，正是 mcpp 构建得以可复现的那条
+性质本身。
 
 ## 适配包的定义
 
-**一个符号链接农场,加上让它可被够到的那点元数据。** 不内嵌任何东西、不再分发任何
-东西,包里没有上游的字节。`runtime.library_dirs` 把一个包自有的符号链接目录放上产物
-的运行期搜索路径,于是整条链解析得开。
+**一座符号链接农场，加上让它可被够到的那点元数据。** 不内嵌任何字节，不再分发
+任何字节，包里没有一个上游字节。`runtime.library_dirs` 把包自己拥有的一个符号
+链接目录放上产物的运行期搜索路径，链条就此解析得通。
 
-工程把适配包当作一个普通依赖声明,除此之外什么都不做。
+工程把适配包当一个普通依赖声明即可，不必再做别的事。
 
-## 驱动本身不能成为一个包的原因
+## 驱动本身不能做成一个包的原因
 
-专有驱动的用户态与**内核模块处于 ABI 锁步**,而它的许可证禁止再分发。这两条都不是
-靠努力能解决的打包问题,所以这类驱动被建模为**宿主能力** —— 机器要么有、要么没有
-—— 而适配包是产物够到它的方式。
+专有驱动的用户态与**内核模块处于 ABI 锁步**，而它的许可证又禁止再分发。这两条
+都不是靠打包上多花力气能解决的问题，所以这类驱动被建模为一种**宿主能力**
+—— 机器要么有，要么没有 —— 适配包是产物够到它的方式。
 
-**开源**驱动是另一种情形,取另一个答案:它就是一个载荷(CPU 上是
-`xim:mesa-lavapipe`,AMD 硬件上是 `xim:mesa`),而用着它的机器完全不需要这个农场。
-自 2026.09.05 起,当某个已发布载荷提供了同名库、且它的符号集合覆盖宿主那份时,适配包
-优先取载荷 —— 于是农场实际记录下来的,是专有用户态与打包欠账。
+**开源**驱动是另一种情形，答案也不同：它本身就是一个载荷（CPU 上是
+`xim:mesa-lavapipe`，AMD 硬件上是 `xim:mesa`），用着它的机器完全不需要这座
+农场。自 2026.09.05 起，当某个已发布载荷提供了同名库、且它的符号集合覆盖宿主
+那一份时，适配包会优先取载荷。农场因此实际记录下来的，是专有用户态与尚未打包
+完的部分。
 
-## 适配包最容易做错的三件事
+## 适配包最容易出的三个错
 
-**模式列表必须覆盖传递依赖。** 整条链都要经由同一个目录解析。Mesa 的软件光栅器会
-拉进 LLVM;NVIDIA 驱动会拉进它自己那一族。只列 ICD 一个,结果是同一句
-`cannot open shared object file` 往下挪一层。
+**模式列表必须覆盖传递依赖。** 整条链都要经同一个目录解析开。Mesa 的软件光栅器
+会拉进 LLVM，NVIDIA 驱动会拉进它自己那一族。只列出 ICD 这一个，结果是同一句
+`cannot open shared object file` 在下一层重新出现。
 
-**`libstdc++` 应当在列表里,这不是疏忽。** mcpp **静态**链接 libstdc++ —— 它不出现在
-构建产物的 `NEEDED` 里 —— 所以一个被 `dlopen` 的 C++ 驱动,除非宿主那份在这里被提供,
-否则没有任何东西可供它解析。
+**`libstdc++` 属于这份列表，这不是疏漏。** mcpp **静态**链接 libstdc++ —— 它不
+出现在构建产物的 `NEEDED` 里 —— 因此一个被 `dlopen` 出来的 C++ 驱动，除非宿主
+那一份在这里被提供，否则没有任何东西供它解析。
 
-**不得有任何一项是必需的。** 一台完全没有这类驱动的机器是**合法配置**,而这个生态的
-每一台 CI runner 都是这样的机器。此时农场为空,程序报告它实际找到了什么。一个在宿主库
-缺失时报错的适配包,会把一种受支持的配置变成构建失败。
+**不得把任何一项当作必需。** 一台完全没有这类驱动的机器是一种合法配置，这个
+生态里每一台 CI runner 都是这样的机器。此时农场为空，程序如实报告它实际找到了
+什么。一个在宿主库缺失时报错的适配包，会把一种受支持的配置变成一次构建失败。
 
-## mcpp 对这个面的检查与报告
+## mcpp 在这个面上做的检查
 
-适配包发布的库是被 `dlopen` 找到的,没有任何链接边指向它们,因此运行期闭包检查
-—— 它从产物出发沿 `DT_NEEDED` 走 —— 按构造到不了这些库。mcpp 在链接之后单独走一遍
-这个面,并把结果作为警告报出:
+适配包发布的库是经 `dlopen` 找到的，没有任何链接边指向它们，因此运行期闭包检查
+—— 它沿产物的 `DT_NEEDED` 走 —— 按构造到不了这些库。mcpp 在链接之后单独走一遍
+这个面，把结果作为警告报出：
 
 ```
 warning: 1 of 13 libraries a dependency published for dlopen cannot be loaded
@@ -79,18 +81,19 @@ on this artifact's search path:
     libur_adapter_cuda.so.0 needs libnvidia-ml.so.1
 ```
 
-三种读数被区分开,只有一种被报告:
+三种读数被区分开来，只有一种会被报告：
 
-| 该库需要的 SONAME | 含义 | 是否报告 |
+| 该库所需的 SONAME | 含义 | 是否报告 |
 |---|---|---|
 | 在产物的搜索路径上 | 无话可说 | 否 |
-| 在农场里存在,但链接悬空 | 这台机器没有这个驱动 | 否 |
-| 到处都不存在 | 适配包没有携带它 | 是 |
+| 存在于农场里，但链接悬空 | 这台机器没有这个驱动 | 否 |
+| 到处都找不到 | 适配包没有携带它 | 是 |
 
-中间那一行正是这条检查是警告而不是错误的原因:悬空链接是「宿主驱动尚未安装」的
-既定形状,一条在那里失败的检查会把受支持的配置变成构建失败。
+中间那一行正是这项检查只做警告、不做错误的原因：悬空链接是「宿主驱动尚未安装」
+这一状态的既定形状，一条在那里也失败的检查，会把受支持的配置变成构建失败。
 
-完整结果(含两个分母)发布在 `resolution.json` 的 `runtime.dlopen_surface`:
+完整结果 —— 连同两个分母 —— 发布在 `resolution.json` 的 `runtime.dlopen_surface`
+里：
 
 ```json
 { "members": 13, "walked": 13,
@@ -98,28 +101,29 @@ on this artifact's search path:
                   "soname": "libnvidia-ml.so.1", "kind": "missing" } ] }
 ```
 
-即使没有任何发现,`members` 与 `walked` 也会被发布。一个构建失败的农场枚举出零个成员,
-否则「没有发现」与「什么都没检查」就读起来一模一样。
+即使没有任何发现，`members` 与 `walked` 也照常发布。一座构建失败的农场枚举不出
+任何成员，否则「没有发现」与「什么都没检查」这两件事读起来会一模一样。
 
-这条检查不适用的构建,发布同一条记录,但只带 `reason`、不带读数:
+不适用这项检查的构建，发布同一条记录，只带 `reason`，不带读数：
 
 ```json
 { "members": 0, "walked": 0, "findings": [],
   "reason": "this build produces no program; the surface is reached from a process and belongs to whatever runs" }
 ```
 
-四种理由是:运行时绑定非 hermetic;设置了 `allow_host_libs`;本次构建不产出程序;本次构建
-没有链接产物。目标不是 Linux 时不发布任何记录 —— 这条记录是 ELF 形状的,对一个本次构建
-根本不产出的格式给出「空答案」本身就是另一种混淆。
+四种理由分别是：运行时绑定不是 hermetic 的；设置了 `allow_host_libs`；本次构建
+不产出程序；本次构建没有产出链接后的产物。目标不是 Linux 时不发布任何记录 ——
+这条记录本身是 ELF 形状的，对一个本次构建根本不会产出的格式给出「空答案」，
+只会制造另一种混淆。
 
-读这条记录的测试应当把 `reason` 当作「没有测到」而不是「测了,结果干净」—— 「没适用」与
-「没检查过」正是这条记录存在的意义所在。
+读这条记录的测试应当把 `reason` 当作「没有测到」处理，而不是「测过、结果干净」
+—— 「不适用」与「从未跑过」正是这条记录存在的意义所要分开的那两件事。
 
 ## 当前边界
 
-- **按构造只适用于 Linux。** macOS 的 dyld 与 Windows 的 PE 加载器没有对应的这一层,
-  因此面向它们的工程不声明适配包。
-- 适配包无法让一台机器上不存在的驱动工作起来。它只移除一个障碍 —— 可达性 —— 其余的
-  按「缺席」如实报告。
-- 农场的内容在适配包被安装时决定。之后才装上的驱动,要到适配包被重新安装时才会被
-  纳入。
+- **按构造只适用于 Linux。** macOS 的 dyld 与 Windows 的 PE 加载器没有对应的这一
+  层，因此面向它们的工程不声明适配包。
+- 适配包无法让一台机器上原本不存在的驱动工作起来。它只移除一个障碍 —— 可达性
+  —— 其余的按「缺席」如实报告。
+- 农场的内容在适配包被安装的那一刻就确定了。之后才装上的驱动，要等到适配包被
+  重新安装才会被纳入。
diff --git a/docs/zh/34-authoring-a-bsp.md b/docs/zh/34-authoring-a-bsp.md
index 5a76198de..762c98ce2 100644
--- a/docs/zh/34-authoring-a-bsp.md
+++ b/docs/zh/34-authoring-a-bsp.md
@@ -1,39 +1,40 @@
 # 34 —— 编写板级支持包
 
-**读者:**要把一块板子支起来,好让工程能用 `mcpp build` 面向它、用 `mcpp run`
+**读者：**要把一块板子支起来，好让工程能用 `mcpp build` 面向它、用 `mcpp run`
 抵达它的人。
 
-**本章回答的那一个问题:**一个板级支持包供给什么,以及一个包怎样同时服务模拟器与
+**本章回答的那一个问题：**一个板级支持包供给什么，以及一个包怎样同时服务模拟器与
 真实板子。
 
-**不在这里:**使用一个 BSP,那是
-[40 —— 裸机与 freestanding 目标](40-baremetal.md);消费者看到的 runner 机制,那是
-[41 —— 抵达一台设备](41-devices.md);以及把模拟器或探针驱动本身打包,那是
+**不在这里：**使用一个 BSP，那是
+[40 —— 裸机与 freestanding 目标](40-baremetal.md)；消费者看到的 runner 机制，
+那是 [41 —— 抵达一台设备](41-devices.md)；把模拟器或探针驱动本身打包，那是
 [32 —— 编写一个载荷](32-authoring-a-payload.md)。
 
-在此之前:[33 —— 编写运行时适配包](33-authoring-an-adapter.md)。
+在此之前：[33 —— 编写运行时适配包](33-authoring-an-adapter.md)。
 
 ## BSP 的供给内容
 
-freestanding 目标没有操作系统,所以 hosted 程序白得的一切都必须来自某处。BSP 就是
-那个某处,它供给**整个目标世界**:
+freestanding 目标没有操作系统，所以 hosted 程序白得的一切都必须来自某处。BSP
+就是那个某处，它供给**整个目标世界**：
 
 | | 内容 |
 |---|---|
-| 内存布局 | 一份链接脚本 —— 程序既推导不出、也猜不到的那一个事实 |
-| 启动代码 | `main` 之前跑的东西,以及向量表 |
+| 内存布局 | 一份链接脚本——程序既推导不出、也猜不到的那一个事实 |
+| 启动代码 | `main` 之前跑的东西，以及向量表 |
 | 一个导出模块 | 程序 import 它来够到板子的控制台与外设 |
 | **runner** | `mcpp run` 与 `mcpp test` 究竟怎样抵达这块板子 |
 
-最容易被漏掉的是 runner;少了它,每个消费者都要自己写一遍模拟器的调用。
+runner 是最容易被漏掉的一项，少了它，每个消费者都要自己写一遍模拟器的调用。
 
-## 一个包,两种环境
+## 一个包，两种环境
 
-经模拟器抵达的板子,与经调试探针抵达的同一块板子,**差别只在 runner 的 argv,别处
-一个字都不差**。链接脚本、启动代码、内存布局与导出模块是同一块板子。为了改四个字符串
-而发两个包,会把这一切复制一遍,并让两份副本各自漂移。
+经模拟器抵达的板子，与经调试探针抵达的同一块板子，**差别只在 runner 的
+argv，别处一个字都不差**。链接脚本、启动代码、内存布局与导出模块是同一块板子。
+为了让四个字符串各不相同而发布两个包，会把这一整套复制一遍，并让两份副本
+各自漂移。
 
-所以环境是一个 **feature**:
+所以环境是一个 **feature**：
 
 ```toml
 [features]
@@ -48,22 +49,22 @@ hardware = {}
 "xim:probe-rs" = { version = "", when = "run" }
 ```
 
-**`emulator` 是默认,而这是一个关于「谁在读」的决定。** 刚接触这个包的人手边没有
-板子;手边有板子的人有理由把它说出来。一个要求硬件的默认值,会让所有还没买东西的人
-的第一条命令就失败。
+**`emulator` 是默认，而这是一个关于「谁在读」的决定。** 刚接触这个包的人手边
+没有板子；手边有板子的人有理由把这一点说出来。要求硬件的默认值，会让所有还
+没买任何东西的人第一条命令就失败。
 
-两张表刻意对称:哪种环境都不是引擎眼里的「正常」,而消费者只下载它所选 feature 需要
-的那一份。
+两张表刻意对称：两种环境都不是引擎眼里的「正常」，消费者只下载自己所选
+feature 需要的那一份。
 
-**并且两者都在 `run` 档位上 —— 这是第二道独立的闸门。** feature 说**谁**需要这个工具;
-档位说**什么时候**。编译固件两者都不需要,只有抵达板子才需要,所以一个只构建、从不
-烧录的 CI 任务**一个字节都不下载**。
+**并且两者都在 `run` 档位上——这是第二道独立的闸门。** feature 说的是**谁**
+需要这个工具；档位说的是**什么时候**需要。编译固件两者都不需要，只有抵达板子
+才需要，所以一个只构建、从不烧录的 CI 任务**一个字节都不下载**。
 
 ## C 库也是一个 feature
 
-每一行 `thumb*-none-eabi*` 的 C 库列都是空的,所以面向它的工程一开始**没有 libc**,
-除非它开口要。BSP 停在这一档:它不引用任何 C 库符号,它的控制台走 semihosting 而不是
-`stdio`。
+每一行 `thumb*-none-eabi*` 的 C 库列都是空的，所以面向它的工程一开始**没有
+libc**，除非工程自己开口要。BSP 停在这一档：它不引用任何 C 库符号，它的控制台
+走 semihosting，而不是 `stdio`。
 
 ```toml
 libc = {}
@@ -72,8 +73,9 @@ libc = {}
 picolibc.picolibc = "1.8.12.3"
 ```
 
-C 库以**源码包**的形式到达,用程序自己的旗标编译,于是没有 multilib 要匹配、也没有
-ABI 约定会弄错。`mcpp run --features libc` 就是全部;不选它,零 libc 档原样保留。
+C 库以**源码包**的形式到达，用程序自己的旗标编译，因此没有 multilib 要匹配，
+也没有 ABI 约定会弄错。`mcpp run --features libc` 就是全部；不选它，零 libc
+档原样保留。
 
 ## 构建程序
 
@@ -88,31 +90,31 @@ int main() {
             mcpp::runner(a);
         mcpp::run_exclusive();
     } else {
-        /* 这个目标对应的模拟器 argv */
+        /* the emulator's argv for THIS target */
     }
     return 0;
 }
 ```
 
-**哪个机器型号对应哪个目标,是一张表,不是一个默认值。** 为 `thumbv6m` 构建的镜像
-在实现 `thumbv7em` 的型号上跑不起来,而猜错的结果是它启动了、然后在毫不相干的地方
-faul。表里没有这一行时要**点名报错**,而不是静默缺席 —— 一个没有配置 runner 的 BSP
-会让 `mcpp run` 报「缺少 runner」并建议加一个 `runner` 键,那句话一般而言是对的,而
-在这里不是原因。
+**哪个机器型号对应哪个目标，是一张表，不是一个默认值。** 为 `thumbv6m`
+构建的镜像，在实现 `thumbv7em` 的型号上跑不起来；猜错的后果是它照常启动，
+随后在毫不相干的地方出错。表里没有对应行时，要**点名报错**，而不是静默
+缺席——一个没有配置 runner 的 BSP 会让 `mcpp run` 报「缺少 runner」并建议
+添加一个 `runner` 键，这句话一般而言是对的，但在这种情况下不是真正的原因。
 
-**写程序名,不写路径。** mcpp 会搜索图中任何包声明过的每一个载荷的 `bin/`,然后才是
-`PATH`,并且能准确报出它搜过哪些目录。用安装目录拼出来的绝对路径引入了一种失败形态:
-查找返回空,而没有任何东西说明为什么。
+**写程序名，不写路径。** mcpp 会搜索图中任何包所声明的每一个载荷的
+`bin/`，然后才轮到 `PATH`，并且能准确报出它搜过哪些目录。用安装目录拼出来
+的绝对路径，会引入一种失败形态：查找返回空，而没有任何东西说明原因。
 
-**引擎不认识上面任何一个 runner 名字。** `flash`、`serve`、`erase` 是这个包的词汇;
-另一个包提供的 `serve` 可以是别的意思,而两者都不必被 mcpp 知道。
+**引擎不认识上面任何一个 runner 名字。** `flash`、`serve`、`erase` 是这个
+包的词汇；另一个包提供的 `serve` 可以指别的意思，两者都不必被 mcpp 知道。
 
-**一个探针,一个使用者。** `mcpp::run_exclusive()` 声明这个目标的运行不可重叠,
-`mcpp test` 随后把它们串行化。工程方永远不需要记得加 `-j1`。
+**一个探针，一个使用者。** `mcpp::run_exclusive()` 声明这个目标的运行不可
+重叠，`mcpp test` 随后把它们串行化。工程方永远不需要记得加 `-j1`。
 
 ## 当前边界
 
-- BSP 把它的模拟器与探针驱动声明为载荷,因此工具链未在某个平台发布的板子,就无法
-  从那个平台抵达。
-- 机器型号表是按三元组组织的。需要表里没有的型号的板子,要改 BSP,而不是在工程侧
-  覆盖。
+- BSP 把它的模拟器与探针驱动声明为载荷，因此工具链未在某个平台发布的板子，
+  就无法从那个平台抵达。
+- 机器型号表按三元组组织。板子需要表里没有的型号时，要修改的是 BSP，而不是
+  在工程侧覆盖。
diff --git a/docs/zh/40-baremetal.md b/docs/zh/40-baremetal.md
index 64d2c778c..fdf204c5b 100644
--- a/docs/zh/40-baremetal.md
+++ b/docs/zh/40-baremetal.md
@@ -1,165 +1,168 @@
 # 40 —— 裸机与 freestanding 目标
 
-**读者:**面向没有操作系统的机器的嵌入式开发者。
+**读者：**面向没有操作系统的机器的嵌入式开发者。
 
-**本章回答的那一个问题:**一个工程怎样为 freestanding 目标构建、谁供给这个目标的
-整个世界,以及标准库还剩下什么。
+**本章回答的那一个问题：**一个工程怎样为 freestanding 目标构建、谁供给这个目标的
+整个世界，以及标准库还剩下什么。
 
-**不在这里:**运行与测试这个镜像,那是 [41 —— 抵达一台设备](41-devices.md);以及
-hosted 的交叉构建,那是 [24 —— 基于 openkal 的交叉构建](24-openkal-cross.md)。
+**不在这里：**运行与测试这个镜像，那是 [41 —— 抵达一台设备](41-devices.md)；hosted
+的交叉构建，那是 [24 —— 基于 openkal 的交叉构建](24-openkal-cross.md)。
 
-本文说明 mcpp 如何为没有操作系统的目标构建、运行与测试软件,以及板级支持包如何
-提供引擎刻意不去掌握的那部分目标事实。
+本章说明 mcpp 如何为没有操作系统的目标构建、运行与测试软件，以及板级支持包如何
+供给引擎刻意不掌握的那部分目标事实。
 
-相关文档:[04 — mcpp.toml 清单指南](04-mcpp-toml.md) §2.7.2 是本文使用的
-`[target.<triple>]` 各键的参考;[30 — build.mcpp 构建程序](30-build-mcpp.md)
-是板级支持包所用指令协议的参考;[91 — 工具链内部机制](91-toolchain-internals.md)
-描述了本文所偏离的宿主链接模型。
+相关文档：[04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) §2.7.2 是本章用到的
+`[target.<triple>]` 各键的参考；[30 —— build.mcpp 构建程序](30-build-mcpp.md)是
+板级支持包所用指令协议的参考；[91 —— 工具链内部机制](91-toolchain-internals.md)
+描述了本章所偏离的那套 hosted 链接模型。
 
 ## 概述
 
 freestanding 目标是 `os` 字段为 `none` 的目标。`modules/toolchain-model/src/triple.cppm`
-的目标表中有十三个:
+的目标表里有十三行：
 
 | Triple | 档位 | C 库 |
 |---|---|---|
 | `riscv64-none-elf` | verified | `xim:picolibc-riscv` |
 | `riscv32-none-elf` | verified | `xim:picolibc-riscv` |
-| `aarch64-none-elf` | preview | 默认无 —— 零 libc 层;`xim:picolibc-aarch64` 可声明 |
-| `x86_64-none-elf` | preview | 默认无 —— 零 libc 层;`xim:picolibc-x86` 可声明 |
-| `thumbv6m-none-eabi` | verified | 默认无 —— Cortex-M0/M0+/M1 |
-| `thumbv7m-none-eabi` | verified | 默认无 —— Cortex-M3 |
-| `thumbv7em-none-eabi` | preview | 默认无 —— Cortex-M4/M7,软浮点 |
-| `thumbv7em-none-eabihf` | verified | 默认无 —— Cortex-M4F/M7F,硬浮点 |
-| `thumbv8m.base-none-eabi` | preview | 默认无 —— Cortex-M23 |
-| `thumbv8m.main-none-eabi` | verified | 默认无 —— Cortex-M33/M55,软浮点 |
-| `thumbv8m.main-none-eabihf` | preview | 默认无 —— Cortex-M33F/M55F,硬浮点 |
-| `armv7a-none-eabi` | verified | 默认无 —— Cortex-A 32 位,软浮点 |
-| `armv7a-none-eabihf` | verified | 默认无 —— Cortex-A 32 位,硬浮点 |
-
-`verified` 意味着该行的镜像被构建**并被运行**过。`preview` 意味着它构建并链接得出,
-尚无模拟器运行记录。
+| `aarch64-none-elf` | preview | 默认无——零 libc 档；`xim:picolibc-aarch64` 可声明 |
+| `x86_64-none-elf` | preview | 默认无——零 libc 档；`xim:picolibc-x86` 可声明 |
+| `thumbv6m-none-eabi` | verified | 默认无——Cortex-M0/M0+/M1 |
+| `thumbv7m-none-eabi` | verified | 默认无——Cortex-M3 |
+| `thumbv7em-none-eabi` | preview | 默认无——Cortex-M4/M7，软浮点 |
+| `thumbv7em-none-eabihf` | verified | 默认无——Cortex-M4F/M7F，硬浮点 |
+| `thumbv8m.base-none-eabi` | preview | 默认无——Cortex-M23 |
+| `thumbv8m.main-none-eabi` | verified | 默认无——Cortex-M33/M55，软浮点 |
+| `thumbv8m.main-none-eabihf` | preview | 默认无——Cortex-M33F/M55F，硬浮点 |
+| `armv7a-none-eabi` | verified | 默认无——Cortex-A 32 位，软浮点 |
+| `armv7a-none-eabihf` | verified | 默认无——Cortex-A 32 位，硬浮点 |
+
+`verified` 表示该行的镜像已被构建**并被运行**过；`preview` 表示它构建、链接得出，
+但尚无模拟器运行记录。
 
 ### ARMv7-A 是第一个带内存管理单元的 32 位行
 
-上表其余每一个 32 位行都是 M-profile:MPU 按基址与上限描述区域,根本没有页表项。
-A-profile 有真正的 MMU 与页表走查器,所以它是第一个能被问「**32 位**机器的页表项长
-什么样」的目标 —— 短描述符 32 位宽,长描述符(LPAE)64 位。这个问题无法向一台没有
-页表项的机器提出,这正是 `openarch` 的 Cortex-M 后端不声明该能力的原因。
+上表其余每个 32 位行都是 M-profile：MPU 按基址和上限描述区域，没有任何页表项。
+A-profile 有真正的 MMU 和页表走查器，因此它是第一个可以被问「一台**32 位**机器的
+页表项长什么样」的目标——短描述符宽 32 位，长描述符（LPAE）宽 64 位。这个问题问
+不到一台没有页表项的机器，这正是 `openarch` 的 Cortex-M 后端不声明该能力的原因。
 
-**半主机的退出调用有两种拼法,只有一种带得走状态。** `SYS_EXIT`(`0x18`)把原因码
-**直接**放在 `r1`;`{reason, code}` 块是 `SYS_EXIT_EXTENDED`(`0x20`),它存在的理由
-正是 32 位的 `r1` 装不下「原因」与「状态」两者。把块传给 `0x18`,一切打印都正确,而
-**退出状态是错的**。
+**半主机的退出调用有两种拼法，只有一种带得走状态。**`SYS_EXIT`（`0x18`）把原因码
+**直接**放进 `r1`；`{reason, code}` 块是 `SYS_EXIT_EXTENDED`（`0x20`），它存在的
+理由正是 32 位的 `r1` 装不下「原因」和「状态」两者。把那个块传给 `0x18`，打印全部
+正确，而**退出状态是错的**。
 
-这是 **AArch32** 的事实,对 M-profile 与 A-profile 同样成立。实测两次:一个
-ARMv7-A 程序退 0 而报回 1;`openarch` 的一个 Cortex-M 示例打印了
-`both tasks observed preemption` 然后退 1 —— 对**输出**的每一条断言都通过了。只看
-自己打印了什么的板子看不出这个差别,所以 `tests/e2e/332` 与 `336` 都读 `$?`,而且都
-从模拟器本身取,不从管道末端取。
+这是 **AArch32** 层面的事实，对 M-profile 和 A-profile 同样成立。实测过两次：一个
+ARMv7-A 镜像退出码本应是 0，报回的却是 1；`openarch` 的一个 Cortex-M 示例打印了
+`both tasks observed preemption`，退出码却是 1——对**输出**的每一条断言都通过了。
+只检查自己打印了什么的板子看不出这个差别，这正是 `tests/e2e/332` 与 `336` 都读取
+`$?`、并且都从模拟器本身取值而不是从管道末端取值的原因。
 
 ### M-profile 是七行而不是一行
 
-上面每一个裸机族都是一个架构一行。Cortex-M 不是:为 `thumbv7em` 构建的目标文件
-使用 Cortex-M0 没有的指令,两种拼写产出的是互不兼容的目标文件,而不是一种偏好。
-这张表存在,是为了让 `--target <triple>` 单独就足以产出正确的目标文件;若只写一行
-`arm-none-eabi` 再让每个工程各自记住一个 `-mcpu`,就把一个正确性决定从表里搬进了
-每一份清单。
+上面其余每个裸机族都是一个架构一行，Cortex-M 不是。为 `thumbv7em` 构建出的目标
+文件用到 Cortex-M0 没有的指令，两种拼法产出的是互不兼容的目标文件，而不是一种
+偏好。这张表存在的意义，是让 `--target <triple>` 单独就足以产出正确的目标文件；
+若只写一行 `arm-none-eabi`，再让每个工程各自记住一个 `-mcpu`，就会把一个正确性
+决定从表里搬进每一份清单。
 
-`eabi`/`eabihf` 后缀即浮点 ABI,clang 直接从 triple 读出它:实测 llvm 22.1.8,
-`thumbv7em-none-eabi` 得到 `-mfloat-abi soft`,`thumbv7em-none-eabihf` 得到 `hard`。
+`eabi`/`eabihf` 后缀就是浮点 ABI，clang 无需额外提示就能从 triple 读出它：实测
+llvm 22.1.8，`thumbv7em-none-eabi` 得到 `-mfloat-abi soft`，`thumbv7em-none-eabihf`
+得到 `hard`。
 
-**浮点 ABI 并不决定 FPU 是否被使用。** 它约束浮点值如何跨越函数边界,不约束
-编译器在函数内部可以发什么指令,而 `thumbv7em` 架构蕴含 FPv4-SP。实测:在软浮点
-ABI 下,clang 对一次 float 乘法仍然发出 `vmul.f32`。在没有 FPU 的 Cortex-M4 上,
-这条指令在运行期触发异常 —— 而编译与链接都是干净的。因此每一个软浮点行都携带
-`-mfpu=none`,**包括那些架构本来就没有 FPU 的行**:一行应当陈述它所保证的性质,
-而不是从一个随时可以改变的默认值继承它。
+**浮点 ABI 并不决定 FPU 是否被使用。**它约束的是浮点值如何跨越函数边界，而不是
+编译器在函数内部可以发出什么指令，而 `thumbv7em` 架构本身蕴含 FPv4-SP。实测：在
+软浮点 ABI 下，clang 对一次 float 乘法仍然发出 `vmul.f32`。在没有 FPU 的
+Cortex-M4 上，这条指令在运行期触发异常——编译和链接都是干净的。因此每个软浮点行
+都携带 `-mfpu=none`，**包括那些架构本来就没有 FPU 的行**：一行应当陈述它所保证的
+性质，而不是从一个随时可能改变的默认值继承它。
 
-Cortex-M 不需要 `lldEmulation` 列:clang 有面向 arm 的 *BareMetal* 工具链,这些
-triple 与 RISC-V、aarch64 各行一样经驱动到达 `ld.lld`。32 位 ARM 没有 `-mcmodel`
-这个轴,所以该列同样为空。
+Cortex-M 不需要 `lldEmulation` 列：clang 备有面向 arm 的 *BareMetal* 工具链，这些
+triple 和 RISC-V、aarch64 各行一样经驱动到达 `ld.lld`。32 位 ARM 没有 `-mcmodel`
+这根轴，所以那一列同样为空。
 
 ### 死代码段消除
 
-freestanding 构建以 `-ffunction-sections -fdata-sections` 编译,以 `--gc-sections`
-链接。两半都属于引擎而不属于工程,因为依赖的翻译单元也必须带上它们,而工程够不到
-那些单元。
+freestanding 构建以 `-ffunction-sections -fdata-sections` 编译，以 `--gc-sections`
+链接。两者都属于引擎而不属于工程，因为依赖的翻译单元同样必须带上它们，而工程
+够不到那些单元。
 
-这两个标志从「划算」变成「必需」,发生在 C 库开始由依赖图提供的时候。依赖的目标
-文件是**无条件**进入链接的,不像归档成员那样只在符号仍未定义时才被拉入。当 C 库是
-预编译归档、目标又有若干兆字节时,这不花什么代价;而 Cortex-M 器件只有几十 KB,
-没有死代码段消除,每个镜像都会装进整份 C 库。
+这两个标志从「划算」变成「必需」，发生在 C 库开始由依赖图提供的那一刻。依赖的
+目标文件是**无条件**进入链接的，不像归档成员那样只在符号仍未定义时才被拉入。当
+C 库是预编译归档、目标又有几兆字节容量时，这不花什么代价；而 Cortex-M 器件只有
+几十 KB，没有死代码段消除，每个镜像都会装进整份 C 库。
 
-**链接脚本因此以一种新的方式承重。** 中断向量表不被任何东西引用 —— 硬件按地址
-读取它 —— 所以 `--gc-sections` 会把它回收。板级脚本必须写 `KEEP(*(.vectors))`。
-实测:有这条 `KEEP` 时,无人调用的函数被丢弃、向量表被保留、镜像能够启动。
+**链接脚本因此以一种新的方式承重。**中断向量表不被任何东西引用——硬件按地址读取
+它——所以 `--gc-sections` 会把它回收掉。板级脚本必须写 `KEEP(*(.vectors))`。实测：
+有这条 `KEEP` 时，没人调用的函数被丢弃，向量表被保留，镜像能够启动。
 
-后两行**默认**没有 C 库,这是声明而非遗漏:这两行的第一个消费者 —— 机器机制层
-`openarch` —— 一个 C 库符号都不引用,而**如果四行里没有一行默认在这一层,就没有
-任何东西在证明这一层可用**。空列在这里的含义与清单里
-`[target.<triple>].sysroot = ""` 完全一致。
-
-**这两行的 C 库是可声明的,不是不存在的**(mcpp 2026.8.21.3+)。
-`xim:picolibc-aarch64` 与 `xim:picolibc-x86` 已在索引里;想要它的工程自行声明,
-而那与它换用另一份 C 库是同一个动作:
+后两行**默认**没有 C 库，这是一句声明，不是一处遗漏：这两行的第一个消费者——机器
+机制层 `openarch`——一个 C 库符号都不引用，而如果十三行里没有一行默认落在这一档，
+就没有任何东西证明这一档能用。**这两行的 C 库是可声明的，不是不存在的**
+（mcpp 2026.8.21.3+）。`xim:picolibc-aarch64` 与 `xim:picolibc-x86` 已在索引里，
+想要它的工程自行声明，方式与换用另一份 C 库完全相同：
 
 ```toml
 [target.aarch64-none-elf]
 sysroot = "xim:picolibc-aarch64@1.8.12"
 ```
 
-这类目标不需要逐宿主的交叉工具链。clang 与 lld 在构造上就是交叉编译器 ——
-一个二进制发射它构建时支持的全部目标 —— 因此目标表在每个宿主上都钉
-`llvm@22.1.8`,任何能安装 LLVM 载荷的机器都能为这四个中的任何一个产出镜像。
+空列在这里的含义，与清单里 `[target.<triple>].sysroot = ""` 完全一致，因此面向
+这两行的工程，不问自取就落在零 libc 档上。想在这两个目标上使用 C 库的工程自行
+声明一份，方式与它换用另一份 C 库完全相同。
+
+这类目标不需要逐宿主的交叉工具链。clang 与 lld 在构造上就是交叉编译器——一个
+二进制发射它构建时支持的每一个目标——因此目标表在每个宿主上都钉住
+`llvm@22.1.8`，任何能安装这份 LLVM 载荷的机器，都能为这四个目标中的任意一个产出
+镜像。
 
-### x86_64 这一行不止是四个字符串
+### x86_64 这一行不只是四个字符串
 
-**一个目标行通常就是两张表里的两条记录,不含引擎代码。这一行需要引擎代码,
-而原因是 clang 的属性而非指令集的属性。**
+**一个目标行通常只是两张表里的两条记录，不含任何引擎代码。这一行需要引擎代码，
+而原因是 clang 的属性，不是指令集的属性。**
 
-clang 由 triple 选择工具链。它为 arm、aarch64、riscv 备有 *BareMetal* 工具链,
-直接以 `ld.lld` 链接;它没有 x86_64 的,于是裸 x86_64 triple 的每一种写法都落到
-通用 GCC 工具链上 —— 而后者的链接器是**宿主的 `g++`**:
+clang 按 triple 选择工具链。它为 arm、aarch64、riscv 备有 *BareMetal* 工具链，
+直接以 `ld.lld` 链接；它没有 x86_64 的，于是裸 x86_64 triple 的每一种写法都落到
+通用 GCC 工具链上——而那个工具链的链接器是**宿主的 `g++`**：
 
 ```
 g++: error: unrecognized command-line option '-fuse-ld=/…/llvm/22.1.8/bin/ld.lld'
 ```
 
 对 `x86_64-none-elf`、`x86_64-unknown-none-elf`、`x86_64-unknown-none`、
-`x86_64-elf`、`x86_64-none-none`、`x86_64-unknown-unknown` 逐一实测,结果一致;
-`-fuse-ld=lld`、`--ld-path=`、`--gcc-toolchain=`、`-B` 逐一实测,均不改变结果。
-唯一能改变它的是把 `linux` 放进 OS 位,而那会给一次裸机链接带来八条宿主 `-L`。
+`x86_64-elf`、`x86_64-none-none`、`x86_64-unknown-unknown` 逐一实测，结果一致；
+`-fuse-ld=lld`、`--ld-path=`、`--gcc-toolchain=`、`-B` 逐一实测，均不改变结果。
+唯一能改变它的是把 `linux` 放进 OS 位，而那会给一次裸机链接带来八条宿主 `-L`。
 
-两种结果都不可接受:经宿主 `g++` 会让这一行只在 Linux 宿主上成立;宿主搜索路径
-出现在 freestanding 链接上,正是本引擎存在的意义所要守住的封闭性。因此该行带了
-第五列 `lldEmulation`,置位时引擎直接用 `ld.lld` 驱动链接。标志的词汇随工具一同
-改变 —— `-Map=` 而非 `-Wl,-Map=`,`-m elf_x86_64` 而非 `--target=` —— 而仅属于
-驱动的标志(`-nostdlib++`、加载器标签)是被丢弃而不是被翻译。
+两种结果都不可接受：经宿主 `g++` 会让这一行只在 Linux 宿主上成立；宿主搜索路径
+出现在一次 freestanding 链接上，正是本引擎存在的意义所要守住的那份封闭性。因此
+这一行带了第五列 `lldEmulation`，置位时引擎直接用 `ld.lld` 驱动链接。标志的词汇
+随工具一同改变——`-Map=` 而非 `-Wl,-Map=`，`-m elf_x86_64` 而非 `--target=`——
+仅属于驱动本身的标志（`-nostdlib++`、加载器标签）则被丢弃，而不是被翻译。
 
-riscv 与 aarch64 两行的该列为空。它们的驱动本就到得了 lld,为了让三行看起来一致
-而改动一条可用的链接,正是引入回归的方式。
+riscv 和 aarch64 两行的这一列为空。它们的驱动本就到得了 lld，为了让三行看起来
+一致而去改动一条本已可用的链接，正是引入回归的方式。
 
-### `-mno-red-zone` 是目标的属性,不是偏好
+### `-mno-red-zone` 是目标的属性，不是偏好
 
-System V x86-64 ABI 在 `rsp` 之下保留 128 字节,叶函数可以不调整栈指针直接使用,
-因为在有操作系统的机器上没有别的东西会写那里。裸机上不存在做这件事的一方:处理器
-在 `rsp` 处压入中断帧 —— 正压进红区 —— 被中断的叶函数恢复后发现自己的局部变量已被
-覆盖。既不触发异常也没有诊断,而且只在中断恰好落在叶函数内部时发生。
+System V x86-64 ABI 在 `rsp` 之下保留 128 字节，叶函数可以不调整栈指针直接使用，
+因为在有操作系统的机器上没有别的东西会写那里。裸机上不是这样：处理器在 `rsp`
+处压入中断帧——正压进红区——被中断的叶函数恢复后，发现自己的局部变量已被覆盖。
+既不触发异常，也没有诊断，而且只在中断恰好落在叶函数内部时发生。
 
-不存在红区安全的裸机 x86_64 程序,所以这个标志是行的属性,而不是工程需要记住的
-事情。它经 ISA 档表新增的 `extra` 列到达命令行 —— 该列之所以存在,是因为
-`-march`/`-mabi`/`-mcmodel` 表达不了它。RISC-V 与 aarch64 没有对应物,这也正是
+不存在红区安全的裸机 x86_64 程序，所以这个标志是行的属性，不是工程需要记住的
+事情。它经 ISA 档表新增的 `extra` 列到达命令行——该列之所以存在，是因为
+`-march`/`-mabi`/`-mcmodel` 表达不了它。RISC-V 与 aarch64 没有对应物，这也正是
 此前不需要这一列的原因。
 
-裸机构建需要的三样东西并不是 ISA 的属性,mcpp 也不试图推导它们:选哪个启动对象
-与哪些库、哪份链接脚本描述这台机器的内存、以及如何执行产出的镜像。这三样随
-**板级支持包**一起提供,而板级支持包是一个普通依赖。由此得到的结果是:换板子是
-一次依赖变更,而不是一次构建系统变更。
+裸机构建需要的三样东西并不是 ISA 的属性，mcpp 也不试图推导它们：选哪个启动对象
+和哪些库、哪份链接脚本描述这台机器的内存、以及如何执行产出的镜像。这三样随
+**板级支持包**一起提供，板级支持包本身是一个普通依赖。由此得到的结果是：换板子
+是一次依赖变更，而不是一次构建系统变更。
 
 ## 从零到一个可运行的镜像
 
-两条命令即可产出一个会启动的镜像,其中链接脚本、加载地址与模拟器命令行都不必手写:
+两条命令即可产出一个会启动的镜像，链接脚本、加载地址与模拟器命令行都不必手写：
 
 ```bash
 mcpp new blinky --template riscv-virt-rt
@@ -167,7 +170,7 @@ cd blinky
 mcpp run
 ```
 
-实测输出:
+实测输出：
 
 ```
    Resolving toolchain
@@ -188,13 +191,14 @@ float 3.1416
 heap ok
 ```
 
-`Size` 行在每次 freestanding 链接后打印。容量是裸机目标上的支配性约束,而链接完成
-的那一刻引擎已经知道这个数;不打印就意味着每个工程都要另跑一次 `size`。在宿主目标
-上以及工具缺失时它保持静默 —— 一行信息性输出没有让构建失败的资格。
+`Size` 这一行在每次 freestanding 链接后都会打印。容量是裸机目标上的支配性约束，
+而链接一结束引擎就已经知道这个数；不打印它，就要求每个工程另外跑一次 `size`。
+在 hosted 目标上、以及工具缺失时它保持静默——一行信息性输出没有让构建失败的
+资格。
 
 ### 生成的工程
 
-整份清单只有四处声明:
+整份清单只有四处声明：
 
 ```toml
 [package]
@@ -208,11 +212,11 @@ target = "riscv64-none-elf"
 riscv-virt-rt = "0.3.0"
 ```
 
-其中没有 `[target.*]` 段,没有链接脚本路径,没有加载地址,没有 `-nostdlib`,
-没有 `-march`/`-mabi`/`-mcmodel`,没有 crt0,没有 C 库名字,也没有模拟器命令行。
-ISA 参数来自引擎的目标表;其余来自 `[dependencies]` 中列出的板级支持包。
+其中没有 `[target.*]` 段，没有链接脚本路径，没有加载地址，没有 `-nostdlib`，
+没有 `-march`/`-mabi`/`-mcmodel`，没有 crt0，没有 C 库的名字，也没有模拟器命令行。
+ISA 参数来自引擎的目标表；其余部分来自 `[dependencies]` 里列出的板级支持包。
 
-生成的 `src/main.cpp` 是一个普通的 `main`:
+生成的 `src/main.cpp` 是一个普通的 `main`：
 
 ```cpp
 import mcpplibs.riscv_virt_rt;
@@ -227,52 +231,54 @@ extern "C" int main() {
 }
 ```
 
-不需要 `_start`,也不需要汇编入口,因为板级支持包选取了 picolibc 的 semihosting
-`crt0` —— C 运行时在 `main` 之前就已就绪,返回值经 semihosting 回到宿主。只有完全
-没有 C 库的板子才需要显式入口,做法是让 `main` 指向携带 `_start` 的那份源文件。
+不需要 `_start`，也不需要汇编入口，因为板级支持包选取了 picolibc 的 semihosting
+`crt0`——C 运行时在 `main` 运行之前就已初始化好，返回值经 semihosting 传回宿主。
+只有完全没有 C 库的板子才需要显式入口点，做法是让 `main` 指向携带 `_start` 的
+那份源文件。
 
 ## freestanding 目标带来的变化
 
 | 方面 | 在 freestanding 目标上的行为 |
 |---|---|
-| 链接行 | 从零构造而非在原有基础上追加:`-nostdlib -nostartfiles -static`,没有 crt 文件,没有动态链接器,没有 C++ 运行时。在宿主链接行后追加 `-nostdlib` 将依赖驱动以正确顺序丢弃先前的 flag。 |
-| 链接器选择 | `ld.lld` 按**绝对路径**寻址,由驱动自身所在目录推导。`-fuse-ld=lld` 按名字解析,在任何 binutils 位于 `PATH` 更靠前位置的机器上都会找到 GNU ld,随后以 `unrecognised emulation mode: elf64lriscv` 失败。 |
-| ISA 参数 | `-march`、`-mabi` 与 `-mcmodel` 来自 `src/freestanding/target.cppm` 中每个目标一行的表,因此仅凭 `--target <triple>` 就足以产出正确的目标文件。 |
-| C 库 | 属于**目标**,由 mcpp 从目标自己的表行解析,与解析编译器的方式完全一致。裸机工程不声明 libc,正如宿主工程不声明 glibc。引擎把 sysroot 的库目录放入链接搜索路径,板级支持包因此可以按裸名从中选取(`-lc`、`-lcrt0-semihost`)。 |
-| 异常与 RTTI | 在图中每个翻译单元上都关闭,包括依赖的翻译单元,**除非有包提供为该目标构建的 C++ 运行时**。否则既没有 unwinder 也没有 `libc++abi`,任何东西都无法抛出;仅 `std::optional::value()` 一处就会引用 `__cxa_throw` 以及另外三个未定义符号。该设定属于目标而非工程的 `cxxflags`,因为 BMI 会记录它,而带异常编出的依赖无法被不带异常的单元导入。声明 `provides = ["hosted-standard-library"]` 的包会翻转这个默认:异常与 RTTI 开启,`-ffreestanding` 被去掉,并加上 `-fasynchronous-unwind-tables`。 |
-| `import std` | 当图中有包提供 `hosted-standard-library` 并指明自己的 `std` 模块源码时可用;否则在配置期以诊断拒绝,而不是在链接期失败。 |
-| 入口点 | 只要有东西提供 `crt0`,`int main()` 就可用。板级支持包通常提供它。 |
-| 默认链接方式 | 静态,而且这不是偏好:没有加载器,因此没有别的选项。 |
+| 链接行 | 从零构造，而不是在原有基础上追加：`-nostdlib -nostartfiles -static`，没有 crt 文件、没有动态链接器、没有 C++ 运行时。在 hosted 链接行后追加 `-nostdlib`，要依赖驱动按正确顺序丢弃先前的 flag 才行得通。 |
+| 链接器选择 | `ld.lld` 按**绝对路径**寻址，由驱动自身所在目录推导。`-fuse-ld=lld` 按名字解析，在任何 binutils 位于 `PATH` 更靠前位置的机器上都会找到 GNU ld，随后以 `unrecognised emulation mode: elf64lriscv` 失败。 |
+| ISA 参数 | `-march`、`-mabi`、`-mcmodel` 来自 `src/freestanding/target.cppm` 中每个目标一行的表，因此仅凭 `--target <triple>` 就足以产出正确的目标文件。 |
+| C 库 | 属于**目标**，由 mcpp 从目标自己的表行解析，方式与解析编译器完全一致。裸机工程不声明 libc，正如 hosted 工程不声明 glibc。引擎把 sysroot 的库目录放进链接搜索路径，板级支持包因此可以按裸名从中选取（`-lc`、`-lcrt0-semihost`）。 |
+| 异常与 RTTI | 在图中每个翻译单元上都关闭，包括依赖的翻译单元，**除非有包提供为该目标构建的 C++ 运行时**。否则既没有 unwinder，也没有 `libc++abi`，任何东西都无法抛出；仅 `std::optional::value()` 一处，就会引用 `__cxa_throw` 以及另外三个未定义符号。该设定属于目标，而不是工程的 `cxxflags`，因为 BMI 会记录它，而带异常编出的依赖无法被不带异常的单元导入。声明了 `provides = ["hosted-standard-library"]` 的包会翻转这个默认：异常和 RTTI 开启，`-ffreestanding` 被去掉，并加上 `-fasynchronous-unwind-tables`。 |
+| `import std` | 当图中有包提供 `hosted-standard-library` 且指明了自己的 `std` 模块源码时可用；否则在配置期以诊断拒绝，而不是在链接期才失败。 |
+| 入口点 | 只要有东西提供 `crt0`，`int main()` 就可用。板级支持包通常会提供它。 |
+| 默认链接方式 | 静态，而且这不是偏好：没有加载器，因此没有别的选项。 |
 
-一个完全没有依赖的工程仍然构建得出来,这正是「仅凭 ISA 表行就已足够」的证据:
+一个完全没有依赖的工程仍然构建得出来，这正是「单凭 ISA 表行已经足够」的证据：
 
 ```
         Size norunner  text 12  data 0  bss 0  total 12
 ```
 
-## 分层:引擎、目标与板级支持包
+## 分层：引擎、目标与板级支持包
 
-职责划分只有一句话:**位置是目标的事实,选择是板级的事实。**
+职责划分只有一句话：**位置是目标的事实，选择是板级的事实。**
 
 | 层 | 拥有的内容 | 例子 |
 |---|---|---|
-| 引擎 | ISA 档位、freestanding 链接行、产物集、以及「产物如何执行」的单一读取点 | `-march=rv64gc -mabi=lp64d -mcmodel=medany -ffreestanding` |
-| 目标 | 用哪个编译器与哪份 C 库,两者都从目标的表行解析并按需安装 | `pin = llvm@22.1.8`、`sysroot = xim:picolibc-riscv@1.8.12` |
-| 板级支持包 | 选哪个启动对象与哪些库、哪份链接脚本、哪条模拟器命令行 | `-lcrt0-semihost`、`picolibcpp.ld`、`qemu-system-riscv64 -machine virt …` |
+| 引擎 | ISA 档位、freestanding 链接行、产物集，以及「产物如何执行」的单一读取点 | `-march=rv64gc -mabi=lp64d -mcmodel=medany -ffreestanding` |
+| 目标 | 用哪个编译器、用哪份 C 库，两者都从目标的表行解析并按需安装 | `pin = llvm@22.1.8`、`sysroot = xim:picolibc-riscv@1.8.12` |
+| 板级支持包 | 选哪个启动对象和哪些库、哪份链接脚本、哪条模拟器命令行 | `-lcrt0-semihost`、`picolibcpp.ld`、`qemu-system-riscv64 -machine virt …` |
 
-中间那一行正是让包不必指名 C 库的原因。两个生态包早先都在环境表里直接指名过一份
-libc 包,这把包绑死在一份 libc、一种架构与一种编译器实现上。该声明已不再需要,目标的 sysroot 列取代了它。
+中间那一行正是让包不必指名 C 库的原因。两个生态包更早的版本都在环境表里直接
+指名过一份 libc 包，这把包绑死在一份 libc、一种架构与一种编译器实现上。这条
+声明已不再需要，目标的 sysroot 列取代了它。
 
-同一 ISA 上的第二块板子,是把最后一行里的三个取值换掉。它不需要引擎作任何改动。
+同一 ISA 上的第二块板子，只是把最后一行里的三个取值换掉，不需要引擎做任何改动。
 
 ## 示例
 
-本节每一段实录都在 `x86_64-linux-gnu` 上用 mcpp 2026.8.20.1 实测得到,
-参见[验证范围](#验证范围)。
+本节每一段实录，都是在 `x86_64-linux-gnu` 上用 mcpp 2026.8.20.1 实测得到的，参见
+[验证范围](#验证范围)。
 
 ### 切换 ISA 宽度
 
-同一份源码与同一个板级支持包同时服务两种宽度:
+同一份源码、同一个板级支持包，同时服务两种宽度：
 
 ```bash
 mcpp run --target riscv32-none-elf
@@ -285,13 +291,14 @@ float 3.1416
 heap ok
 ```
 
-工程的源码与板级支持包都未改动。板级支持包从 `MCPP_TARGET_ARCH` 选取档位,而 ISA
-参数来自引擎的表 —— 那是数据而不是代码,再支持一种宽度是加一行。
+工程的源码和板级支持包都未改动。板级支持包从 `MCPP_TARGET_ARCH` 选取档位，ISA
+参数来自引擎的表——那是数据而不是代码，再支持一种宽度只是加一行。
 
 ### freestanding 标准库子集
 
-`import std` 是覆盖整个库的一个模块,线程、文件系统与 iostreams 全在其中,因此在
-没有操作系统的前提下不存在它的子集可编。承载其中不需要 OS 的那部分的是一个普通依赖:
+`import std` 是覆盖整个标准库的一个模块，线程、文件系统与 iostreams 全在其中，
+因此在没有操作系统的前提下，不存在它的一个可编子集。承载其中不需要操作系统那
+部分的，是一个普通依赖：
 
 ```toml
 [dependencies]
@@ -323,7 +330,7 @@ extern "C" int main() {
 }
 ```
 
-实测输出与体积:
+实测输出与体积：
 
 ```
         Size blinky  text 19564  data 72  bss 5632  total 25268
@@ -333,14 +340,14 @@ atomic 42
 span 4 ok
 ```
 
-该子集覆盖 LLVM 22.1.8 载荷所带 110 个 `std/*.inc` 头中的 103 个 —— 2026-08-20 在
-两侧目录分别计数得到 —— 且它由机械挑选生成,而不是手写的导出表。被略去的 7 个,
-按包一侧的说明在宿主 `x86_64` 上同样失败;该说明未在此重新实测。可用的实体包括
-`array`、`span`、`optional`、
-`expected`、`atomic`、`string_view`、`ranges`、`algorithm`、`bit`、`charconv`、
-`concepts`、`type_traits`、`tuple`、`utility` 以及协程。
+该子集覆盖 LLVM 22.1.8 载荷所带 110 个 `std/*.inc` 头文件中的 103 个——2026-08-20
+在两侧目录分别计数得到——而它是由机械挑选生成的，不是手写的导出表。被略去的
+7 个，按包一侧的说明，在 hosted `x86_64` 上同样会失败；那份说明没有在这里重新
+实测。可用的实体包括 `array`、`span`、`optional`、`expected`、`atomic`、
+`string_view`、`ranges`、`algorithm`、`bit`、`charconv`、`concepts`、
+`type_traits`、`tuple`、`utility`，以及协程。
 
-子集排除掉的部分在编译期被排除,而不是运行期:
+子集排除掉的部分，是在编译期被排除的，而不是运行期：
 
 ```cpp
 std::mutex m;
@@ -350,11 +357,11 @@ std::mutex m;
 error: no type named 'mutex' in namespace 'std'
 ```
 
-### 子集中会分配的那半边
+### 子集里会分配内存的那一半
 
-子集不改变什么能编。它的全部头文件都是无条件包含的,`std::vector` 今天就编得过;
-失败发生在**链接**,因为 freestanding 目标没有编译版 `libc++`,也就没有
-`operator new`:
+子集本身不改变什么能编。它的全部头文件都是无条件包含的，`std::vector` 今天就
+编得过；失败发生在**链接**，因为一个 freestanding 目标没有编译版的 `libc++`，
+也就没有 `operator new`：
 
 ```
 ld.lld: error: undefined symbol: operator new(unsigned long)
@@ -363,9 +370,9 @@ ld.lld: error: undefined symbol: operator new(unsigned long)
 
 | 不需要分配器 | 需要分配器 |
 |---|---|
-| `array` `span` `optional` `expected` `atomic` `string_view` `ranges` `algorithm` `bit` `charconv` `tuple` | `vector` `string` `deque` `list` `map` `set` `unordered_*` `function` `any` `make_unique`,以及默认的协程帧 |
+| `array` `span` `optional` `expected` `atomic` `string_view` `ranges` `algorithm` `bit` `charconv` `tuple` | `vector` `string` `deque` `list` `map` `set` `unordered_*` `function` `any` `make_unique`，以及默认的协程帧 |
 
-分配器随一个 feature 到来:
+分配器随一个 feature 到来：
 
 ```toml
 [dependencies]
@@ -379,18 +386,18 @@ std-freestanding = { version = "0.3.0", features = ["alloc-libc"] }
 vector 5 last=16
 ```
 
-`alloc-libc` 转发到目标的 C 库,目标有 C 库时它是更短的路径。`alloc-kal` 转发到
-openkal,适用于同一份源码还要为「环境不是 C 库」的目标构建的工程;裸机上 openkal
-后端由板级支持包提供,因为控制台与堆区都是板级事实:
+`alloc-libc` 转发到目标的 C 库，目标有 C 库时，这是更短的路径。`alloc-kal` 转发到
+openkal，适用于同一份源码还要为「环境不是 C 库」的目标构建的工程；在裸机上，
+openkal 后端由板级支持包提供，因为控制台在哪、堆区在哪都是板级事实：
 
 ```toml
 riscv-virt-rt    = { version = "0.4.0", features = ["openkal"] }
 std-freestanding = { version = "0.3.0", features = ["alloc-kal"] }
 ```
 
-`operator new` 是全程序单例,因此实现是独立的包,而选择属于程序。feature 以能力的
-形式声明这条要求,实现方提供该能力,解析器绑定恰好一个。两种失败因此都在图解析时
-报告,点名的是包而不是 mangled 符号:
+`operator new` 是全程序单例，因此实现方是一个独立的包，选择权属于程序。feature
+把这条要求表述为一种能力，实现方提供该能力，解析器绑定恰好一个。两种失败因此都
+在图解析时报告，点名的是包，不是被 mangle 过的符号：
 
 ```
 error: no package provides capability 'freestanding-allocator' required by 'std-freestanding'
@@ -401,61 +408,63 @@ error: capability 'freestanding-allocator' has multiple providers in the graph:
 
 ### 没有 C 库的目标
 
-`[target.<triple>].sysroot` 覆盖目标表所绑定的 C 库,与 `toolchain` 覆盖编译器 pin
-同轴。空字符串表示完全不要 C 库:
+`[target.<triple>].sysroot` 覆盖目标表所绑定的 C 库，与 `toolchain` 覆盖编译器
+pin 处在同一根轴上。空字符串表示完全不要 C 库：
 
 ```toml
 [target.riscv64-none-elf]
 sysroot = ""
 ```
 
-有了这一行,C 头文件离开编译行,C 库离开链接行。`#include <stdio.h>` 不再解析,
-镜像里只剩工程与其依赖放进去的内容。实测:一个自带入口点与链接脚本的自包含镜像
-链接后为 **108 字节**,并能启动。
+有了这一行，C 头文件离开编译行，C 库离开链接行。`#include <stdio.h>` 不再能
+解析，镜像里只剩工程与其依赖放进去的内容。实测：一个自带入口点和链接脚本的
+自包含镜像，链接后只有 **108 字节**，并且能启动。
 
-键缺席与键为空是两个不同的答案。缺席继承目标表的 C 库,存在且为空则拒绝它。内核与
-bootloader 要的是后者,而
+键缺席和键为空是两个不同的答案。缺席继承目标表的 C 库；存在且为空则拒绝它。
+内核或 bootloader 要的是后者，而
 
 ```bash
 mcpp new mykernel --template riscv-virt-rt:nolibc
 ```
 
-生成的工程已处于该安排 —— 一个入口点、一份内存映射、一个设备,实测 369 字节。
+生成的工程已经处在这种安排里——一个入口点、一份内存映射、一个设备，实测
+369 字节。
 
-freestanding 翻译单元仍会用到的 C 函数中,有四个是义务而非便利:`memcpy`、
-`memmove`、`memset` 与 `memcmp` 必须存在,因为编译器把结构体赋值与数组初始化下降到
-它们之上。`std-freestanding-nolibc` 提供这四个与 `strlen`。
+freestanding 翻译单元仍会用到的 C 函数里，有四个是义务而非便利：`memcpy`、
+`memmove`、`memset`、`memcmp` 必须存在，因为编译器把结构体赋值与数组初始化
+下降到它们之上。`std-freestanding-nolibc` 提供这四个，以及 `strlen`。
 
-子集与这一档是**组合**关系而非互斥。`std-freestanding` 带 `features = ["nolibc"]`
-时在完全没有 C 库的情况下编译,实测其 **103 个头中的 94 个**可用。障碍从来不是子集
-需要一个 C 库:libc++ 为 C 头文件提供了包装头 —— `string.h` 及其同类 —— 它们通过
-`#include_next` 续到真正的头去取 `size_t`、`mbstate_t`、`time_t` 与 `EOF`。没有
-C 库时这条链无处可续,包装头死在缺**类型**而不是缺头文件上,这正是从报错看不出成因的
-原因。四个很小的头把链续上,而该 feature 负责把它们引进来。
+子集与这一档是**组合**关系，不是互斥。`std-freestanding` 带
+`features = ["nolibc"]` 时，在完全没有 C 库的情况下编译，实测其
+**103 个头文件里有 94 个**可用。障碍从来不是「子集需要一个 C 库」：libc++ 为
+C 头文件提供了包装头——`string.h` 及其同类——它们经 `#include_next` 续到真正
+的头文件，去取 `size_t`、`mbstate_t`、`time_t`、`EOF`。没有 C 库时这条链无处
+可续，包装头败在缺**类型**，不是缺头文件，这正是报错本身看不出成因的原因。四个
+很小的头把这条链续上，而该 feature 负责把它们引进来。
 
-板级支持包同样可以服务这一档,理由与"为什么要有板级包"是同一条:一台机器的 UART 在哪、
-RAM 从哪开始、哪个模拟器启动它,没有一条是 C 库事实:
+板级支持包同样可以服务这一档，理由与「为什么要有板级支持包」是同一条：一台机器
+的 UART 在哪、RAM 从哪开始、哪个模拟器启动它，没有一条是 C 库事实：
 
 ```toml
 [dependencies]
 riscv-virt-rt = { version = "0.5.0", features = ["nolibc"] }
 ```
 
-`std-freestanding-nolibc` 正是该 feature 解析到的包,而**直接**把它与 C 库并用时
-是**静默**失败而非响亮失败。C 库以归档形式
-发布,归档成员只在符号仍未定义时才被拉入;而依赖包的目标文件无条件进入链接。于是该包
-先定义了 `memcpy`,C 库的成员从不被拉入,构建**成功** —— 程序拿到的是逐字节实现而不是
-C 库经过优化的那份,且没有任何提示。实测(picolibc 在场):冷构建链接通过,`nm` 只找到
-一处定义。
+`std-freestanding-nolibc` 正是该 feature 解析到的包，而把它**直接**和一份 C 库
+并用，是**静默**失败，不是响亮失败。C 库以归档形式发布，归档成员只在符号仍未
+定义时才被拉入；而依赖包的目标文件无条件进入链接。于是该包先定义了 `memcpy`，
+C 库那个成员从不被拉入，构建**成功**——程序拿到的是逐字节实现，不是 C 库那份
+经过优化的实现，而且没有任何提示。实测（picolibc 在场）：冷构建链接通过，`nm`
+只找到一处定义。
 
 ### 在目标上运行测试
 
-测试在这里的运作方式与 [08 —— 测试](08-testing.md) 所述完全一致,本节只补充板子
-特有的部分:每个 `tests/*.cpp` 成为它自己的一个镜像,由板级支持包提供的 runner
-执行它。
+测试在这里的运作方式，与 [08 —— 测试](08-testing.md) 所述完全一致，本节只补充
+板子特有的部分：每个 `tests/*.cpp` 成为它自己的一个镜像，由板级支持包提供的
+runner 执行它。
 
-让判据成立的是 semihosting —— 它把固件 `main` 的返回值传递到模拟器的退出码。这正是
-这个模型与宿主上的运行**完全一致**而不只是相似的原因。
+让判据成立的是 semihosting——它把固件 `main` 的返回值传递到模拟器的退出码。这
+正是这个模型与 hosted 上的运行**完全一致**，而不只是相似的原因。
 
 ```bash
 mcpp test
@@ -470,7 +479,7 @@ boots ... ok (0.02s)
  test result ok. 1 passed; 0 failed; finished in 0.58s (build 0.05s + run 0.02s)
 ```
 
-失败的用例会被点名,命令的退出状态非零:
+失败的用例会被点名，命令的退出状态非零：
 
 ```
 deliberate_fail ... FAIL (exit 1, 0.02s)
@@ -486,7 +495,7 @@ failures:
 
 ### 烧录所需的产物集
 
-freestanding 链接产出三个文件而不是一个:
+一次 freestanding 链接产出三个文件，不是一个：
 
 ```
 target/riscv64-none-elf/<fingerprint>/bin/blinky        91640 bytes   ELF, for a debugger or `qemu -kernel`
@@ -494,14 +503,15 @@ target/riscv64-none-elf/<fingerprint>/bin/blinky.bin     8664 bytes   flat image
 target/riscv64-none-elf/<fingerprint>/bin/blinky.map    253369 bytes  link map
 ```
 
-裸二进制由一条 `objcopy -O binary` 边产出,该工具与驱动取自同一份载荷。映射文件是
-链接边的隐式输出而非一个孤立的 `-Wl,-Map=` flag,因此删掉它会被重新生成;它是唯一
-能回答「某个段为何在此处」以及「某段内容为何被或未被从归档中拉入」的产物。
+裸二进制由一条 `objcopy -O binary` 边产出，它使用的载荷与驱动本身相同。映射文件
+是链接边的隐式输出，不是一个孤立的 `-Wl,-Map=` flag，因此删掉它会被重新生成；它
+是唯一能回答「某个段为什么在此处」以及「某段内容为什么被或没被从归档里拉入」的
+产物。
 
 ### 覆盖板级支持包提供的 runner
 
-板级支持包通常提供 runner。工程可以覆盖它,这是通常的优先级 —— 工程作者写下的
-胜过依赖提供的:
+板级支持包通常提供 runner。工程可以覆盖它，这是通常的优先级——工程作者写下的
+胜过依赖提供的：
 
 ```toml
 [target.riscv64-none-elf]
@@ -511,19 +521,19 @@ runner = ["qemu-system-riscv64", "-machine", "virt", "-nographic",
           "-kernel"]
 ```
 
-覆盖生效时会被报告,而不是静默应用:
+覆盖生效时会被报告，不是静默应用：
 
 ```
         note [target.riscv64-none-elf].runner overrides the runner a dependency supplied
 ```
 
-产物路径追加在模板末尾,或者在模板包含 `{}` 时替换该记号。追加是常见形态,因为
-`-kernel <image>` 处在命令行末尾。
+产物路径追加在模板末尾，或者在模板包含 `{}` 时替换该记号。追加是常见形态，因为
+`-kernel <image>` 正处在命令行末尾。
 
-mcpp 不附带任何默认 runner。用哪个模拟器、哪种机器模型、哪种固件模式都是板级事实
-—— 同一 ISA 上的两块板子需要不同的 argv,OpenSBI 启动用 `-bios default`,picolibc
-镜像用 `-bios none -semihosting` —— 因此一个猜中其中之一的引擎,会被另一块板子反复
-对抗。
+mcpp 不附带任何默认 runner。用哪个模拟器、哪种机器模型、哪种固件模式都是板级
+事实——同一 ISA 上的两块板子需要不同的 argv，OpenSBI 启动用 `-bios default`，
+picolibc 镜像用 `-bios none -semihosting`——因此一个替其中之一猜好了默认值的
+引擎，会被另一块板子反过来拖累。
 
 ## 诊断
 
@@ -545,14 +555,14 @@ error: `import std;` is not available on 'riscv64-none-elf' — a freestanding t
        exports `mcpplibs.riscv_virt_rt`).
 ```
 
-该消息在配置期发出。若改为报告缺少 `std` 模块源,会把读者引向排查一个损坏的载荷,
-而工具链其实什么都不缺。
+该消息在配置期发出。若改为报告缺少一份 `std` 模块源码，会把读者引去排查一个
+损坏的载荷，而工具链并不缺任何东西。
 
 ### 缺少 runner
 
-freestanding 产物无法在构建机器上执行:ISA 不对,没有加载器,而且它预期独占整个
-地址空间。当没有配置 runner 时,`mcpp run` 会报告「构建成功」与「无法执行」之间的
-这段落差:
+一个 freestanding 产物无法在构建机器上执行：ISA 不对，没有加载器，而且它预期
+独占整个地址空间。没有配置 runner 时，`mcpp run` 会报告「构建成功」与「无法
+执行」之间的这段落差：
 
 ```
 error: no runner is configured for 'riscv64-none-elf' — a freestanding artifact cannot execute on this machine.
@@ -566,62 +576,62 @@ error: no runner is configured for 'riscv64-none-elf' — a freestanding artifac
        A board-support package normally supplies this so you do not have to.
 ```
 
-这个键不限于裸机。hosted 交叉目标 —— x86_64 宿主上的 `aarch64-linux-musl` 产物 ——
-使用同一个 `[target.<triple>].runner`,以 `qemu-aarch64-static` 这类用户态模拟器代替
-系统模拟器;在这类目标上,缺少 runner 在内核拒绝产物之前不是错误。hosted 目标的规则、
-`--no-runner` 出口与 `mcpp test` 的未运行报告见 [04 —— mcpp.toml](04-mcpp-toml.md)
-§2.7.3。
+这个键并不限于裸机。一个 hosted 交叉目标——x86_64 宿主上的 `aarch64-linux-musl`
+产物——使用的是同一个 `[target.<triple>].runner`，只是以 `qemu-aarch64-static`
+这类用户态模拟器代替系统模拟器；在这类目标上，缺少 runner 在内核拒绝该产物之前
+都不算错误。hosted 目标的规则、`--no-runner` 出口，以及 `mcpp test` 对「未运行」
+的报告方式，都在 [04 —— mcpp.toml](04-mcpp-toml.md) §2.7.3。
 
 ## 编写板级支持包
 
-板级支持包是一个普通的 mcpp 包。它在 `[xlings.workspace]` 下声明所需的模拟器,为消费者
-导出一个 C++ 模块,并从 `build.mcpp` 发出它的板级事实。
+板级支持包是一个普通的 mcpp 包。它在 `[xlings.workspace]` 下声明自己需要的
+模拟器，为消费者导出一个 C++ 模块，并从 `build.mcpp` 发出它的板级事实。
 
-**那里的声明会在首次构建时供给该包**(2026.8.29 起;这张表是
-`[xlings.workspace]`)。它同时让
-`mcpp::xpkg_dir` 能回答「那个包落在哪」。两半都要紧:同一条声明既装上模拟器,也告诉
-构建程序它装到了哪。
+**那里的声明会在首次构建时供给这个包**（自 2026.8.29 起；该表是
+`[xlings.workspace]`）。它同时也是 `mcpp::xpkg_dir` 能够回答「那个包落在哪」的
+前提。两半都要紧：同一条声明既装上模拟器，也告诉构建程序它装到了哪里。
 
-这次供给用的正是 `[toolchain]` 一直以来的契约 —— 声明它,mcpp 在首次使用时装上 ——
-并且遵守同样两个开关:在 `--offline` / `MCPP_OFFLINE` 或 `MCPP_NO_AUTO_INSTALL` 下
-mcpp 转为拒绝,并列出包名以便手动安装。
+这次供给用的正是 `[toolchain]` 一直以来的契约——声明它，mcpp 在首次使用时装
+上——并且遵守同样两个开关：在 `--offline` / `MCPP_OFFLINE` 或
+`MCPP_NO_AUTO_INSTALL` 下，mcpp 转为拒绝，并点名那些包，以便脱离该流程单独
+安装。
 
-**构建程序仍然不得假定目录存在。** 供给发生在**声明**了这些 deps 的那个包上;
-构建程序可以从没有发生过供给的路径被走到 —— 一个自己什么都没声明的工程的依赖、
-上面两个开关拒绝掉的环境 —— 所以 `xpkg_dir` 仍可能返回空,此时必须说出来,而不是
-发出一个坏掉的 runner:
+**构建程序仍然不得假定这个目录存在。**供给只发生在**声明**了这些 deps 的那个
+包上；构建程序可能经由从未发生过供给的路径被走到——某个自己什么都没声明的
+工程的依赖、被上面两个开关拒绝掉的环境——因此 `xpkg_dir` 仍可能返回空，此时
+程序必须把这一点说出来，而不是发出一个坏掉的 runner：
 
 ```cpp
 if (const char* dir = mcpp::xpkg_dir("xim", "qemu-riscv"); dir && *dir) {
     mcpp::runner(std::format("{}/bin/qemu-system-riscv64", dir).c_str());
-    // …… 其余 argv ……
+    // … the rest of the argv …
 } else {
-    mcpp::warning("qemu-riscv 未安装,于是 `mcpp run` 没有 runner。"
-                  "装一次即可:  xlings install qemu-riscv -y");
+    mcpp::warning("qemu-riscv is not installed, so `mcpp run` has no runner. "
+                  "Install it once:  xlings install qemu-riscv -y");
 }
 ```
 
-没有那一行,构建会成功、不配置 runner,而 `mcpp run` 报告缺少 runner 并建议写一个
-`runner` 键 —— 这句话一般情况下对,在这里不对。见 [30 —— build.mcpp](30-build-mcpp.md)
-的 `mcpp:warning=`。
+没有这一行，构建会成功、不配置任何 runner，而 `mcpp run` 会报告缺少 runner，
+并建议写一个 `runner` 键——这句话一般情况下是对的，在这里不是。参见
+[30 —— build.mcpp](30-build-mcpp.md) 里的 `mcpp:warning=`。
 
 ### 板级支持包发出的指令
 
 | 指令 | 作用 |
 |---|---|
-| `mcpp:link-lib=<name>` | 向消费者的链接行加入 `-l<name>`。裸名即可:目标 sysroot 的库目录已在搜索路径上。 |
-| `mcpp:link-search=<dir>` | 加入 `-L<dir>`,用于包自身携带的库。 |
-| `mcpp:link-script=<abs path>` | 加入 `-T <path>`。相对路径按包根解析,因此属于目标 C 库的脚本必须按绝对路径指名。 |
-| `mcpp:runner=<token>` | 向运行模板追加一个 argv 记号。argv 是有序列表,模板由重复构建 —— 一个记号一行指令。 |
-| `mcpp:include-dir=<dir>` | 加入一个**仅对本包生效**的头文件目录。 |
+| `mcpp:link-lib=<name>` | 向消费者的链接行加入 `-l<name>`。裸名即可：目标 sysroot 的库目录已经在搜索路径上。 |
+| `mcpp:link-search=<dir>` | 加入 `-L<dir>`，用于包自己携带的库。 |
+| `mcpp:link-script=<abs path>` | 加入 `-T <path>`。相对路径按包根解析，因此属于目标 C 库的脚本必须用绝对路径指名。 |
+| `mcpp:runner=<token>` | 向运行模板追加一个 argv 记号。argv 是有序的，模板因此由重复构建——一个记号一行指令。 |
+| `mcpp:include-dir=<dir>` | 加入一个**仅对本包生效**的头文件搜索目录。 |
 
-两个「向引擎提问」的接口提供了板级支持包不应硬编码的路径:`mcpp::sysroot_dir()`
-返回目标 C 库的根,`mcpp::xpkg_dir(ns, name)` 返回一个已安装载荷的目录。
-`mcpp::target_arch()` 报告正在构建的架构。
+两个向引擎发问的接口，提供了板级支持包不应硬编码的那些路径：
+`mcpp::sysroot_dir()` 返回目标 C 库的根目录，`mcpp::xpkg_dir(ns, name)` 返回一个
+已安装载荷的目录。`mcpp::target_arch()` 报告正在构建的架构。
 
-### 指令作用域与到达消费者的内容
+### 指令作用域，以及到达消费者的内容
 
-作用域是刻意不对称的,而这份不对称正是指令层完全不需要 sysroot 概念的原因:
+作用域是刻意不对称的，这份不对称正是指令层完全不需要一个 sysroot 概念的原因：
 
 | 作用域 | 指令 | 到达消费者 |
 |---|---|---|
@@ -629,13 +639,13 @@ if (const char* dir = mcpp::xpkg_dir("xim", "qemu-riscv"); dir && *dir) {
 | `RunGlobal` | `runner` | 是 |
 | `PackagePrivate` | `include-dir`、`include-dir-after` | 否 |
 
-因此板级支持包以私有方式包含目标的 C 头文件,并把希望被看见的部分导出为一个 C++
-模块。消费者导入该模块,而不继承一条头文件搜索路径。
+因此板级支持包以私有方式包含目标的 C 头文件，把希望被看见的部分导出为一个
+C++ 模块。消费者导入那个模块，不会继承一条头文件搜索路径。
 
 ### 一份完整的 build.mcpp
 
-下面是 QEMU RISC-V `virt` 机器的板级支持包,去掉注释后的全文。这就是该板子构建
-逻辑的全部:
+下面是 QEMU RISC-V `virt` 机器的板级支持包，去掉注释后的全文。这就是该板子
+构建逻辑的全部：
 
 ```cpp
 import mcpp;
@@ -673,30 +683,30 @@ int main() {
 }
 ```
 
-该包的清单只声明模拟器,别无其他:
+该包的清单只声明模拟器，别无其他：
 
 ```toml
 [xlings.workspace]
 "xim:qemu-riscv" = "9.2.4-1"
 ```
 
-在这块板子上链接 `clang_rt.builtins` 不是可选项。picolibc 通过 ryu 格式化浮点值,
-而 ryu 需要 128 位移位,rv64 没有对应指令;缺少 builtins 时链接会在 `__ashlti3`
-与 `__lshrti3` 上失败。一个「64 位除法是否可用」的检查到不了这条判据,因为 rv64gc
-有硬件 `divu`。
+在这块板子上链接 `clang_rt.builtins` 不是可选项。picolibc 经 ryu 格式化浮点值，
+而 ryu 要做 128 位移位，rv64 没有对应的指令；缺了 builtins，链接会在
+`__ashlti3` 和 `__lshrti3` 上失败。一个「64 位除法是否可用」的检查够不到这个
+情形，因为 rv64gc 本身有硬件 `divu`。
 
-包一侧无法探测出当前 mcpp 是否比它所面向的版本更旧:
-`if constexpr (requires { mcpp::runner("x"); })` 作用在未知的限定名上是硬错误而不是
-`false`,语言在此不提供特性探测。引擎为此作了补偿:当 `build.mcpp` 编译失败且错误
-指出某个名字不是 `mcpp` 的成员时,追加一条升级提示。
+包这一侧无法探测出当前的 mcpp 是否比它所面向的版本更旧：
+`if constexpr (requires { mcpp::runner("x"); })` 作用在一个未知限定名上是硬错误，
+不是 `false`，语言在这里不提供特性探测。引擎为此做了补偿：当 `build.mcpp`
+编译失败、且错误指出某个名字不是 `mcpp` 的成员时，追加一条升级提示。
 
 ## 验证范围
 
-本文的命令与输出于 2026-08-20 实测,环境如下:
+本章的命令与输出于 2026-08-20 实测，环境如下：
 
 | 组件 | 版本 |
 |---|---|
-| mcpp | 2026.8.20.1,由本仓库构建 |
+| mcpp | 2026.8.20.1，由本仓库构建 |
 | 宿主 | `x86_64-linux-gnu` |
 | 工具链 | `xim:llvm` 22.1.8 |
 | 目标 C 库 | `xim:picolibc-riscv` 1.8.12 |
@@ -704,22 +714,22 @@ int main() {
 | 板级支持包 | `mcpplibs:riscv-virt-rt` 0.3.0 |
 | 标准库子集 | `mcpplibs:std-freestanding` 0.2.0 |
 
-体积随 mcpp 版本变化:同一个工程在 2026.8.19.4 下实测为 `text 8844`,在 2026.8.20.1
-下为 `text 8572`。因此上文的数字表示量级,而不是固定值。
+体积随 mcpp 版本变化：同一个工程在 2026.8.19.4 下实测为 `text 8844`，在
+2026.8.20.1 下为 `text 8572`。因此上面的数字表示的是量级，不是固定值。
 
-裸机链路只在 Linux 上有持续验证。引擎侧 CI 有一个 `baremetal` job,覆盖四个端到端
-脚本;两个生态包在各自仓库中以 QEMU 真跑 RISC-V 64 与 32 —— 全部在 `ubuntu-24.04`
-上。macOS 与 Windows 宿主预期可用,依据是载荷为交叉编译器且 `xim:qemu-riscv` 发布了
-五个宿主目标的资产,但该预期**没有**测试覆盖。
+裸机链路只在 Linux 上有持续验证。引擎侧 CI 有一个 `baremetal` job，覆盖四个
+端到端脚本；两个生态包各自在自己的仓库里，用 QEMU 真跑 RISC-V 64 位和 32 位——
+全部跑在 `ubuntu-24.04` 上。macOS 与 Windows 宿主预期可用，依据是这份载荷是
+交叉编译器，且 `xim:qemu-riscv` 为五个宿主目标发布了资产，但这份预期**没有**
+测试覆盖。
 
 ## 当前边界
 
 | 边界 | 观察到的行为 |
 |---|---|
-| `std::format`、内建标量类型上的 `std::sort`、以及完整的 `std::string` | 在**链接**期失败并点名未定义符号。libc++ 把这些实体放在编译版库中 —— 标量 `__sort` 的实例化是 `extern template`,没有可用于关闭它们的宏 —— 因此需要为目标编出的 `libc++.a`。该载荷尚未发布。 |
-| 异常与 RTTI | 在整张图上关闭,**除非有包提供 `hosted-standard-library`** —— `mcpplibs/openkal-llvm-runtime` 就通过携带为该目标配置过的 `libc++`、`libc++abi` 与 `libunwind` 做到了这一点。没有这样的包时,`try`/`catch` 在编译期仍不可用。 |
-| 板子覆盖面 | 只有一个板级家族。`riscv32-none-elf` 证明的是 ISA 表为数据,而不是已移植第二台机器。ARM Cortex-M 尚未尝试。 |
-| 替换 C 库 | 自 2026.8.20.2 起可经 `[target.<triple>].sysroot` 表达,而**仅空值一侧经过验证**(零 libc 档)。指向另一份 C 库同样被接受并经同一通道安装,但生态中没有第二份裸机 C 库,该路径未经测试。 |
-| `win32-arm64` 上的 `qemu-riscv` | 上游包未为该宿主发布资产,因此在其上安装会失败。该失败是正确的而非静默的,但该宿主无法运行裸机镜像。 |
-| 生态侧 CI 广度 | 两个生态包各自的 CI 只跑 `ubuntu-24.04`。mcpp-index 的 `tests/examples/` workspace 成员在三个平台上无条件运行且没有能力门,因此需要模拟器与目标 sysroot 的包无法加入其中。这是一个已知的覆盖缺口。 |
-
+| `std::format`、内建标量类型上的 `std::sort`，以及完整的 `std::string` | 在**链接**期失败，点名未定义符号。libc++ 把这些实体放在编译版库里——标量的 `__sort` 实例化是 `extern template`，没有可以关闭它们的宏——因此需要一份为目标编出的 `libc++.a`。这样的载荷尚未发布。 |
+| 异常与 RTTI | 在整张图上关闭，**除非有包提供 `hosted-standard-library`**——`mcpplibs/openkal-llvm-runtime` 携带了为该目标配置过的 `libc++`、`libc++abi` 与 `libunwind`，就是这样做到的。没有这样的包时，`try`/`catch` 在编译期仍不可用。 |
+| 板子覆盖面 | 只有一个板级家族。`riscv32-none-elf` 证明的是 ISA 表为数据，不是「第二台机器已经移植」。ARM Cortex-M 尚未尝试。 |
+| 替换 C 库 | 自 2026.8.20.2 起可经 `[target.<triple>].sysroot` 表达，而**只有空值这一侧**经过验证（零 libc 档）。指向另一份 C 库同样被接受，并经同一通道安装，但生态里没有第二份裸机 C 库，这条路径因此未经测试。 |
+| `win32-arm64` 上的 `qemu-riscv` | 上游包没有为该宿主发布资产，因此在其上安装会失败。这个失败是正确的，不是静默的，但该宿主无法运行裸机镜像。 |
+| 生态侧 CI 广度 | 两个生态包各自的 CI 只跑 `ubuntu-24.04`。mcpp-index 的 `tests/examples/` workspace 成员在三个平台上无条件运行，没有能力门，因此需要模拟器和目标 sysroot 的包无法加入其中。这是一个已知的覆盖缺口。 |
diff --git a/docs/zh/41-devices.md b/docs/zh/41-devices.md
index 1ad8c5224..f940db252 100644
--- a/docs/zh/41-devices.md
+++ b/docs/zh/41-devices.md
@@ -1,67 +1,73 @@
-# 41 —— 抵达一台设备
+# 41 —— 在设备上运行
 
-**读者:**产物不在构建它的那台机器上运行的人 —— 一块板子、一个模拟器,或者一台
-远程主机。
+**读者：** 产物不在构建它的那台机器上运行的所有人——一块板子、一个模拟器，
+或者一台远程主机。
 
-**本章回答的那一个问题:**这样的产物怎样被运行与测试,以及一个包供给什么,才能让
-一条命令抵达它。
+**本章回答的那一个问题：** 这样的产物怎样被运行与测试，以及一个包供给
+什么，才能让一条命令抵达它。
 
-**不在这里:**这个目标本身怎么构建,那是 [40 —— 裸机](40-baremetal.md);以及 mcpp
-认为什么是一个测试,那是 [08 —— 测试](08-testing.md)。
+**不在这里：** 这个目标本身怎么构建，那是 [40 —— 裸机](40-baremetal.md)；
+以及 mcpp 认为什么是一个测试，那是 [08 —— 测试](08-testing.md)。
 
-本文规定 mcpp 如何执行一个运行在构建机器之外的产物、包如何提供抵达它的其他方式,
-以及工程如何在模拟器与真实硬件之间选择。
+本文规定 mcpp 如何执行一个运行在构建机器之外的产物、包如何提供抵达它的
+其它方式，以及工程如何在模拟器与真实硬件之间选择。
 
-相关文档:[40 - 裸机与 freestanding 目标](40-baremetal.md) · [30 - build.mcpp](30-build-mcpp.md)
-· [50 - 机器输出](50-machine-output.md)。
+相关文档：[40 —— 裸机与 freestanding 目标](40-baremetal.md) 覆盖这一机制
+最常应用的那些目标；[30 —— build.mcpp](30-build-mcpp.md) 是包所讲的指令
+协议的参考；[50 —— 机器输出](50-machine-output.md) 是调试器客户端或 IDE
+使用的接口。
 
-## 一条命令,加具名的例外
+## 一条命令，加具名的例外
 
-无法在构建机器上运行的产物需要有东西站在它前面。那个东西叫 **runner**:包提供、
-工具执行的一段 argv,产物被追加或替换 `{}`。
+无法在构建机器上运行的产物需要有东西站在它前面。那个东西叫 **runner**：
+包提供、工具执行的一段 argv，产物被追加或替换 `{}`。
 
 ```bash
-mcpp run                        # 默认 runner
-mcpp run --runner flash         # 具名的
-mcpp run --list-runners         # 这个工程提供了哪些
-mcpp why runners                # 同一份清单,与其余解析结果并列
-mcpp run --features hardware    # 同一块板,换一条路到达
+mcpp run                        # the default runner
+mcpp run --runner flash         # a named one
+mcpp run --list-runners         # what this project supplies
+mcpp why runners                # the same list, beside everything else resolved
+mcpp run --features hardware    # the same board, reached the other way
 ```
 
-`mcpp run` 接受 `--features` 与 `--profile`,与 `mcpp build`、`mcpp test` 同轴。
-上面那一行因此是一条**命令**而不是一次清单改动:板级包把两种环境表达成 feature,
-选其中之一与选任何别的 feature 是同一个动作。
+`mcpp run` 接受 `--features` 与 `--profile`，与 `mcpp build`、
+`mcpp test` 同轴。这正是上面那一行是一条**命令**而不是一次清单改动的
+原因：板级包把两种环境表达成 feature，选其中之一与选任何别的 feature
+是同一个动作。
 
-**`mcpp run` 覆盖了常见情形的全部,真实硬件也一样。** 在设备上,「运行一个程序」
-意味着写进去、复位、接上它的输出、读回退出状态 —— 这是**一条**命令
-(`probe-rs run`、`qemu-system-* -kernel`),不是几条。因此板级包把它作为**默认**
-runner,于是开发者从模拟器换到真板时,敲的命令不变。
+`mcpp run` 覆盖了常见情形的全部，真实硬件也不例外。在设备上，「运行一个
+程序」意味着写进去、复位、接上它的输出、读回退出状态——这是**一条**
+命令（`probe-rs run`、`qemu-system-* -kernel`），不是几条。因此板级包把
+它作为**默认** runner，于是开发者从模拟器换到真实板子时，敲的命令不变。
 
-具名 runner 服务剩下的部分:只写不跑、看串口、起调试服务端、擦片、部署但不启动。
+具名 runner 服务剩下的部分：只写不跑、观察一路串口输出、起一个调试
+服务端、擦除一个分区、部署但不启动。
 
 **引擎不认识任何 runner 名字。** `flash`、`serve`、`deploy`、`submit`、
-`logcat` 对它一样陌生:它只知道「包可以提供具名 runner」这件事,然后执行它找到的
-argv。**引擎里若有一份固定的名字表,就等于由引擎决定哪些领域可被表达。**
+`logcat` 对它一样陌生：它只知道包可以提供具名 runner 这件事，然后执行
+它找到的 argv。引擎里若有一份固定的名字表，就等于由引擎决定哪些领域可
+被表达。
 
 ## 包的供给内容
 
 ```cpp
-mcpp::runner("qemu-system-arm");        // 默认:一次一个 token
+mcpp::runner("qemu-system-arm");        // the default: argv token by token
 mcpp::runner("-machine"); mcpp::runner("mps2-an385"); …
 
-mcpp::runner("flash", "probe-rs");      // 具名 runner
+mcpp::runner("flash", "probe-rs");      // a named runner
 mcpp::runner("flash", "download"); …
 
-mcpp::runner_longlived("monitor");      // 没有自然终点
-mcpp::run_exclusive();                  // 这个目标的运行不能重叠
+mcpp::runner_longlived("monitor");      // no natural end
+mcpp::run_exclusive();                  // this target's runs cannot overlap
 ```
 
-**写程序名,不要写路径。** mcpp 会定位它:先找**图中任何一个包**在
-`[xlings.workspace]` 里声明的载荷的 `bin/`(消费工程优先,然后是它的依赖),再找 `PATH`。
-板级包正是那个知道「哪个模拟器或探针能抵达这台机器」的东西,所以由它声明,
-**消费者什么都不用声明**。用 `mcpp::xpkg_dir` 拼绝对路径是多余的,而且引入了一个
-失败模式 —— **声明不是安装**,查询可能返回空,于是没有配置任何 runner 而没有任何
-话说明原因。写程序名则让 mcpp 报出它究竟搜过哪些目录。
+**写程序名，不要写路径。** mcpp 会定位它：先找**图中任何一个包**在
+`[xlings.workspace]` 下声明的载荷的 `bin/`（消费工程优先，然后是它的
+依赖），再找 `PATH`。板级包正是那个知道哪个模拟器或探针能抵达这台机器
+的东西，所以由它自己声明该载荷，**消费者什么都不用声明**。用
+`mcpp::xpkg_dir` 拼出绝对路径是多余的，而且会引入一个失败模式——声明
+不是安装，查询可能返回空，于是没有配置任何 runner，也没有任何话说明
+原因。写程序名则让 mcpp 能报出它究竟搜过哪些目录。
 
 ## 工程的覆盖项
 
@@ -74,80 +80,90 @@ flash   = ["probe-rs", "download", "--verify", "--chip", "STM32L475VG", "{}"]
 monitor = ["probe-rs", "attach", "--chip", "STM32L475VG"]
 ```
 
-优先级是通常那个:工程作者写的胜过依赖提供的,且覆盖会被报告。一个名字只允许一个
-依赖提供,第二个是点名两个包的错误。
+优先级是通常那一个：工程作者写的胜过依赖提供的，而覆盖会被报告，不会
+被默默应用。同一个名字只允许一个依赖提供，出现第二个是一个点名两个包的
+错误。
 
 ## runner 收到的内容
 
-runner 收到一段 argv —— 它自己的 token,产物路径被追加或替换 `{}` —— 以及一个环境
-变量 `MCPP_RUNTIME_FILES`。`mcpp run` 与 `mcpp test` 启动的每一个 runner 都会收到
-这个变量,默认 runner 与具名 runner 相同。`mcpp run --no-runner` 不启动 runner,
-也不设置它。
+runner 收到一段 argv——它自己的 token，产物路径被追加或替换 `{}`——
+以及一个环境变量 `MCPP_RUNTIME_FILES`。`mcpp run` 与 `mcpp test` 启动
+的每一个 runner 都会收到这个变量，默认 runner 与具名 runner 一样。
+`mcpp run --no-runner` 不启动任何 runner，也不设置它。
 
-`MCPP_RUNTIME_FILES` 指向一个文件,列出产物从自己所在目录读取或加载的东西:
-`[runtime] deploy` 与 `deploy_files` 的条目,以及构建链接的共享库。每个文件一行:
+`MCPP_RUNTIME_FILES` 指向一个文件，列出产物从自己所在目录读取或加载的
+东西：`[runtime] deploy` 与 `deploy_files` 的条目，以及构建链接的共享库。
+每个文件一行：
 
 ```
 data/data.txt<TAB>/abs/project/target/<triple>/<fp>/bin/data/data.txt
 libfw.so<TAB>/abs/project/target/<triple>/<fp>/bin/libfw.so
 ```
 
-第一个字段是相对于产物所在目录的目的路径,分隔符为 `/`;在子目录中发现的测试程序,
-其目的路径以 `../` 开头。第二个字段是该文件在输出树中的绝对路径。两者以 TAB 分隔。
-每次启动 runner 时这个文件都存在,没有需要携带的东西时为空;以 `--format` 运行的
-可分发物收到空文件,因为可分发物自带其文件。
+第一个字段是相对于产物所在目录的目的路径，分隔符为 `/`；对于在子目录中
+发现的测试程序，它以 `../` 开头。第二个字段是该文件在输出树中的绝对
+路径。两者以 TAB 分隔。每次启动 runner 时这个文件都存在，没有需要携带
+的东西时为空；以 `--format` 运行的可分发物收到的是空文件，因为可分发物
+自带其文件。
 
-就地执行产物的 runner 忽略这个变量。把产物移走的 runner —— 移到设备、容器或远程
-主机 —— 把列出的每个文件复制到被移走的产物旁边对应的目的路径。
+就地执行产物的 runner 会忽略这个变量。把产物移走的 runner——移到设备、
+容器或远程主机——会把列出的每个文件复制到被移走产物旁边对应的目的
+路径。
 
 ## 运行一个可分发物
 
-`mcpp run --format <f>` 打包可分发物 `<f>` 并运行它。不带 `--runner` 时,若图或
-清单提供了名为 `<f>` 的 runner,就由它抵达,否则由默认 runner 抵达:
+`mcpp run --format <f>` 打包可分发物 `<f>` 并运行它。不带 `--runner`
+时，若图或清单提供了名为 `<f>` 的 runner，就由它抵达，否则由默认
+runner 抵达：
 
 ```cpp
-mcpp::runner("app", "<tool>");          // 包以格式名命名 runner
+mcpp::runner("app", "<tool>");          // a package names a runner after its format
 ```
 
 ```bash
-mcpp run --format app                   # 经名为 `app` 的 runner
-mcpp run --format app --runner other    # 显式的 --runner 仍然优先
+mcpp run --format app                   # through the runner named `app`
+mcpp run --format app --runner other    # a typed --runner still wins
 ```
 
-目录形式的可分发物(例如应用包)不被直接执行。没有 runner 抵达它时,
-`mcpp run --format <f>` 在启动任何东西之前拒绝,退出状态为 `126`,并点名能抵达它的
-runner `<f>` 以及声明它的清单表。
+目录形式的可分发物（例如应用包）不会被直接执行。没有 runner 能抵达它
+时，`mcpp run --format <f>` 会在启动任何东西之前拒绝，退出状态为
+`126`，并点名能抵达它的 runner `<f>` 以及本该声明它的清单表。
 
-## 终止由声明决定,不由推断
+## 终止由声明决定，不由推断
 
 | | 含义 |
 |---|---|
-| 默认 | 运行到结束;退出码即判决 |
-| `runner_longlived(name)` | 没有自然终点;由操作者结束 |
+| default | runs to completion; the exit code is the verdict |
+| `runner_longlived(name)` | has no natural end; the operator ends it |
 
-`openocd -c "program image.elf verify reset exit"` 会终止,`openocd -c "init"`
-不会,两者拼写直到包所选的那个参数为止都一样。没有任何 argv 能表达这个区别,而引擎
-也没有一份名字表可供推断 —— 所以由包陈述。
+`openocd -c "program image.elf verify reset exit"` 会终止，
+`openocd -c "init"` 不会，两者的拼写直到包所选的那个参数为止都一样。
+没有任何 argv 能表达这个区别，引擎也没有一份名字表可供推断——所以由包
+陈述。
 
-`mcpp run --runner debug` 启动一个**服务端**,到此为止。连上去的客户端是用户的
-调试器或 IDE,它通过机器输出协议获得所需。
+`mcpp run --runner debug` 启动一个**服务端**，到此为止。连上去的客户端
+是用户的调试器或 IDE，它通过机器输出协议获得所需信息。
 
 ## 不能重叠的运行
 
-`mcpp test` 在工作者池上跑测试二进制。一块板配一个探针、一张 GPU、一个串口、
-一个单席位 license 的工具,都一次只容一个使用者;两个工作者去够它不会干净地失败
-—— 它们互相穿插,产生的判决不描述其中任何一个测试。
+`mcpp test` 在一个工作者池上运行测试二进制。一块板配一个探针、一张
+GPU、一个串口，或一个单席位授权的工具，都一次只容一个使用者；两个工作
+者同时去够它不会干净地失败——它们会互相穿插，产生的判决不描述其中任何
+一个测试。
 
-包用 `mcpp::run_exclusive()` 说出这件事,`mcpp test` 于是串行化。工程永远不必记得
-`-j1`。
+包用 `mcpp::run_exclusive()` 说出这件事，`mcpp test` 随之串行化。工程
+永远不必记得 `-j1`。
 
-**按性质命名而不按硬件命名**:这里没有一处是关于「设备」的。
+按性质命名而不按硬件命名：这里没有一处是关于「设备」的。
 
 ## 模拟器与硬件是同一个包
 
-经模拟器抵达的板,与经调试探针抵达的同一块板,差别只在 runner 的 argv,别无其他。
-链接脚本、启动代码、内存映射与导出的模块都是同一块板。为变化几个字符串而发布两个
-包,会把这一切复制一遍并让副本漂移。
+经模拟器抵达的板子，与经调试探针抵达的同一块板子，差别只在 runner 的
+argv，别无其它。链接脚本、启动代码、内存映射与导出的模块都是同一块板
+子。为了变化几个字符串而发布两个包，会把这一切复制一遍，并让两份副本
+漂移开来。
+
+因此，这个选择是一个包的一项 feature：
 
 ```toml
 [features]
@@ -157,17 +173,20 @@ hardware = {}
 ```
 
 ```cpp
-if (mcpp::has_feature("hardware")) {
-    for (auto a : {"probe-rs","run","--chip","STM32L475VG"})
-        mcpp::runner(a);                       // 移动的是**默认**
-    for (auto a : {"probe-rs","gdb","--chip","STM32L475VG"})
-        mcpp::runner("debug", a);
-    mcpp::runner_longlived("debug");
-    mcpp::run_exclusive();
-} else {
-    for (auto a : {"qemu-system-arm","-machine","mps2-an385","-nographic",
-                   "-semihosting","-no-reboot","-kernel"})
-        mcpp::runner(a);
+int main() {
+    if (mcpp::has_feature("hardware")) {
+        for (auto a : {"probe-rs", "run", "--chip", "STM32L475VG"})
+            mcpp::runner(a);                       // the DEFAULT moves
+        for (auto a : {"probe-rs", "gdb", "--chip", "STM32L475VG"})
+            mcpp::runner("debug", a);
+        mcpp::runner_longlived("debug");
+        mcpp::run_exclusive();
+    } else {
+        for (auto a : {"qemu-system-arm", "-machine", "mps2-an385", "-nographic",
+                       "-semihosting", "-no-reboot", "-kernel"})
+            mcpp::runner(a);
+    }
+    return 0;
 }
 ```
 
@@ -176,18 +195,20 @@ if (mcpp::has_feature("hardware")) {
 cortex-m-rt = { version = "0.1.0", features = ["hardware"] }
 ```
 
-**消费者的命令不变。** 所选环境不提供的 runner 保持缺席:模拟器没有调试探针,
-于是在 emulator 之下 `mcpp run --runner debug` 报告没有这个 runner,并列出有哪些。
+消费者的命令不变。所选环境不提供的 runner 保持缺席：模拟器没有调试
+探针，于是在 emulator feature 下 `mcpp run --runner debug` 会报告没有
+这个 runner，并列出确实存在的那些。
 
-**这不需要任何引擎机制。** 引擎读 runner,对模拟器与探针一无所知;
-`mcpp::has_feature` 本来就在。**一个问题不必新增任何东西就能回答,是分层按规定在
-起作用。**
+这不需要任何引擎机制。引擎只读 runner，对模拟器或探针一无所知；
+`mcpp::has_feature` 本来就已经存在。一个问题不必新增任何东西就能回答，
+正是分层按其规定在起作用。
 
 ## 当前边界
 
-- **同一个 runner 名字只允许一个依赖提供。** 出现第二个是错误,并会点名两个包;
-  没有任何「按顺序取胜」的规则。
-- 所选环境没有提供的 runner **就是不存在**。在 emulator feature 下没有调试探针,
-  于是 `mcpp run --runner debug` 会报告没有这个 runner,并列出确实存在的那些。
-- 终止方式是被声明的,不是被推断的。一个不声明自己长驻的 runner,会被一直等到
-  操作者结束它。
+- **同一个 runner 名字只允许一个依赖提供。** 出现第二个是一个点名两个
+  包的错误；没有任何「按顺序取胜」的规则。
+- 所选环境没有提供的 runner **就是不存在**。在 emulator feature 下没有
+  调试探针，于是 `mcpp run --runner debug` 会报告没有这个 runner，并
+  列出确实存在的那些。
+- 终止方式是被声明的，不是被推断的。一个不声明自己长驻的 runner，会被
+  一直等到操作者结束它。
diff --git a/docs/zh/42-heterogeneous-builds.md b/docs/zh/42-heterogeneous-builds.md
index e6495b30e..33bfe47a4 100644
--- a/docs/zh/42-heterogeneous-builds.md
+++ b/docs/zh/42-heterogeneous-builds.md
@@ -1,193 +1,198 @@
 # 42 —— 异构硬件构建
 
-**读者:**把程序的一部分编译到 GPU 或 AI 加速器上的人。
+**读者：**把程序的一部分编译到 GPU 或 AI 加速器上的人。
 
-**本章回答的那一个问题:**设备代码怎样被编译并链接进一个普通程序,以及一个预建
+**本章回答的那一个问题：**设备代码怎样被编译并链接进一个普通程序，以及一个预建
 产物怎样声明它能在哪些设备上运行。
 
-**不在这里:**编写驱动设备编译器的那条规则,那是
-[31 —— 编写规则包](31-authoring-a-rule-package.md);以及抵达设备把它跑起来,那是
+**不在这里：**编写驱动设备编译器的那条规则，那是
+[31 —— 编写规则包](31-authoring-a-rule-package.md)；抵达设备并把它跑起来，那是
 [41 —— 抵达一台设备](41-devices.md)。
 
-GPU 与 AI 加速器目标,以及宿主/设备混合编译:mcpp 如何构建设备代码,以及一个预建产物如何
-声明它能在哪些设备上运行。
+GPU 与 AI 加速器目标，以及宿主/设备混合编译：mcpp 如何构建设备代码，以及一个预建
+产物如何声明它能在哪些设备上运行。
 
-## 支持范围
+## 支持面
 
-一个构建点名它面向哪些设备后端,而且**可以点多个**:
+一次构建点名它面向的设备后端，而且**可以点多个**：
 
 ```toml
 [build]
 accel = "cuda12.9+{sm_89}, vulkan1.2"
 ```
 
-`accelerator` 是目标侧的一个**集合**,所以这个构建里 `cfg(accelerator = "cuda")` 与
-`cfg(accelerator = "vulkan")` 同时为真,每个后端的规则包各编各的设备单元,一个产物把
-它们都带上。逗号分隔的是这个集合里的**条目**;空格分隔的是**同一条目内的修饰符**
-(`cuda12.9+{sm_89} ptx>=89` 是一个后端加一组架构再加一条 PTX 下界)。源码集合怎么写
-见下面「一个构建里的多个后端」。
+`accelerator` 是目标侧的一个**集合**，因此这次构建里 `cfg(accelerator = "cuda")`
+与 `cfg(accelerator = "vulkan")` 同时为真，每个后端的规则包各编各的设备单元，
+一个产物把它们全部带上。逗号分隔的是这个集合里的条目；空格分隔的是**同一条目
+内部的修饰符**（`cuda12.9+{sm_89} ptx>=89` 是一个后端，加一组架构，再加一条
+PTX 下界）。源码集合具体怎么写，见下文「一次构建里的多个后端」。
 
-`accelerator = "none"` 是**空集** —— 恰好在本次构建完全没有命名加速器时为真。它是
-词表里唯一一个不是后端名字的取值,而它之所以存在,是因为词表的其余部分是**开放**的:
-一个会增长的集合不能靠列举来否定。见下面「CPU 回退」。
+`accelerator = "none"` 是**空集**——恰好在这次构建完全没有点名任何加速器时
+为真。它是这个词表里唯一一个不是后端名字的取值，而它之所以存在，是因为词表的
+其余部分是**开放**的：一个会不断增长的集合，不能靠列举来否定。见下文
+「CPU 回退」。
 
-今天有规则包的编程模型是五个 —— CUDA、HIP、SYCL、Vulkan/SPIR-V、Ascend C ——
-「各条 lane」那张表写明每个驱动哪个编译器、需要哪些载荷。引擎里不持有任何厂商名字,
-所以第六个是**一个包**而不是一次引擎改动。
+今天带有规则包的编程模型有五个——CUDA、HIP、SYCL、Vulkan/SPIR-V 与
+Ascend C——「各条 lane」那张表写明了每一个驱动哪个编译器、需要哪些载荷。引擎
+本身不持有任何厂商的名字，所以第六个只是**一个包**，而不是一次引擎改动。
 
-## 两种形态,以及两者共用的机制
+## 两种形态，以及两者共用的机制
 
-加速器工具链有两种形态。它们描述的是**一个工具链通常怎么被使用**,不是一个构建系统
-需要几套机制。
+加速器工具链有两种形态。它们描述的是一个工具链**通常怎样被使用**，不是一个
+构建系统需要几套机制。
 
-**岛(island)** 把设备代码放在单独的编译单元里,由单独的编译器编译。CUDA、HIP、
-Ascend C 与 Metal 都是这种形态。设备编译器产出一个目标文件(着色语言则产出运行期
-资源),汇入普通的链接。
+**岛（island）**把设备代码放进独立的编译单元，由独立的编译器编译。CUDA、HIP、
+Ascend C 与 Metal 都是这种形态。设备编译器产出一个目标文件（着色语言则产出
+一份运行期资源），汇入普通的链接。
 
-**整目标(whole-target)** 把设备代码放在普通 `.cpp` 里,整个目标由一个能 offload 的
-编译器编译。SYCL、OpenMP offload 与 stdpar 通常这样用。
+**整目标（whole-target）**把设备代码放进普通的 `.cpp` 里，由一个能够 offload
+的编译器编译整个目标。SYCL、OpenMP offload 与 stdpar 通常这样用。
 
-mcpp 只实现**一套**机制 —— 岛。这是关于**设计**的陈述,不是关于支持多少后端的:
-一个整目标工具链是**经由**岛、而不是在它旁边被接进来的,所以支持它的代价是一个规则包,
-而不是第二套机制。SYCL 之所以在已发布的那一组里,正是这个原因。
+mcpp 只实现**一套**机制——岛。这是一句关于**设计**的陈述，不是关于支持多少
+后端的陈述：一个整目标工具链是**经由**岛被接进来的，不是在它旁边另立一套，因此
+支持它的代价是一个规则包，而不是第二套机制。SYCL 正因为这个原因被列在已发布的
+那一组里。
 
-**SYCL 的分得开。** 一个 SYCL kernel 是 `submit` 里的一个 lambda,所以一个工程可以
-按约定把它们全部收进各自的编译单元,而 `.sycl` 就是这条约定的可检查形式。只有这些
-单元交给 SYCL 编译器,目标的其余部分由工程自己的工具链编译 —— `examples/09-heterogeneous/sycl`
-实测如此:`app.cppm` 与 `main.cpp` 由 mcpp 的 clang 编,`saxpy.sycl` 由 dpcpp 载荷的编。
+**SYCL 的设备代码分得开。**一个 SYCL kernel 是 `submit` 里的一个 lambda，因此
+一个工程可以按约定把它们全部收进各自的编译单元，而 `.sycl` 就是这条约定的可
+检查形式。只有这些单元交给 SYCL 编译器，目标的其余部分由工程自己的工具链编译
+——`examples/09-heterogeneous/sycl` 实测正是如此：`app.cppm` 与 `main.cpp` 由
+mcpp 的 clang 编译，`saxpy.sycl` 由 dpcpp 载荷的编译器编译。
 
-**OpenMP offload 与 stdpar 的分不开。** `#pragma omp target` 与
-`std::execution::par_unseq` 出现在普通代码里任意的调用点上;没有可搬的单元,也就没有
-可施加的岛。「mcpp 未实现的那一种形态」现在指的正是这两个,而这条边界是**模型本身的
-性质**,不是本文档志向上的缺口。
+**OpenMP offload 与 stdpar 的设备代码分不开。**`#pragma omp target` 与
+`std::execution::par_unseq` 出现在普通代码里任意的调用点上，没有可搬动的单元，
+也就没有可施加的岛。「mcpp 未实现的那种形态」如今指的正是这两个，而这条边界是
+**模型本身的性质**，不是本章志向上的缺口。
 
-两个值得直说的后果:
+两个值得直说的后果：
 
-* 一个 kernel 写在 `.cpp` 里的既有 SYCL 工程**不能原样构建**。它的设备单元要先搬进
-  `.sycl` —— 那是一次改名加一条接缝,不是重写。
-* 一个扩展名只有一个含义。让收窄的 glob 去承载 `.cpp`,同一个名字就会因为哪条 glob
-  先匹配而选中两个不同的编译器;接缝之所以可读,正是因为文件名说明了一个单元位于它
-  的哪一侧。
+* 一个既有的 SYCL 工程，如果 kernel 写在 `.cpp` 里，**不能原样构建**。它的
+  设备单元要先搬进 `.sycl`——那是一次改名加一条接缝，不是重写。
+* 一个扩展名只对应一个含义。让收窄过的 glob 去承载 `.cpp`，会让同一个名字因为
+  哪条 glob 先匹配而选中两个不同的编译器；接缝之所以可读，正是因为文件名说明了
+  一个单元位于接缝的哪一侧。
 
 ## 设备编译单元
 
-由另一个编译器消费的语言写成的源文件是**设备编译单元**。mcpp 据此分类并相应处理:
-它从不被扫描 import,也从不产出 BMI —— 因为没有任何设备编译器接受 C++20 modules。
+由另一个编译器消费的语言写成的源文件，是一个**设备编译单元**。mcpp 据此分类
+并相应处理它：它从不被扫描 import，也从不产出 BMI——因为没有任何设备编译器接受
+C++20 modules。
 
-判据是编译器,不是语言(下表为 2026.9.5.3+;在此之前只有 `.cu` 与 `.hip`)。`.sycl`
-正是这一区别变得可见的地方:它的内容就是普通 C++,文件里没有任何东西会告诉读者别的。
-使它成为设备单元的是「它交给一个带设备后端的编译器」—— 一个 mcpp 不驱动、且不接受
-C++20 modules 的编译器。
+判据是编译器，不是语言（下表为 2026.9.5.3+；在此之前只有 `.cu` 与 `.hip`）。
+`.sycl` 正是这条区分变得可见的地方：它的内容就是普通 C++，文件里没有任何东西
+会告诉读者别的。使它成为设备单元的，是「它交给一个带设备后端的编译器」——一个
+mcpp 不驱动、也不接受 C++20 modules 的编译器。
 
 | 语言 | 扩展名 |
 |---|---|
 | CUDA、HIP | `.cu`、`.hip` |
-| SYCL | `.sycl`(2026.9.6.1+) |
-| Ascend C | `.asc`、`.cce`(2026.9.6.5+) |
-| GLSL(按 stage) | `.comp`、`.vert`、`.frag`、`.geom`、`.tesc`、`.tese`、`.mesh`、`.task`、`.rgen`、`.rint`、`.rahit`、`.rchit`、`.rmiss`、`.rcall` |
-| GLSL(无 stage) | `.glsl` |
+| SYCL | `.sycl` (2026.9.6.1+) |
+| Ascend C | `.asc`、`.cce` (2026.9.6.5+) |
+| GLSL（按 stage） | `.comp`、`.vert`、`.frag`、`.geom`、`.tesc`、`.tese`、`.mesh`、`.task`、`.rgen`、`.rint`、`.rahit`、`.rchit`、`.rmiss`、`.rcall` |
+| GLSL（无 stage） | `.glsl` |
 | HLSL | `.hlsl` |
 | OpenCL C | `.cl` |
 | Metal Shading Language | `.metal` |
 
-表外的扩展名若出现在 `[build] sources` 中会被点名拒绝 —— 这正是「这张表是一张表」
-的含义:mcpp 对该文件没有任何规则,它的目标文件不会被任何东西链接,构建下去只会
-在更晚、更不清楚的地方失败。
+表外的扩展名若出现在 `[build] sources` 中，会被点名拒绝——这正是「这张表是一
+张表」的含义：mcpp 对该文件没有任何规则，它的目标文件不会被任何东西链接，
+构建下去只会在更晚、更含糊的地方失败。
 
-上表是 mcpp **不需要被告知**就知道的那些:在「包可以自己声明」之前就已经支持的语言。
-规则包通过 `[features].<f>.device_extensions`(见
-[04 — mcpp.toml](04-mcpp-toml.md) §2.8)向它增补,而这正是**一门新设备语言到达的方式**
-—— 不动引擎,也不需要发一版引擎。Slang 是第一个:`.slang` 不在上表里,由
-`mcpp:plugins` 的 `rules-slang` 声明。
+上表是 mcpp **不需要被告知**就已经知道的那些：在「包可以自己声明」之前就已经
+支持的语言。规则包经 `[features].<f>.device_extensions`（见
+[04 —— mcpp.toml](04-mcpp-toml.md) §2.8）向它增补，而这正是一门**新设备语言**
+到达的方式——不改引擎，也不需要发一版新引擎。Slang 是第一个：`.slang` 不在上表
+里，由 `mcpp:plugins` 的 `rules-slang` 声明。
 
+`.glsl` 不携带 stage 信息。glslang 从扩展名推导 stage，因此拒绝一个无 stage 的
+名字是规则包的事——那条消息属于那里，这张表因此不需要知道哪些扩展名指定了
+stage。
 
-`.glsl` 不携带 stage。glslang 从扩展名推导 stage,因此拒绝一个无 stage 的名字是
-规则包的事 —— 那条消息属于那里,这张表因此不需要知道哪些扩展名指定了 stage。
+`.cuh` 与 `.hiph` 被分类为头文件。它们不被编译，但改动其一可以改变构建图应有的
+形状，因此与其它任何头文件一样会使快路径失效。
 
-`.cuh` 与 `.hiph` 被分类为头文件。它们不被编译,但改动其一可以改变构建图应有的形状,
-因此与任何其它头文件一样会使快路径失效。
+设备扩展名**不在**默认的 source glob 中。一个把 `.cu` vendored 进来、却在别处
+构建它的包，不应当在 mcpp 升级后突然开始编译这个文件——那是它的作者一旦那个
+版本发出去就无法修复的破坏。设备源文件必须被显式点名才会进入构建。
 
-设备扩展名**不在**默认 source glob 中。一个 vendored 了 `.cu`、但在别处构建它的包,
-不应当在 mcpp 升级后突然开始编译它 —— 这是它的作者无法修复的破坏,因为那个版本的
-tarball 已经发出去了。设备源文件必须被显式点名。
+## 接缝（seam）
 
-## 接缝(seam)
+设备编译单元不能 import 模块，因此它与工程其余部分的边界是一个头文件。消费者
+看不到这个头文件：一个模块在自己的 global module fragment 里包含它，并导出
+一份 C++ 接口，下游一律 import 该模块。
 
-设备编译单元不能 import 模块,因此它与工程其余部分的边界是一个头文件。消费者看不到
-这个头文件:一个模块在其 global module fragment 里包含它,并导出 C++ 接口,
-下游一律 import 该模块。
+这个模块值得起一个名字，叫**接缝**，因为它存在的理由不是模块边界本身。它是
+唯一一处可以在不改动任何消费者的前提下替换掉下层的岛（换成 HIP，换成 CPU
+回退）的位置，也是 `cfg(accelerator = ...)` 唯一有落点的位置。一个没有接缝的
+工程，没有任何边界可供替换后端。
 
-这个模块值得叫做**接缝**,因为它存在的理由不是模块边界。它是**唯一**一处可以在不改动
-任何消费者的前提下替换下层的岛(换成 HIP、换成 CPU 回落)的位置,也是
-`cfg(accelerator = ...)` 唯一有落点的位置。没有接缝的工程,没有任何边界可供替换后端。
+接口上的两条约束来自编译器本身的事实，不是审美。它应当是 `extern "C"`，因为
+设备编译器驱动的是一个 mcpp 没有选择的宿主编译器，两侧因此不共享 C++ ABI。岛
+本身应当避开标准库，因为一个链接了 libstdc++ 的岛，会把第二份 C++ 运行时放进
+一个自身运行时来自 mcpp 工具链的程序里。
 
-接口上的两条约束来自编译器的事实,而不是审美。它应当是 `extern "C"`,
-因为设备编译器驱动的是一个 mcpp 没有选择的宿主编译器,两侧因此不共享 C++ ABI。
-岛本身应当避开标准库,因为一个链接了 libstdc++ 的岛,会把第二份 C++ 运行时放进一个
-自身运行时来自 mcpp 工具链的程序里。
+#### 那个 `extern "C"` 头文件，以及省掉它的代价
 
+不是因为语言要求。接缝可以自己声明入口点，岛自己定义它，一个头文件都不写，
+照样编得过、链得上、跑得起来。
 
-#### 那个 `extern "C"` 头文件,以及省掉它的代价
-
-语言上不是。接缝可以自己声明入口点、岛自己定义它,一个头文件都不写,照样编得过、链得上、
-跑得起来。
-
-头文件买来的是**那份声明只有一份**。没有它就有两份副本分属两个编译器,而它们可以静默地
-不一致:
+头文件买来的是「那份声明只存在一份」。没有它，就有两份副本分属两个编译器，
+而它们可以静默地不一致：
 
 ```cpp
-// 接缝里
+// the seam
 extern "C" int saxpy_device(float a, const float* x, const float* y,
                             float* out, unsigned n);
-// 岛里,在有人把计数加宽之后
+// the island, after someone widened the count
 extern "C" int saxpy_device(float a, const float* x, const float* y,
                             float* out, std::size_t n);
 ```
 
-C 语言链接不做名字修饰,所以这两个是同一个符号。链接是干净的,而两侧各按自己的 ABI 解释
-参数:没有编译错误,没有链接错误,只有一次读过了参数末尾的运行。同样的错误发生在 C++
-边界上会被名字修饰在链接期挡下。
+C 语言链接不做名字修饰，所以这两个是同一个符号。链接是干净的，而两侧各按自己
+的 ABI 解释参数：没有编译错误，没有链接错误，只有一次读过了参数末尾的运行。
+同样的错误发生在 C++ 边界上，会被名字修饰在链接期挡下。
 
-所以**迫使这条边界必须是 `extern "C"` 的那条性质 —— 两侧不共享 C++ ABI —— 正是让声明
-分裂无法被发现的同一条性质**。一个普通头文件是模块和设备编译器都能读的最小共同物,这就
-是它存在的全部理由。
+所以，**迫使这条边界必须是 `extern "C"` 的那条性质——两侧不共享 C++ ABI——
+正是让声明分裂无法被发现的同一条性质**。一个普通头文件是模块和设备编译器都
+能读的最小共同物，这就是它存在的全部理由。
 
-三条替代都试过,没有一条能去掉它:岛不能包含接缝(`.cppm` 不是 nvcc 解析的东西);从某个
-单一来源生成头文件就是头文件多加一步;而模块的 global module fragment 什么都不导出,即使
-岛的编译器能读 BMI 也够不到。
+三条替代都被考虑过，没有一条能去掉它：岛不能包含接缝（`.cppm` 不是 nvcc 解析
+的东西）；从某个单一来源生成头文件，不过是头文件多加一道工序；而模块的
+global module fragment 什么都不导出，即使岛的编译器能读 BMI，也够不到它。
 
-### 两类 lane,只有一类的接口是生成的
+### 两类 lane，只有一类的接口是生成的
 
-上面那个接缝是手写的,而 shader 那条 lane 的对应物是生成的。这不是不一致 ——
+上面那个接缝是手写的，而 shader 那条 lane 的对应物是生成的。这不是不一致——
 两条 lane 承载的东西不同。
 
-**设备编译单元是代码,而它上面那层接缝是一个设计决定** —— 有哪些函数、什么类型、
-失败怎么报。没有任何生成器能把这个决定做好,所以 CUDA、HIP、SYCL 与 Ascend C 有一个
-手写的接缝,下游一律写 `import app.saxpy`。
+**设备编译单元是代码，而它上面那层接缝是一个设计决定**——有哪些函数、什么
+类型、失败时怎么报。没有任何生成器能把这个决定做好，所以 CUDA、HIP、SYCL 与
+Ascend C 都有一个手写的接缝，下游一律写 `import app.saxpy`。
 
-**而接缝**底下**那个 `extern "C"` 边界不是设计决定。** 它是每个入口点的签名被第二次
-写出来,写在一个「不一致看不见」的位置上:C 语言链接不做名字修饰,而设备岛与它的宿主
-回落**永不同链**。`mcpp.tools.island` 从两个实现里读出被标记的声明,写出那个头文件和
-它之上的模块,于是签名只存在一次,而两个半边如果声明不一致,会在两份文本同时摆在生成器
-面前的那一刻被拒绝。`examples/09-heterogeneous/cuda` 与 `.../sycl` 是这个形状;
-`.../hip` 保留手写的头文件,两者可以并排读。
+**接缝底下那个 `extern "C"` 边界不是设计决定。**它是每个入口点的签名被第二次
+写出来，写在「不一致时看不见」的那个位置上：C 语言链接不做名字修饰，而设备岛
+与它的宿主回退永不同链。`mcpp.tools.island` 从两个实现里读出被标记的声明，
+写出那个头文件和它之上的模块，于是签名只存在一次，而两个半边如果声明不一致，
+会在两份文本同时摆在生成器面前的那一刻被拒绝。`examples/09-heterogeneous/cuda`
+与 `.../sycl` 正是这个形状；`.../hip` 保留手写的头文件，两者因此可以并排读。
 
-**shader 或一份被嵌入的文件是数据。** 它的接口是一个地址加一个尺寸,这是机械的,所以
-由规则包生成,消费者同样不写出任何生成物的名字,只写 `import myapp.shaders`。在
-mcpp 2026.9.7.1 之前,那条 lane 是唯一的例外:生成的头文件**就是**接口,而每个消费者
-都得写出它的名字。
+**shader 或一份被嵌入的文件是数据。**它的接口是一个地址加一个字节数，这是
+机械的，所以由规则包生成，消费者同样不写出任何生成物的名字，只写
+`import myapp.shaders`。在 mcpp 2026.9.7.1 之前，那条 lane 是唯一的例外：生成的
+头文件**就是**接口，每个消费者都得写出它的名字。
 
-所以规则不是「接口要生成」也不是「接口要手写」。规则是:**机械的接口生成,设计出来的
-接口手写,而两种情况下头文件都是没有任何消费者会写出其名字的中间产物。**
+所以规则不是「接口要生成」，也不是「接口要手写」。规则是：**机械的接口生成，
+设计出来的接口手写，而两种情况下，头文件都是没有任何消费者会写出其名字的
+中间产物。**
 
 #### 载荷到达时的名字
 
-模块名与命名空间是同一条标识符路径,由工程已经写下的名字推导。一条规则,两条 lane
-共用:
+模块名与命名空间是同一条标识符路径，由工程已经写下的名字推导而来。一条规则，
+两条 lane 共用：
 
-> 模块名是根。组基准目录以下的每层目录延长**命名空间**。末端标识符由 lane 决定:
-> 数据 lane 从文件名推导,因为载荷没有自己的名字;岛 lane 取入口点的名字,因为
-> 作者写了一个。
+> 模块名是根。组基准目录以下的每一层目录延长**命名空间**。末端标识符由 lane
+> 决定：数据 lane 从文件名推导，因为载荷没有自己的名字；岛 lane 取入口点的
+> 名字，因为作者已经写了一个。
 
 | 写下的 | 到达时的样子 |
 |---|---|
@@ -197,44 +202,48 @@ mcpp 2026.9.7.1 之前,那条 lane 是唯一的例外:生成的头文件**就是
 | `kernels/saxpy.cu` 里的 `myapp_saxpy` | `myapp::kernels::myapp_saxpy(...)` |
 | `kernels/image/blur.cu` 里的 `myapp_blur` | `myapp::kernels::image::myapp_blur(...)` |
 
-根取自**包名**(非标识符字符替换掉),不是目录名 —— 包放在一个通用目录下时两者不同,
-而 mcpp 从 2026.9.7.1 起把包名报给构建程序,正是为了这一条。文件名的 stem 与 stage
-构成访问器(`scale.comp` -> `scale_comp`),而相对该组基准目录的子目录成为命名空间段 ——
-这就是让两个同 stem 的 shader 成为两样东西而不是一次冲突的机制。想要别的名字就传一个:
-`examples/09-heterogeneous/cuda` 就传了,于是它的边界是 `app.kernels`,与接缝
-`app.saxpy` 同根。
+根取自**包名**（非标识符字符被替换掉），不是取自目录名——包放在一个通用目录
+下时两者不同，mcpp 从 2026.9.7.1 起把包名报给构建程序，正是为了这一条。文件名
+的 stem 与 stage 一起构成访问器（`scale.comp` -> `scale_comp`），相对组基准
+目录的子目录成为命名空间段——这正是让两个同 stem 的 shader 成为两样东西、而
+不是一次冲突的机制。想要别的名字，传一个就是：`examples/09-heterogeneous/cuda`
+就传了，于是它的边界是 `app.kernels`，与它的接缝 `app.saxpy` 同根。
 
-**岛 lane 上文件名什么都不变成,理由就在这张表里。** 载荷没有名字,所以数据 lane
-必须推导一个,并且需要目录把两个同 stem 的文件分开。入口点已经带着作者写下的名字,
-而两个同名入口点无论各自在哪个目录都是同一个符号 —— 于是文件名不命名任何东西,把一个
-函数在同一目录的两个文件之间搬动也不会改掉消费者写下的名字。
+**岛 lane 上文件名什么都不代表，理由就在这张表里。**载荷没有名字，所以数据
+lane 必须推导一个，并且需要目录把两个同 stem 的文件分开。入口点已经带着作者
+写下的名字，而两个同名入口点无论各自位于哪个目录，都是同一个符号——于是文件名
+不命名任何东西，把一个函数在同一目录的两个文件之间搬动，也不会改掉消费者写下
+的任何名字。
 
-访问器同时回答地址与字节数。在这个边界上 `sizeof` 不只是别扭,而是**答不出来**:
-那些字可能放在一个对象里而不是一个数组里,那时根本没有数组可以取 size。
+访问器同时回答地址与字节数。在这个边界上，`sizeof` 不只是别扭，而是**答不
+出来**：那些字可能落在一个对象里，而不是一个数组里，那时根本没有数组可以取
+size。
 
 ### 生成这个边界
 
-`extern "C"` 头以及它之上的模块都是机械的,`mcpp:plugins` 的 `mcpp.tools.island`
-把两者都写出来。它由工程在自己的 `build.mcpp` 里调用;它不是设备规则,`mcpp:plugins`
-里也没有任何规则用它。
+`extern "C"` 头文件以及它之上的模块都是机械的，`mcpp:plugins` 的
+`mcpp.tools.island` 把两者都写出来。它由工程在自己的 `build.mcpp` 里调用；
+它不是一条设备规则，`mcpp:plugins` 里也没有任何规则使用它。
 
-**工程要写的只有一个标记,写在入口点被定义的地方。**
+**工程要写的只有一个标记，写在入口点被定义的地方。**
 
 ```c
-// src/kernels/saxpy.cu —— 没有 include:生成的头经由编译器的强制包含旗标到达,
-// 而那个头同时把这个标记定义成空。
+// src/kernels/saxpy.cu -- no include: the generated header arrives through the
+// compiler's forced-include flag, which is also what defines the marker as
+// nothing.
 
 MCPP_EXPORT_C
 int app_saxpy(float a, const float* x, const float* y, float* out, unsigned n)
 { ... }
 ```
 
-`MCPP_EXPORT_C` 命名的是机制而不是领域:被标记的东西以 C 链接跨越一个生成出来的
-边界被导出。它展开为空 —— 由生成的头定义 —— 所以它刻意不以 `_API` 结尾,那个后缀
-按惯例展开为一个可见性属性。标记名可以由 `options::marker` 配置。
+`MCPP_EXPORT_C` 命名的是机制，不是领域：被标记的东西，以 C 链接跨越一个生成
+出来的边界被导出。它展开为空——由生成的头文件定义——所以它刻意不以 `_API`
+结尾，那个后缀按惯例展开为一个可见性属性。标记名可以经 `options::marker`
+配置。
 
-标记做的是选择。岛有自己的内部函数,而一个把文件里所有东西都导出的生成器,会让边界
-变成那个文件恰好包含了什么的意外结果。
+标记做的是选择。岛有自己的内部函数，而一个把一个文件里所有东西都导出的生成器，
+会让边界变成那个文件恰好包含了什么的意外结果。
 
 ```cpp
 const std::string root = std::string(mcpp::manifest_dir());
@@ -243,80 +252,85 @@ mcpp::tools::island::options opt;
 opt.module_name  = "app.kernels";
 opt.out_dir      = std::string(mcpp::out_dir()) + "/island";
 opt.roots        = { root + "/src/kernels", root + "/src/cpu" };
-opt.layout_root  = root + "/src/kernels";     // 默认取 roots.front()
-opt.strip_prefix = "app_";                     // 可选,见下
+opt.layout_root  = root + "/src/kernels";     // the default is roots.front()
+opt.strip_prefix = "app_";                     // optional, see below
 
 const auto entries = mcpp::tools::island::scan(opt);
 const auto out     = mcpp::tools::island::emit(*entries, opt);
 mcpp::generated(out->interface_file.c_str());
 ```
 
-**根是一棵树,其中一个根提供形状。** 每个根持有这个边界的一份实现,多个根意味着
-同一个入口点被实现了多次 —— 这正是接缝的常见形态,任何一次链接里只有一份实现在场。
-layout root 的目录才延长命名空间;其余的根只需要定义同样的名字,所以回退树可以是
-一个平铺文件,也可以被重新组织而不改掉消费者写下的任何名字。这是一个命名上的角色,
-不是等级:每个根都参与编译与链接,都同样是一份实现。
+**根是一棵树，其中一个根供给形状。**每个根持有这个边界的一份实现，多个根
+意味着同一个入口点被实现了多次——这正是接缝的常见形态，任何一次链接里都只有
+一份实现在场。layout root 的目录才延长命名空间；其余的根只需要定义同样的
+名字，因此回退树可以是一个平铺的文件，也可以被重新组织而不改掉消费者写下的
+任何名字。这是一个命名上的角色，不是等级：每个根都参与编译、参与链接，同等地
+是一份实现。
 
-根是磁盘上的目录,并且必须与加速器无关。取自 `mcpp::device_sources()` 的根在
-`--no-accel` 下会被收窄成空,入口点的命名空间就会改从回退树来 —— 同一个工程的两次
-构建会给出不同的限定名。
+根是磁盘上的目录，并且必须与加速器无关。一个取自 `mcpp::device_sources()` 的
+根，在 `--no-accel` 下会被收窄成空，入口点的命名空间就会改从回退树来——同一个
+工程的两次构建会给出不同的限定名。
 
-**两条拒绝,回答的是不同的问题。** 同一个名字在**一个**根里出现两次是冲突:C 语言
-链接不做名字修饰,所以那是同一个符号,而看起来把它们分开的命名空间会承诺一个链接器
-并不提供的隔离。同一个名字出现在**多个**根里是同一个入口点的多份实现,这时它们的
-声明必须逐字一致。后者是工具链里没有别的东西能做的检查;前者是让命名空间不说谎的
-那一条。
+**两条拒绝，回答的是不同的问题。**同一个名字在**一个**根里出现两次是一次
+冲突：C 语言链接不做名字修饰，所以那是同一个符号，而看起来把它们分开的命名
+空间，会承诺一种链接器并不提供的隔离。同一个名字出现在**多个**根里，是同一个
+入口点的多份实现，这时它们的声明必须逐字一致。后者是工具链里没有别的东西能做
+的检查；前者是让命名空间不说谎的那一条。
 
-此外还有两种配置错误被拒绝:互相重叠的根 —— 同时可以从两个根到达的文件有两条命名
-空间路径,而它拿到哪一条取决于这个列表的顺序;以及根里一个被标记的入口点都没有 ——
-一个什么都不导出的模块,比一个写错的路径在这里被指出来要晚得多、也难懂得多。
+此外还有两种配置错误会被拒绝：相互重叠的根——一个从两个根都能到达的文件有
+两条命名空间路径，而它拿到哪一条取决于这个列表的顺序——以及一个被标记的入口点
+都没有的根——一个什么都不导出的模块，比一个写错的路径在这里被指出来要晚得多、
+也难懂得多。
 
-**`strip_prefix` 是一种拼法,不是第二个实体。** 岛的符号对整个程序是全局的,所以
-入口点无论是否落在命名空间里都带着包前缀,而命名空间随后又把它重复一遍。这个选项在
-`using ::app_blur;` 旁边写出 `inline constexpr auto blur = app_blur;`。作者写下的
-名字仍然是规范名 —— 它是符号,也是 `nm`、链接错误、profiler 与 `dlsym` 显示的东西。
+**`strip_prefix` 是一种拼法，不是第二个实体。**岛的符号对整个程序是全局的，
+所以入口点无论是否落在命名空间里，都带着一个包前缀，命名空间随后又把它重复
+一遍。这个选项在 `using ::app_blur;` 旁边写出
+`inline constexpr auto blur = app_blur;`。作者写下的名字仍然是规范名——它是
+符号，也是 `nm`、链接错误、profiler 与 `dlsym` 显示出来的东西。
 
-**四级,每一级覆盖上一级:**
+**四个等级，每一级覆盖上一级：**
 
 | 级 | 手写的部分 | 消费者写 |
 |---|---|---|
 | L0 | 只有被标记的入口点 | `import app.kernels` —— 岛自己的 C 形状接口 |
 | L1 | 生成模块之上的一个接缝模块 | `import app.saxpy` —— 项目设计的接口 |
-| L2 | 接缝,外加用 `island::declared` 构造的条目 | 同上,用于 scan 看不见的入口点 |
-| L3 | 头文件与模块都手写 | 同上,签名写了两遍 |
+| L2 | 接缝，加上用 `island::declared` 构造的条目 | 同上，用于 scan 看不见的入口点 |
+| L3 | 头文件与模块都手写 | 同上，签名写了两遍 |
 
-生成的头经由 `mcpp::tools::island::force_include_flags` 到达岛,而这些旗标交给驱动
-设备编译器的那条**规则**,不走 `mcpp::cxxflag` —— 把一个头强制灌进每个 C++ 翻译单元,
-会让声明出现在模块接口的 `export module` 之前,那是非良构的。由 mcpp 自己编译的宿主
-实现没有这样一条命令行,它写一行普通的 `#include`。
+生成的头文件经 `mcpp::tools::island::force_include_flags` 到达岛，这些旗标
+交给驱动设备编译器的那条**规则**，不走 `mcpp::cxxflag`——把一个头强制灌进
+每个 C++ 翻译单元，会让声明出现在模块接口的 `export module` 行之前，那是
+非良构的。由 mcpp 自己编译的宿主实现没有这样一条命令行，它写一行普通的
+`#include`。
 
 [`examples/09-heterogeneous/boundary`](../../examples/09-heterogeneous/boundary/)
-是 L0 并写明了每一级的代价;`.../cuda` 与 `.../sycl` 是 L1;`.../hip`、`.../vulkan`
-与 `.../cann` 保留手写的头,于是两者可以对照着读。
+是 L0，并写明了每一级的代价；`.../cuda` 与 `.../sycl` 是 L1；`.../hip`、
+`.../vulkan` 与 `.../cann` 保留手写的头文件，于是两者可以对照着读。
 
 ## 编译一个岛
 
-调用设备编译器的那条命令不内置在 mcpp 里,而是由**构建规则包**提供 ——
-以 `host-module = true` 消费,emit 输出汇入链接的构建边。机制见
-[30 — build.mcpp](30-build-mcpp.md),可用的 CUDA 规则见 `examples/09-heterogeneous/cuda`。
+调用设备编译器的那条命令不内置在 mcpp 里，而是由一个**构建规则包**提供——以
+`host-module = true` 消费，emit 出的构建图边把输出汇入链接。机制见
+[30 —— build.mcpp](30-build-mcpp.md)，可用的 CUDA 规则见
+`examples/09-heterogeneous/cuda`。
 
-这个划分是刻意的。mcpp 拥有构建图、产物身份与架构集合;厂商的 flag 拼法、
+这个划分是刻意的。mcpp 拥有构建图、产物身份与架构集合；厂商的 flag 拼法、
 架构语法与宿主编译器要求属于规则包。
 
-## 工具包跟着规则来(2026.9.6.6+)
+## 工具包跟着规则一起来（2026.9.6.6+）
 
-一个要 CUDA 岛的工程只写一条边:
+一个想要 CUDA 岛的工程只写一条边：
 
 ```toml
 [build-dependencies.mcpp]
 plugins = { version = "0.3.0", features = ["rules-cuda"], host-module = true }
 ```
 
-**别的什么都不写。** 厂商工具包、它的运行时,以及规则需要的其余东西,都由**规则包**
-在选中它的那个 feature、它所服务的加速器之下声明:
+别的什么都不写。厂商工具包、它的运行时，以及规则需要的其余东西，都由**规则包**
+在选中它的那个 feature、它所服务的加速器之下声明：
 
 ```toml
-# 写在 mcpp:plugins 里,不写在你的工程里
+# mcpp:plugins, not your project
 [target.'cfg(accelerator = "cuda")'.feature-xlings.rules-cuda]
 "xim:cuda-nvcc"   = ">=12.9.86"
 "xim:cuda-cudart" = ">=12.9.79"
@@ -324,56 +338,64 @@ plugins = { version = "0.3.0", features = ["rules-cuda"], host-module = true }
 "xim:cuda-cccl"   = ">=12.9.27"
 ```
 
-**两重门,在下载第一个字节之前都要开。** feature 说「要不要这个规则」,
-`cfg(accelerator = ...)` 说「哪些构建真的需要设备工具包」。不带加速器的 `mcpp build`
-两道门都不过——这正是让最便宜的那次构建保持便宜的原因,而那是 CI 跑的那一次。
+两重门，在下载第一个字节之前都要打开。feature 回答「要不要这条规则」；
+`cfg(accelerator = ...)` 选择器回答「哪些构建真的需要这份设备工具包」。不带
+加速器的 `mcpp build` 两道门都不打开——这正是让最便宜的那次构建保持便宜的
+原因，而那正是 CI 跑的那一次。
 
-每条 lane 都是这样:`rules-cuda`、`rules-hip`、`rules-sycl`、`rules-spirv`、
-`rules-ascendc` 各自带着自己的环境。**不存在需要工程自己补环境的 lane**,因为「有时候
-需要」是一条没有任何地方能说清楚到可用的规则。
+每条 lane 都是这样：`rules-cuda`、`rules-hip`、`rules-sycl`、`rules-spirv`
+与 `rules-ascendc` 各自带着自己的环境。没有一条 lane 期待工程自己补上这份
+环境，因为「有时候需要」是一条没有任何地方能把它说清楚到可用的规则。
 
-**覆盖是工程里的一行。** 哪个包、最低到哪一版,是规则作者的知识;**具体哪一版**有时
-属于工程——一条 CUDA 线耦合着驱动下界,而那是产物将要运行的那批机器的属性:
+**覆盖是工程里的一行。**哪个包、最低到哪一版，是规则作者的知识；**具体是
+哪一版**有时属于工程，因为一条 CUDA 线耦合着一个驱动下界，而那是产物将要
+运行的那批机器的属性：
 
 ```toml
 [target.'cfg(accelerator = "cuda")'.xlings.workspace]
 "xim:cuda-nvcc" = "13.3.33"
 ```
 
-更近的声明赢,装一个版本,并且 mcpp 说出用了哪条。不满足规则下界的钉会被拒绝并点出
-两侧,而不是与它并排装下来。完整规则见 [23 — The Project Environment](23-the-project-environment.md) 的
-「一个包一个版本」;`examples/09-heterogeneous/multi-backend` 是本仓库里唯一走覆盖
-路径的示例,其余每一个都只写那条边。
+更接近的声明胜出，只装一个版本，mcpp 会说出用了哪一个。一个不满足规则下界
+的钉会被拒绝，并点名两侧，而不是与规则并排装下来。完整规则见
+[23 —— The Project Environment](23-the-project-environment.md) 的「一个包，
+一个版本」；`examples/09-heterogeneous/multi-backend` 是本仓库里唯一走覆盖
+路径的示例，其余每一个都只写那一条边。
 
 ## 规则包在第一次编译之前报告的事
 
-设备工具包有三件事出错得很晚,而没有一件是关于构建图的事实。它们由驱动这些工具的
-**规则包**读取并报告 —— `mcpp:plugins` 里的 `mcpp.rules.cuda` 逐一演示 —— 引擎一件都
-不拥有(`tests/unit/test_core_vendor_probes.cpp` 守住这条线,于是第二个后端不会在
-mcpp 里长出第二份拷贝)。
-
-**设备编译器接受哪些宿主编译器。** nvcc 拒绝比它在自己的 `crt/host_config.h` 中声明
-的上界更新的宿主编译器,而 mcpp 的工具链载荷往往比那个上界更新。在 nvcc 路线上,规则
-从它解析到的工具包读出上界 —— 载荷先于宿主,因为经 xlings 安装的工具包才是构建会用
-的那个,通常也是更新的那个(12.9 载荷写着 `gcc <= 14`,发行版的 CUDA 12.0 写着
-`gcc <= 12`)—— 并通过 `mcpp::warning` 说出它选了哪个编译器、为什么。主路线没有这条
-上界:`clang -x cuda` 自己就是宿主编译器。
-
-**设备编译器能否够到自己的后端。** 工具包可以装好、完整、在 `PATH` 上,却在第一阶段
-就失败:nvcc 以裸名调用 `cicc`、`cudafe++`、`ptxas`、`fatbinary`,靠的是它从自己二进制
-旁边的 `nvcc.profile` 前置进来的一条 `PATH`,而替换了 `/etc` 的沙箱会拿走 Debian 打包的
-那个 profile。规则向 nvcc 要它的计划(`nvcc --dryrun`)而不是假设一个,逐个解析各阶段,
-点名第一个解析不到的以及提供它的载荷。产不出计划的 dryrun 不产生任何结论。
-
-**驱动是否新到足以承载运行时。** 设备运行时不能比它将遇到的驱动更新;更新时,构建编译
-干净、链接干净,到第一次分配才以 *"CUDA driver version is insufficient for CUDA runtime
-version"* 失败。规则经驱动自己的库(经由 sentinel 包够到,绝不经 `/usr/lib`)读出驱动
-版本并陈述为事实;陈述它的运行时需要的下界;引擎在编译任何东西之前比较两者 —— 见
-[30 — build.mcpp](30-build-mcpp.md) 的探针通道。引擎读到的是一个名字、一个关系、一个
-版本;`cuda.driver` 是流过引擎的数据。
-
-凡是错答比不答更贵的地方都只报告不强制:工程里没有规则包的机器没有任何厂商相关的话
-要说,于是什么都不说;够不到答案的探针不发明答案。
+设备工具包有三件事出错得很晚，而没有一件是关于构建图的事实。它们由驱动这些
+工具的**规则包**读取并报告——`mcpp:plugins` 里的 `mcpp.rules.cuda` 逐一演示
+了它们——引擎一件都不拥有（`tests/unit/test_core_vendor_probes.cpp` 守住这条
+线，于是第二个后端不会在 mcpp 里长出第二份拷贝）。
+
+**设备编译器接受哪些宿主编译器。**nvcc 拒绝比它在自己的 `crt/host_config.h`
+中声明的上界更新的宿主编译器，而 mcpp 的工具链载荷往往比那个上界更新。走
+nvcc 路线时，规则从它解析到的工具包读出这条上界——载荷先于宿主被读，因为经
+xlings 安装的工具包才是构建实际会用的那个，通常也是更新的那个（12.9 载荷写着
+`gcc <= 14`，而一个发行版的 CUDA 12.0 写着 `gcc <= 12`）——并经 `mcpp::warning`
+说出它选了哪个编译器、为什么。走主路线时没有这条上界：`clang -x cuda` 自己
+就是宿主编译器。
+
+**设备编译器能否够到自己的后端。**一个工具包可以装好、完整、在 `PATH` 上，
+却仍在第一阶段就失败：nvcc 以裸名调用 `cicc`、`cudafe++`、`ptxas`、
+`fatbinary`，靠的是它从自己二进制旁边的 `nvcc.profile` 前置进来的一条
+`PATH`，而一个替换了 `/etc` 的沙箱会拿走 Debian 打包的那份 profile。规则
+向 nvcc 要它的计划（`nvcc --dryrun`），而不是假设一个，逐个解析各阶段，
+点名第一个解析不到的、以及提供它的那个载荷。一次产不出计划的 dryrun，不
+产生任何结论。
+
+**驱动是否新到足以承载这份运行时。**设备运行时不能比它将要遇到的驱动更新；
+更新时，构建编译干净、链接干净，直到第一次内存分配才以
+*"CUDA driver version is insufficient for CUDA runtime version"* 失败。
+规则经驱动自己的库读出驱动版本（经由 sentinel 包够到，绝不经 `/usr/lib`）并
+把它陈述为事实；陈述它的运行时需要的下界；引擎在编译任何东西之前比较两者——
+见 [30 —— build.mcpp](30-build-mcpp.md) 的探针通道。引擎读到的是一个名字、
+一个关系、一个版本；`cuda.driver` 是流过引擎的数据。
+
+凡是「答错比不答更贵」的地方，只报告，不强制：一台工程里没有规则包的机器，
+没有任何厂商相关的话要说，于是什么都不说；够不到答案的探针，不会发明一个
+答案。
 
 ## 声明一次构建的目标
 
@@ -382,24 +404,24 @@ version"* 失败。规则经驱动自己的库(经由 sentinel 包够到,绝不
 accel = "cuda12.8+{sm_80,sm_90f} ptx>=90"
 ```
 
-单次构建可用 `--accel` 覆盖 —— 这与 `--target` 对 `[toolchain]` 的关系相同。
-`--no-accel` 不是「没有写 `--accel`」,它是**显式请求不要加速器**,
-这正是在一个同时发布了设备构建的包中选中 CPU-only 变体所需要的。
+可用 `--accel` 为单次构建覆盖——这与 `--target` 对 `[toolchain]` 的关系相同。
+`--no-accel` 不是「没有写 `--accel`」，它是**显式请求不要加速器**，这正是在
+一个同时发布了设备构建的包里选中 CPU-only 变体所需要的。
 
-源码包可以声明它支持哪些后端:
+一个源码包可以声明它支持哪些后端：
 
 ```toml
 [package]
 accelerators = ["cuda", "rocm"]
 ```
 
-这与 `[package] platforms` 同形:一个意图声明与 CI 矩阵提示,不是门。
-它与产物的 `accel` 刻意是不同的字段 —— 声明由人手写、可以是期望值,
-而产物的字段是从产生它的那次构建**测量**出来的。
+这与 `[package] platforms` 同形：一个意图声明与 CI 矩阵提示，不是一道门。
+它与产物的 `accel` 刻意是两个不同的字段——声明由人手写，可以是期望值；而
+产物的字段是从产生它的那次构建**测量**出来的。
 
-## 预建产物的声明内容
+## 预建产物声明的内容
 
-携带设备代码的产物把它记在兼容性标签旁边:
+携带设备代码的产物，把它记在兼容性标签旁边：
 
 ```toml
 [[runtime.artifacts]]
@@ -410,22 +432,46 @@ abi        = "x86_64-linux-gnu-gcc16-libstdcxx16-c++23"
 accel      = "cuda12.8+{sm_80,sm_90f} ptx>=90"
 ```
 
-它是标签之外的独立字段而不是标签的一段,因为架构列表是一个**集合**,
-而标签是用 `-` 拼接的字符串,其中的 triple 本身就含有数量不定的 `-`。
+它是标签之外的独立字段，不是标签的一段，因为架构列表是一个**集合**，而标签是
+用 `-` 拼接的字符串，其中的 triple 本身就含有数量不定的 `-`。
 
-`accel` 缺席表示该产物不携带设备代码,因而不施加任何约束 ——
-这就是为什么一个纯 CPU 的库可被任何构建使用。
+`accel` 缺席意味着该产物不携带设备代码，因而不施加任何约束——这正是一个
+纯 CPU 库可被任何构建使用的原因。
 
-### 消费者的匹配
+### 消费方的匹配
 
-当一次构建请求的每个后端,产物都声明了该后端、工具包主版本一致、
-且覆盖了请求的每个架构时,该产物满足这次构建。一个架构被覆盖,当它被直接列出,
-或列出了同 major、minor 不高于它的家族目标,或内嵌可移植形式的下界不高于它。
+当一次构建请求的每个后端，产物都声明了该后端、工具包主版本一致、并且覆盖了
+请求的每个架构时，该产物就满足这次构建。一个架构被覆盖，当它被直接列出，或
+一个同 major、minor 不高于它的家族目标被列出，或内嵌可移植形式的下界不高于
+它。
 
-**家族目标与可移植形式是让变体矩阵保持有限的东西。** 一颗芯片一份产物不可扩展,
-一个世代一份可以。
+家族目标与可移植形式，是让变体矩阵保持有限的机制。一颗芯片发一份产物不可
+扩展，一个世代发一份可以。
 
-没有任何产物匹配时,拒绝会点名维度与两侧的取值:
+### 语法是开放的
+
+`cuda`、`hip`、`vulkan`、`sycl` 不是一个封闭集合。**后端名 + 版本 + 架构
+集合 + 可选下界**就是全部的形状，mcpp 在没有一张「谁存在」的表的情况下比较
+它们：
+
+```
+vulkan1.3+{spirv1.6} floor>=1.4
+sycl2020+{spir64,nvptx64-sm_89}
+hip6.4+{gfx942}
+```
+
+一个拼法里不带前导数字的架构——比如 `gfx942`——按**相等**比较，因为那里读
+不出任何序。这是答案，不是权宜之计：从中间抠出 `942` 会发明一个 AMD 并未
+定义的等级。
+
+`floor>=` 是可移植形式下界的**后端中立**拼法。`ptx>=` 是 CUDA 对同一字段
+的说法，仍然被接受，因此此前写下的描述符不受影响；一个可移植形式是 SPIR-V
+的后端写 `floor>=`，不必借用 NVIDIA 的词。
+
+各拼法对某个具体后端意味着什么，是**那个后端的规则包**的事。引擎持有的只是
+形状与比较方式。
+
+没有任何产物匹配时，拒绝会点名维度与两侧的取值：
 
 ```
 error: mcpplibs.gpuonly@0.1.0: no prebuilt artifact matches this toolchain.
@@ -439,51 +485,32 @@ error: mcpplibs.gpuonly@0.1.0: no prebuilt artifact matches this toolchain.
        publisher for one covering yours.
 ```
 
-这正是该维度存在所要搬移的那个失败。没有它,构建干净地链接完成,
-而程序在第一次 kernel 启动时失败,消息里既没有包名,也没有任何一侧期望的架构。
-
-### 语法是开放的
-
-`cuda`、`hip`、`vulkan`、`sycl` 不是一个封闭集合。**后端名 + 版本 + 架构集合 +
-可选下界**就是全部形状,mcpp 在没有「谁存在」这张表的情况下比较它们:
-
-```
-vulkan1.3+{spirv1.6} floor>=1.4
-sycl2020+{spir64,nvptx64-sm_89}
-hip6.4+{gfx942}
-```
-
-拼法里不带前导数字的架构 —— 如 `gfx942` —— 按**相等**比较,因为那里读不出任何序。
-这是答案而不是回避:从中间抠出 `942` 会发明一个 AMD 并未定义的等级。
-
-`floor>=` 是可移植形式下界的**后端中立**拼法。`ptx>=` 是 CUDA 对同一字段的说法,
-仍然被接受,所以此前写下的描述符不受影响;可移植形式是 SPIR-V 的后端写 `floor>=`,
-不必借用 NVIDIA 的词。
-
-各拼法对某个后端具体意味着什么,是**那个后端的规则包**的事。引擎持有的是形状与比较。
+这正是这个维度存在所要搬移的那种失败。没有它，构建会干净地链接完成，而程序
+在第一次 kernel 启动时才失败，消息里既没有包名，也没有任何一侧期望的架构。
 
 ### 发布多个变体
 
-一个包可以发布多个产物,消费者取第一个标签接受它的。**把 CPU-only 的产物排在第一位。**
-早于 `accel` 字段的 mcpp 会忽略该字段,而顺序是让这样的客户端仍然拿到一个
-到处都能跑的产物的唯一机制。
+一个包可以发布多个产物，消费方取第一个标签接受它的。**把 CPU-only 的产物排
+在第一位。**一个早于 `accel` 字段的 mcpp 会忽略这个字段，而顺序正是让这样的
+客户端仍然拿到一个到处都能跑的产物的唯一机制。
 
 ## 按后端条件化
 
-`accelerator` 是目标侧的一层,在依赖图解析之后才可求值,并且它持有一个**集合**
-而不是单个取值:
+`accelerator` 是目标侧的一层，在依赖图解析之后才被求值，并且它持有一个
+**集合**，而不是单个取值：
 
 ```toml
 [target.'cfg(accelerator = "rocm")'.build]
 cxxflags = ["-DMYAPP_ROCM"]
 ```
 
-比较是**成员判定**,因此一次同时启用 CUDA 与 ROCm 的构建对两者都答真。
+比较是**成员判定**，因此一次同时启用 CUDA 与 ROCm 的构建，对两者都答真。
 `any`、`all`、`not` 作为普通布尔组合子在其上组合。
 
-## 一个构建里的多个后端
+## 一次构建里的多个后端
 
-`accel` 点的是一个集合,所以支持多个设备的工程按后端各写一节,集合自己会合成:
+`accel` 点名的是一个集合，因此支持多个设备的工程按后端各写一节，集合自己
+会合成：
 
 ```toml
 [package]
@@ -504,220 +531,236 @@ sources = ["src/cuda/*.cpp"]
 sources = ["src/vulkan/*.cpp"]
 ```
 
-每条收窄的 glob 都被这个集合收窄,所以只写 `--accel vulkan1.2` 时着色器被编译、`.cu`
-被留在外面,不需要任何手写条件。
+每条收窄过的 glob 都被这个集合收窄，因此只写 `--accel vulkan1.2` 时，着色器
+被编译，`.cu` 被留在外面，不需要任何手写的条件。
 
 ### 多个后端下的 CPU 回退
 
-四个示例各自写的是 `cfg(not(accelerator = "<它自己那个>"))`。这对**只有一个后端**的
-工程是对的,对有多个后端的工程是**错的**:一次 CUDA 构建同样满足
-`not(accelerator = "vulkan")`,于是 CPU 实现会和 CUDA 实现一起进链接。有接缝时两者定义
-同一批 `extern "C"` 符号,结果是实测过的:
+四个示例各自写的都是 `cfg(not(accelerator = "<它自己那个>"))`，这对只有**一个**
+后端的工程是对的，对有多个后端的工程是**错的**：一次 CUDA 构建同样满足
+`not(accelerator = "vulkan")`，于是 CPU 实现会和 CUDA 实现一起进入链接。有
+接缝时，两者定义同一批 `extern "C"` 符号，结果是实测过的：
 
 ```
 ld: obj/src/cpu/impl.o: multiple definition of `impl';
     obj/src/cuda/impl.o: first defined here
 ```
 
-响,而且发生在链接期而不是运行期 —— 但这是 manifest 本可以避免的失败。直接说
-「本次构建没有命名任何后端」:
+响，而且发生在链接期而不是运行期——但这是 manifest 本可以避免的失败。直接说
+「这次构建没有点名任何后端」：
 
 ```toml
 [target.'cfg(accelerator = "none")'.build]
 sources = ["src/cpu/*.cpp"]
 ```
 
-`none`(mcpp 2026.9.6.5)是**空集**:它在本次构建完全没有命名加速器时成立,并且在生态
-长出新后端之后**继续**成立。
+`none`（mcpp 2026.9.6.5）是**空集**：它在这次构建完全没有点名加速器时成立，
+并且在生态长出新后端之后**继续**成立。
 
-**它取代的那种枚举写法当时是对的,但不会一直对。** `none` 之前唯一的拼法是否定整个集合,
+**它取代的那种枚举写法，当时是对的，但没有一直对下去。**在 `none` 之前，唯一
+的拼法是否定整个集合，
 
 ```toml
 [target.'cfg(not(any(accelerator = "cuda", accelerator = "vulkan")))'.build]
 ```
 
-于是这一行成了**后端集合被写下的第二个地方**。`any` / `all` / `not` 仍然作为普通布尔
-组合子在成员判定之上组合,也确实有需要它们的谓词 —— 但这里不是。`accelerator` 是一个
-**开放**词表:第三个后端是一个**包**而不是一次引擎改动,所以它出现的那天,没人记得去
-扩的那份枚举就不再表示它写着的意思。而且它**不会响**:视乎忘掉的是哪一半,得到的要么
-是给有设备的构建静默选上了 CPU 实现,要么是上面那条链接错误。
+于是这一行成了**后端集合被写下的第二个地方**。`any`、`all`、`not` 仍然作为
+普通布尔组合子，在成员判定之上组合，也确实存在需要它们的谓词——但这里不是。
+`accelerator` 是一个**开放**的词表：第三个后端是一个**包**，不是一次引擎改动，
+所以它出现的那一天，没人记得去扩的那份枚举，就不再表示它写着的意思。而且它
+**不会响**：视乎忘掉的是哪一半，得到的要么是给一个有设备的构建静默选上了
+CPU 实现，要么是上面那条链接错误。
 
-`cfg(not(accelerator = "none"))` 是同一句话的反面 —— 「本次构建至少命名了一个后端」
-—— 这正是多个后端共用的分发器应当条件化的东西。
+`cfg(not(accelerator = "none"))` 是同一句话的反面——「这次构建至少点名了
+一个后端」——这正是多个后端共用的分发器应当条件化的东西。
 
-### 另一种形态:不在链接期做选择
+### 另一种形态：不在链接期做选择
 
-需要排除,只是因为**接缝**用一个实现替换另一个,所以只能链进去一个。如果目标是「一个
-二进制在它遇到的任何机器上都能跑」,就不该在链接期选:
+需要排除，只是因为**接缝**用一个实现替换另一个，所以只能链进去一份。如果
+目标是「一个二进制在它遇到的任何机器上都能跑」，就不应该在链接期选择：
 
-* 把构建时带上的**每一个**后端都编进去 —— 每个 `cfg(accelerator = ...)` 节各加各的
-  源码,CPU 实现无条件在内;
-* 给每个实现一个不同的名字,让接缝在**运行期**去问哪些设备在场。
+* 把构建时带上的**每一个**后端都编进去——每个 `cfg(accelerator = ...)` 节
+  各加各的源码，CPU 实现无条件在内；
+* 给每一份实现一个不同的名字，让接缝在**运行期**去问哪些设备在场。
 
-这样就完全没有排除关系要维护,而产物回答的是二进制的使用者真正的问题。ggml 就是
-这个形态:每个后端自己注册,程序运行时由 `ggml_backend_reg_by_name` 选一个。
-`ggml-org:llamacpp` 就是这样构建的,它的 `backend-vulkan` 相对 `backend-cpu` 是**可加的**
-而不是互斥的。
+这样就完全没有排除关系要维护，产物回答的是二进制的使用者真正的问题。ggml
+就是这个形态：每个后端自己注册，程序运行时由 `ggml_backend_reg_by_name`
+选一个。`ggml-org:llamacpp` 就是这样构建的，它的 `backend-vulkan` feature
+相对 `backend-cpu` 是**可加的**，不是互斥的。
 
-选哪个形态是**程序自己的性质**,不是 mcpp 的:用接缝换实现的程序要链接期选择,而要发到
-没见过的机器上去的程序要运行期选择。
+选哪个形态是**程序自己的性质**，不是 mcpp 的性质：一个用接缝替换实现的程序，
+想要链接期选择；一个要发到没见过的机器上的程序，想要运行期选择。
 
-## 链接行上出现第二个 C++ 运行时时,进程只保留一个 unwinder
+## 链接行上出现第二个 C++ 运行时时，只保留一个 unwinder
 
-一条 lane 的设备编译器若是按 libstdc++ 配置的,链接行上就会出现 libstdc++,
-而产物本身静态链接 libc++。两者同时在镜像里,mcpp 的重复符号检查会报出它们共有的符号。
+一条 lane 的设备编译器，如果是按 libstdc++ 配置的，链接行上就会出现
+libstdc++，而产物本身静态链接 libc++。两者同时出现在镜像里，mcpp 的重复符号
+检查会报出它们共有的那些符号。
 
-对其中大多数符号,后果只是「调用了另一份可互换的实现」。对 unwinder 不是。
-静态归档只会贡献被引用到的成员,所以这种抢占**按构造是部分的**:在 SYCL lane 上实测,
-libgcc 的 18 个 `_Unwind_*` 入口点里有 10 个来自产物、8 个仍在 libgcc_s,
-其中包括 personality 例程要用的那几个访问器。于是 libstdc++ 的 personality
-拿 libgcc 的访问器去读一个 LLVM libunwind 的 context,找不到 landing pad,
-越过三帧之上一个本应命中的 handler 直接 `std::terminate`。
-在有东西抛出之前,这个程序一直是正确的。
+对其中大多数符号，后果只是「调用了另一份可互换的实现」。对 unwinder 不是。
+静态归档只贡献被引用到的成员，所以这种抢占**按构造是部分的**：在 SYCL lane
+上实测，libgcc 的 18 个 `_Unwind_*` 入口点里，有 10 个来自产物，8 个仍留在
+libgcc_s 里，其中包括 personality 例程要用的那几个访问器。于是 libstdc++ 的
+personality 拿 libgcc 的访问器去读一个 LLVM libunwind 的 context，找不到
+landing pad，越过三帧之上一个本应命中的 handler，直接调用了
+`std::terminate`。在有东西抛出之前，这个程序一直是正确的。
 
-因此,当链接行上出现 libstdc++ 而工具链自带的标准库是 libc++ 时,
-mcpp 改从 libgcc 取 unwinder(`--unwindlib=libgcc`),不再链载荷的 `libunwind.a`,
-并用 `--exclude-libs` 把静态归档的符号挡在动态符号表之外。libgcc_s 本来就在进程里
-—— libstdc++ 需要它 —— 所以这一步只是点名一个已有的库而不是新增一个,
-C++ 运行时仍然是内嵌的。链接行上没有第二个运行时的构建一字节不变。
+因此，当链接行上出现 libstdc++、而工具链自带的标准库是 libc++ 时，mcpp 改从
+libgcc 取 unwinder（`--unwindlib=libgcc`），不再链载荷的 `libunwind.a`，并用
+`--exclude-libs` 把静态归档的符号挡在动态符号表之外。libgcc_s 本来就在
+进程里——libstdc++ 需要它——所以这一步只是点名一个已有的库，不是新增一个，
+C++ 运行时仍然是内嵌的。链接行上没有第二个运行时的构建，一字节不变。
 
 ## 两条值得写明的边界
 
-**`--accel` 与 `--no-accel` 是 `build`、`run`、`test` 三者的选项**(run 与 test 自 2026.9.5.2 起),与 `--target`、`--profile` 同级;`pack` 与其它构建输入一样从 manifest 读 `[build] accel`。它起初只挂在 `build` 上,实测的后果是一个工程的 CPU-only 变体能构建却不能运行:`mcpp build --no-accel` 产出了它,而 `mcpp run` 交回的是设备构建。
-<!-- 下面一段保留原有说明 -->
-**历史:`--accel` 曾只是 `build` 的选项**,与 `--static`、`--toolchain` 同级,
-不在 `run`、`test`、`pack` 上重复。那些命令与读取任何其它构建输入一样,
-从 manifest 读 `[build] accel`;这个 flag 的用途是覆盖单次构建,而那正是 `build` 覆盖的场景。
+**`--accel` 与 `--no-accel` 是 `build`、`run`、`test` 三者共有的选项**
+（run 与 test 自 2026.9.5.2 起），与 `--target`、`--profile` 同级；`pack` 与
+读取其它任何构建输入一样，从 manifest 读 `[build] accel`。这个 flag 起初只
+挂在 `build` 上，实测的后果是一个工程的 CPU-only 变体能构建却不能运行：
+`mcpp build --no-accel` 产出了它，而 `mcpp run` 交回的却是设备构建。
 
-**`mcpp pack` 不写 `accel` 字段。** 它本可以把 manifest 声明的值写进去,
-而这恰恰是它不这么做的理由:该字段陈述产物**携带**了什么,
-而 mcpp 目前不自己编译设备代码 —— 形态 A 走规则包,mcpp 没有可测量的对象。
-把一个声明写进一个含义是「测量值」的字段,会让身份**恰好以该维度要防止的方式**说谎。
-今天由发布者显式写这个字段,索引描述符就是这么做的;
-等 `kind = "device"` 把设备编译放进 mcpp 之后,`mcpp pack` 才会发它。
+**`mcpp pack` 不写出 `accel` 字段。**它本可以把 manifest 声明的值原样写进去，
+而这恰恰是它不这么做的理由：该字段陈述的是产物**携带**了什么，而 mcpp 目前
+不自己编译设备代码——形态 A 走规则包，mcpp 没有可测量的对象。把一个声明写进
+一个含义是「测量所得」的字段，会让身份恰好以这个维度存在要防止的那种方式
+说谎。今天由发布者显式写这个字段，索引描述符就是这么做的；等
+`kind = "device"` 把设备编译放进 mcpp 之后，`mcpp pack` 才会发出它。
 
-## 各条 lane 及其驱动的工具链
+## 各条 lane，以及它们各自驱动的工具链
 
-一个规则包拥有一个编译器的拼写。引擎不认识其中任何一个名字:
-`tests/unit/test_core_vendor_probes.cpp` 断言剥掉注释后 `src/` 里不出现任何厂商工具名,
-并自带分母(枚举到的文件数)。
+一个规则包拥有一个编译器的拼写。引擎不认识其中任何一个名字：
+`tests/unit/test_core_vendor_probes.cpp` 断言剥掉注释之后，`src/` 里不出现
+任何厂商工具名，并自带分母（枚举到的文件数）。
 
 | `mcpp:plugins` 的 feature | 模块 | 它驱动的编译器 | 它声明的载荷 | `[build] accel` |
 |---|---|---|---|---|
-| `rules-cuda` | `mcpp.rules.cuda` | 工程自己的 clang(`-x cuda`),或 GCC 工具链下的 nvcc | `xim:cuda-nvcc`、`xim:cuda-cudart`、`xim:libcurand`、`xim:cuda-cccl` | `cuda12.9+{sm_89} ptx>=89` |
-| `rules-hip` | `mcpp.rules.hip` | NVIDIA 平台上是工程自己的 clang(`-x cuda`) | 上面那些,再加 `xim:hip-nvidia` | `hip, cuda12.9+{sm_89}` |
-| `rules-sycl` | `mcpp.rules.sycl` | `xim:dpcpp` 载荷里的 clang(`-fsycl`) | `xim:dpcpp`;Linux 上另有 `xim:gcc`、`xim:glibc`、`xim:linux-headers`;NVIDIA 目标另加 `xim:cuda-nvcc` | `sycl` 或 `sycl, cuda12.9+{sm_89}` |
-| `rules-spirv` | `mcpp.rules.spirv` | `glslangValidator` 或 `glslc` | Linux 上 `xim:glslang`,macOS 与 Windows 上 `xim:shaderc` | `vulkan1.2` |
+| `rules-cuda` | `mcpp.rules.cuda` | 工程自己的 clang（`-x cuda`），或 GCC 工具链下的 nvcc | `xim:cuda-nvcc`、`xim:cuda-cudart`、`xim:libcurand`、`xim:cuda-cccl` | `cuda12.9+{sm_89} ptx>=89` |
+| `rules-hip` | `mcpp.rules.hip` | NVIDIA 平台上是工程自己的 clang（`-x cuda`） | 上面那些，再加 `xim:hip-nvidia` | `hip, cuda12.9+{sm_89}` |
+| `rules-sycl` | `mcpp.rules.sycl` | `xim:dpcpp` 载荷里的 clang（`-fsycl`） | `xim:dpcpp`；Linux 上另有 `xim:gcc`、`xim:glibc`、`xim:linux-headers`；NVIDIA 目标另加 `xim:cuda-nvcc` | `sycl` 或 `sycl, cuda12.9+{sm_89}` |
+| `rules-spirv` | `mcpp.rules.spirv` | `glslangValidator` 或 `glslc` | Linux 上 `xim:glslang`，macOS 与 Windows 上 `xim:shaderc` | `vulkan1.2` |
 | `rules-slang` | `mcpp.rules.slang` | `slangc` | `xim:slang` | `vulkan1.2` |
-| `rules-ascendc` | `mcpp.rules.ascendc` | CANN 工具包里的 `bisheng`(`-x asc`) | `xim:cann-toolkit` | `ascend8.5+{dav-c220}` |
-
-载荷那一列是每条规则在 `cfg(accelerator = ...)` 之下**为自己**声明的东西,列出来是为了
-让一条 lane 的代价在选它之前就可读。工程一个字都不用写——见上文「工具包跟着规则来」。
-
-HIP 与 SYCL 两行的 `accel` 值是**两段**而不是一段。第一段命名编程模型,第二段命名设备,
-于是一个设备在本生态里只有一种拼法,无论有多少个模型去够它:`sm_89` 无论被哪条规则读到
-都是同一个 `sm_89`。只写 `accel = "sycl"` 而没有第二段,则编译到 SPIR-V,由运行期挑设备。
-
-**NVIDIA 平台上的 HIP 是一层头文件,不是第二个运行时。** 每一个 HIP 入口点都是对应
-CUDA 入口点的内联包装,所以目标文件链接的是 CUDA 运行时,机器上没有 ROCm。
-`xim:hip-nvidia` 因此不含任何二进制。AMD 平台需要一个本生态尚未发布的 ROCm 运行时,
-规则会点名拒绝,而不是产出一个没有东西能链接的目标文件。
-
-**一次 SYCL 构建携带两个 C++ 运行时,而接缝是使这件事安全的东西。** `libsycl.so` 是
-对着 libstdc++ 编译的,而 mcpp 的产物链接 libc++,于是两者都在同一个映像里,mcpp 的
-重复符号检查会报出它们共有的那些 unwinder 符号。任何东西都不得穿过接缝:SYCL 异常在
-设备编译单元里被捕获并转成返回码,因为抛出它的那个运行时不是调用方会用来展开的那个。
-
-## 每条 lane 到达的平台
-
-一条 lane 在某个平台上成立,要三件事同时为真:设备编译器为它发布了、产物需要的运行时
-在那里够得到、以及这条规则自己那段按宿主分岔的代码在那里编译得过。第三件是最容易被默认
-成立的那一件。`mcpp:plugins` 会为矩阵里的每个平台编译每一条规则
-(`tests/all-rules-compile` —— 一个不点名任何 accelerator 的夹具,因此一个字节都不
-下载,只问六个模块编不编得过);它把三处潜伏的宿主差异变成了对应 runner 上的编译错误,
-而三处没有一处是 Linux 构建看得见的。
+| `rules-ascendc` | `mcpp.rules.ascendc` | CANN 工具包里的 `bisheng`（`-x asc`） | `xim:cann-toolkit` | `ascend8.5+{dav-c220}` |
+
+载荷那一列是每条规则在 `cfg(accelerator = ...)` 之下为自己声明的东西，列
+出来是为了让一条 lane 的代价在被选中之前就可读。工程一个字都不用写——见上文
+「工具包跟着规则一起来」。
+
+HIP 与 SYCL 两行的 `accel` 值是**两段**，不是一段。第一段命名编程模型，第二段
+命名设备，因此一个设备在本生态里只有一种拼法，不论有多少个模型去够它：`sm_89`
+不论被哪条规则读到，都是同一个 `sm_89`。只写 `accel = "sycl"`、没有第二段时，
+编译目标是 SPIR-V，由运行期挑选设备。
+
+**NVIDIA 平台上的 HIP 是一层头文件，不是第二个运行时。**每一个 HIP 入口点都是
+对应 CUDA 入口点的内联包装，因此目标文件链接的是 CUDA 运行时，机器上没有
+ROCm。`xim:hip-nvidia` 因此不含任何二进制。AMD 平台需要一个本生态尚未发布的
+ROCm 运行时，规则会点名拒绝，而不是产出一个没有东西能链接的目标文件。
+
+**一次 SYCL 构建携带两个 C++ 运行时，而接缝是让这件事安全的机制。**
+`libsycl.so` 是对着 libstdc++ 编译的，而一个 mcpp 产物链接 libc++，于是两者
+都在同一个镜像里，mcpp 的重复符号检查会报出它们共有的那些 unwinder 符号。
+任何东西都不得穿过接缝：一个 SYCL 异常在设备编译单元里被捕获，转成一个返回码，
+因为抛出它的那个运行时，不是调用方会用来展开的那一个。
+
+## 每条 lane 能到达的平台
+
+一条 lane 在某个平台上成立，要三件事同时为真：设备编译器为它发布了、产物
+需要的运行时在那里够得到、以及这条规则自己那段按宿主分岔的代码在那里编译
+得过。第三件是最容易被默认成立的一件。`mcpp:plugins` 会为矩阵里的每个平台
+编译每一条规则（`tests/all-rules-compile`——一个不点名任何 accelerator 的
+夹具，因此一个字节都不下载，只问这些模块编不编得过）；这个夹具把三处潜伏的
+宿主差异，变成了对应 runner 上的编译错误，而这三处没有一处是 Linux 构建
+看得见的。
 
 | lane | Linux | macOS | Windows | 决定因素 |
 |---|---|---|---|---|
-| `rules-spirv` | 是 | 是 | 是 | 着色器编译器三个平台都有发布:Linux 上 `xim:glslang`,macOS arm64 与 Windows x86_64 上 `xim:shaderc` |
-| `rules-cuda` | 是 | 否 | 是 | NVIDIA 为 Linux 与 Windows 发布可再分发组件,而自 CUDA 10.2 之后没有为 macOS 发布过工具包 |
-| `rules-sycl` | 是 | 否 | 仅 Level Zero 与 OpenCL | Intel 从同一个 tag 发布 `sycl_linux` 与 `sycl_windows`,macOS 一个都没有;上游写明 Windows 不构建 CUDA 与 HIP 插件,而那份资产也确实只带 Level Zero 与 OpenCL 两个适配器 |
-| `rules-hip` | 是 | 否 | 否 | NVIDIA 平台的头文件包只为 Linux 发布;AMD 平台要一个本生态在任何平台上都还没发布的 ROCm 运行时 |
+| `rules-spirv` | 是 | 是 | 是 | 着色器编译器三个平台都有发布：Linux 上是 `xim:glslang`，macOS arm64 与 Windows x86_64 上是 `xim:shaderc` |
+| `rules-cuda` | 是 | 否 | 是 | NVIDIA 为 Linux 与 Windows 发布可再分发组件，自 CUDA 10.2 之后没有再为 macOS 发布过工具包 |
+| `rules-sycl` | 是 | 否 | 仅 Level Zero 与 OpenCL | Intel 从同一个 tag 发布 `sycl_linux` 与 `sycl_windows`，macOS 一个都没有；上游写明 CUDA 与 HIP 插件不为 Windows 构建，而那份资产也确实只带 Level Zero 与 OpenCL 两个适配器 |
+| `rules-hip` | 是 | 否 | 否 | NVIDIA 平台的头文件包只为 Linux 发布；AMD 平台需要一个本生态在任何平台上都还没发布的 ROCm 运行时 |
 | `rules-ascendc` | 是 | 否 | 否 | CANN 工具包只为 Linux 发布 |
 
-**「到得了」在每一行上不是同一个断言,而这个差别写出来而不是留给人推。** 三个平台上
-真的**跑过**的是 `rules-spirv`:着色器编译器产出两个 SPIR-V 阶段、产物链接得上,而
-Linux 上还渲染出来并把像素与一个软件光栅器逐字节比对。Windows 上**装上并编译过**的是
-CUDA 与 SYCL 那条 lane:组件装得上、注册出程序,规则也为那个宿主编译过,但还没有任何
-一台 runner 在那里端到端驱动过 `nvcc` 或 `dpcpp`。所以一行写「是」的意思是上面三个条件
-成立,不是说有 runner 执行过那条 lane。
-
-**厂商没有为某个平台发布,这个问题就到此为止。** 再多的引擎工作也变不出一个 macOS 的
-CUDA 工具包。生态能做的是在一次构建请求跨过那条边界的地方把它说出来,而每条 lane 正是
-这样做的:SYCL 规则在 Windows 上拒绝一个提前编译的 NVIDIA 目标,并点名决定这件事的那
-条上游发布说明,而不是编出一个运行时装不进去的东西。
-
-**一条 lane 到得了的平台,它到达的方式是同一个。** 一条规则按宿主区别对待的全部内容
-就是下面四处,而每一处都是宿主的性质,不是设备的:
-
-- **程序名上的后缀。** `nvcc` 与 `nvcc.exe` 是同一个工具。
-- **库在哪里。** ELF 宿主上是 `lib` 与 `lib64`,NVIDIA 的 Windows 布局里是 `lib/x64`。
-- **设备编译器驱动的是哪个宿主编译器。** Windows 上 CUDA 规则一律走 clang 路线,与
-  项目的编译器无关:nvcc 路线把设备单元的宿主那一半交给 `-ccbin` 命名的编译器,而在那
-  个宿主上它只接受 MSVC 的 `cl.exe`,找到它要问机器的 Visual Studio 安装。clang 路线
-  不驱动第二个编译器,它自己就会定位 MSVC 的头文件。
-- **要把宿主的哪些库挡在外面。** Linux 上 SYCL 规则点名 `xim:gcc`、`xim:glibc` 与
-  `xim:linux-headers`,因为 dpcpp 的 clang 不是 mcpp 解析的那个 clang,两个库都没有
-  被配置过。Windows 上只有一个 C++ 运行时 —— MSVC 的 —— 两个编译器用的是同一个,所以
-  那三条声明在那里根本不存在:要求它们会让构建因为三个本生态不为那个平台发布、而那个
-  平台的编译器也不需要的包而失败。
-
-**运行时适配层是 Linux 的构造。** `compat:cuda-runtime`、`compat:sycl-runtime` 与
-`compat:vulkan-runtime` 存在,是因为 Linux 上 mcpp 的产物跑在一个不查 `/usr/lib` 的
-私有 loader 后面,于是驱动包装的厂商库必须被搬到产物自己的搜索路径上。macOS(dyld)
-与 Windows(PE loader)按构造就没有这一层,面向它们的项目一条适配声明都不写。
-
-## 建立在此之上的框架形态
-
-五条 lane 证明了规则包能驱动五个编译器,其中最新的一个来自 NVIDIA 与 Khronos 两个
-谱系之外的厂商。框架是下一个问题 —— 这套机制能不能扛起一个
-真会被部署的东西 —— 而它自己有一个形状,是在 llama.cpp 的 Vulkan 后端上量出来的。
-
-**框架自带生成器,生态应当驱动它而不是替换它。** llama.cpp 的着色器由一个与后端放在
-一起的工具生成,两者在同一个仓库里构成同一份契约。重新实现那套生成,等于造出这份契约
-的第二个版本,并且各按各的节奏漂移。`mcpp.rules.spirv` 是给「自己写着色器」的工程用的;
-一个**已经有**着色器流水线的工程需要的是把它**声明**出来,不是被替换掉。
-
-**到了那个规模,「声明」就是全部差别。** 134 组着色器在构建程序里生成,是串行的、每次
-prepare 跑一遍的,失败只会报成 `build.mcpp exited 1`。同样这 134 组写成 `mcpp::action`
-的边,则是增量的、并行的,每一条失败时都说得出自己是谁。这个门槛并不高:
-`mcpp.rules.sycl` 已经在声明两条了。
-
-**能力探测属于构建程序,而且只做一次。** 一个着色器编译器接受哪些扩展,是它**怎么被
-构建**的性质而不是版本的性质,所以上游读的是编译器自己的拒绝信息。这个答案有两个读者
-—— 决定发射哪些变体的生成器,和决定去找哪些变体的后端源码 —— 而两者都在编译开始前
-就定死了。问两遍会把一个真相变成两个。
-
-**可选后端是一个 feature,它需要的一切都挂在这个 feature 下。** 包走
-`[feature-deps.<f>]`,工具走 `[feature-xlings.<f>]`,于是不点名这个后端的消费者一样
-都不会获得。这个主张的判据不是「CPU 构建仍然能用」,而是「CPU 构建的解析结果里不出现
-任何属于该后端的包」。
-
-**软件设备并不自动成为硬件的替身。** ggml 只保留类型不为 `eCpu` 的 Vulkan 设备,所以
-Mesa 的 lavapipe 仅因类型就被排除 —— 尽管它声明了后端要求的每一项能力。这是框架的
-政策而不是打包缺陷,绕过它要用框架自己的选择器,而不是去改打包。
-
-`ggml-org:llamacpp` 以 `backend-vulkan` feature 承载这一整套。
+**「到得了」在每一行上不是同一个断言，而这个差别是写出来的，不是留给人推。**
+三个平台上真的**跑过**的是 `rules-spirv`：着色器编译器产出两个 SPIR-V 阶段、
+产物链接得上，在 Linux 上它还渲染出来了，像素与一个软件光栅器逐字节比对过。
+Windows 上**装上并编译过**的是 CUDA 与 SYCL 那条 lane：组件装得上、注册出
+程序，规则也为那个宿主编译过，但还没有任何一台 runner 在那里端到端驱动过
+`nvcc` 或 `dpcpp`。所以一行写「是」的意思，是上面三个条件成立，不是说有
+runner 执行过那条 lane。
+
+**一个厂商没有为某个平台发布，这个问题就到此为止。**再多的引擎工作，也变不出
+一份 macOS 的 CUDA 工具包。这个生态能做的，是在一次构建请求跨过那条边界的地方
+把它说出来，而每条 lane 正是这样做的：SYCL 规则在 Windows 上拒绝一个提前编译
+的 NVIDIA 目标，并点名决定这件事的那条上游发布说明，而不是去编出一个运行时
+装不进去的东西。
+
+**一条 lane 到得了的平台，它到达的方式是同一个。**一条规则按宿主区别对待的
+全部内容，就是下面四处，而每一处都是宿主的性质，不是设备的性质：
+
+- **程序名上的后缀。**`nvcc` 与 `nvcc.exe` 是同一个工具。
+- **库在哪里。**ELF 宿主上是 `lib` 与 `lib64`，NVIDIA 的 Windows 布局里是
+  `lib/x64`。
+- **设备编译器驱动的是哪个宿主编译器。**Windows 上，CUDA 规则一律走 clang
+  路线，与工程的编译器无关：nvcc 路线把设备单元的宿主那一半交给 `-ccbin`
+  命名的编译器，而在那个宿主上它只接受 MSVC 的 `cl.exe`，找到它要问机器的
+  Visual Studio 安装。clang 路线不驱动第二个编译器，它自己会定位 MSVC 的
+  头文件。
+- **要把宿主的哪些库挡在外面。**Linux 上，SYCL 规则点名 `xim:gcc`、
+  `xim:glibc` 与 `xim:linux-headers`，因为 dpcpp 的 clang 不是 mcpp 解析
+  出来的那个 clang，两个库都没有被它配置过。Windows 上只有一个 C++ 运行时
+  ——MSVC 的——两个编译器用的是同一个，因此那三条声明在那里根本不存在：
+  要求它们，会让构建因为三个本生态不为那个平台发布、而那个平台的编译器也
+  不需要的包而失败。
+
+**运行时适配层是 Linux 特有的构造。**`compat:cuda-runtime`、
+`compat:sycl-runtime` 与 `compat:vulkan-runtime` 之所以存在，是因为
+Linux 上一个 mcpp 产物运行在一个不查 `/usr/lib` 的私有 loader 之后，因此
+一份由驱动包装好的厂商库，必须被搬到产物自己的搜索路径上。macOS（dyld）与
+Windows（PE loader）按构造就没有这一层，面向它们的工程一条适配声明都不写。
+
+## 建立在此之上的框架的形状
+
+五条 lane 证明了一个规则包能驱动五个编译器，其中最新的一个来自 NVIDIA 与
+Khronos 两个谱系之外的厂商。框架是下一个问题——这套机制能不能扛起一个真会被
+部署的东西——而它自己有一个形状，是在 llama.cpp 的 Vulkan 后端上量出来的。
+
+**框架自带生成器，这个生态应当驱动它，而不是替换它。**llama.cpp 的着色器，
+由一个和后端放在一起的工具生成，两者在同一个仓库里构成同一份契约。重新实现
+那套生成，等于造出这份契约的第二个版本，并且各按各的节奏漂移。
+`mcpp.rules.spirv` 是给「自己写着色器」的工程用的；一个**已经有**着色器
+流水线的工程，需要的是把它**声明**出来，不是被替换掉。
+
+**到了那个规模，「声明」就是全部差别。**134 组着色器如果在构建程序里生成，
+是串行的、每次 prepare 都要跑一遍的，失败也只会报成
+`build.mcpp exited 1`。同样这 134 组写成 `mcpp::action` 的边，则是增量的、
+并行的，每一条失败时都说得出自己是谁。这个门槛并不高：`mcpp.rules.sycl` 已经
+在声明两条了。
+
+**能力探测属于构建程序，而且只做一次。**一个着色器编译器接受哪些扩展，是它
+**怎么被构建**的性质，不是它版本的性质，所以上游读的是编译器自己的拒绝信息。
+这个答案有两个读者——决定发射哪些变体的生成器，和决定去找哪些变体的后端
+源码——而两者都在编译开始前就定死了。问两遍，会把一个真相变成两个。
+
+**可选后端是一个 feature，它需要的一切都挂在这个 feature 下面。**包走
+`[feature-deps.<f>]`，工具走 `[feature-xlings.<f>]`，因此不点名这个后端的
+消费方，一样都不会拿到。这个主张的判据不是「CPU 构建仍然能用」，而是
+「CPU 构建的解析结果里，不出现任何属于该后端的包」。
+
+**软件设备并不自动成为硬件的替身。**ggml 只保留类型不是 `eCpu` 的 Vulkan
+设备，因此 Mesa 的 lavapipe 仅因为类型就被排除——尽管它声明了这个后端要求的
+每一项能力。这是框架的策略，不是打包上的缺陷，绕过它要用框架自己的选择器，
+而不是去改打包。
+
+`ggml-org:llamacpp` 用它的 `backend-vulkan` feature 承载这一整套。
 
 ## 当前边界
 
-- 岛形态的 device target,及其隐含的 device link(RDC)。
-- OpenMP `target` offload,以及 stdpar。
+- 岛形态的设备目标，以及它隐含的设备链接（RDC）。
+- OpenMP `target` offload，以及 stdpar。
 - HIP 的 AMD 平台。`rules-hip` 只到达 NVIDIA 平台。
-- Metal(`.metal`)与 OpenCL C(`.cl`)。两个扩展名都被归类为设备源,而没有任何
-  已发布的规则包认领它们,因此声明了其中之一的构建会被拒绝,并点名该文件。
-- CUDA 的 13.x 线在 Windows 上。Windows 承载的是 12.x 线。
-- `mcpp pack` 不产出 `accel` 字段。需要它的发布方写进描述符。
-
-每条 lane 的按平台边界见*每条 lane 到达哪些平台*一节的表格。
+- Metal（`.metal`）与 OpenCL C（`.cl`）。两个扩展名都被归类为设备源文件，而
+  没有任何已发布的规则包认领它们，因此一次点名了其中之一的构建会被拒绝，
+  并点名该文件。
+- CUDA 的 13.x 线在 Windows 上。Windows 上承载的是 12.x 线。
+- `mcpp pack` 不产出 `accel` 字段。需要它的发布方把它写进描述符。
 
+每条 lane 按平台划分的边界，见上文「每条 lane 能到达的平台」一节的表格。
diff --git a/docs/zh/50-machine-output.md b/docs/zh/50-machine-output.md
index dc42ac4fc..bc41c37a2 100644
--- a/docs/zh/50-machine-output.md
+++ b/docs/zh/50-machine-output.md
@@ -1,51 +1,58 @@
 # 50 —— 机器可读输出
 
-**读者:**要解析 mcpp 输出的工具、编辑器扩展或 CI 任务的作者。
+**读者：** 解析 mcpp 输出的工具、编辑器扩展或 CI 任务的作者。
 
-**本章回答的那一个问题:**一个程序可以依赖什么、它怎样被版本化、以及协议怎样被
-识别。
+**本章回答的那一个问题：** 一个程序可以依赖什么，输出如何被版本化，以及协议
+如何被识别。
 
-**不在这里:**面向人的输出 —— 它不带任何兼容性承诺;以及退出码契约,那是
+**不在这里：** 面向人的输出，它不携带任何兼容性承诺；以及退出码契约，那是
 [SPEC-003](../specs/exit-codes.md)。
 
-mcpp 面向两类读者。本章是对第二类 —— **程序** —— 的契约。编辑器扩展、CI 脚本,以及任何解析 mcpp 输出的程序,
-可依赖的部分在此列出。
+mcpp 面向两类读者写作。本章是对第二类读者 —— 程序 —— 的契约。编辑器扩展、
+CI 脚本，以及任何解析 mcpp 输出的程序，都可以依赖本章陈述的内容。
 
 ## 1. 首要规则
 
-> **靠解析 stdout 来识别协议。不要靠退出码,也不要靠「命令没失败」。**
+> **靠解析 stdout 来识别协议，不靠退出码，也不靠「命令没有失败」这一点。**
 
-读 stdout,尝试按 JSON 解析,并要求 `schemaVersion` 与 `kind` 都在。缺任一,说明这个
-mcpp 不支持所请求的内容。
+读取 stdout，尝试按 JSON 解析，并要求 `schemaVersion` 与 `kind` 二者都在。
+只要缺一个，就说明这个 mcpp 不支持调用方所请求的协议。
 
-这不是风格偏好。`mcpp --protocol-version` 看起来像是入口,在支持它的版本上确实是个
-捷径。但在**它出现之前发布的每一个 mcpp** 上,它自己就是一个未知选项 —— 而未知选项
-过去会把人类文本打到 **stdout**、退出码 1、stderr 为空。成功与失败同一通道。换成
-`--json` 拼写也一样,两者走同一条路径。
+这不是风格上的偏好。`mcpp --protocol-version` 看起来理应是入口，在支持它的
+版本上确实是个有用的捷径。但在**它存在之前发布的每一个 mcpp** 上，这条命令
+本身就是一个未知选项 —— 而未知选项过去的行为是把人类可读的文本打印到
+**stdout**、退出码为 1、stderr 为空。成功与失败走的是同一个通道。把它拼成
+`--json` 也不会改变什么，两者最终走的是同一条路径。
 
-所以「正向识别」是唯一跨版本成立的规则。下面所有设计都围绕它。
+所以「正向识别」是唯一在各版本上都成立的规则，下面的一切设计都围绕它展开。
 
 ## 2. 信封
 
 ```jsonc
 {
-  "schemaVersion": 1,          // 信封自身的版本
-  "kind": "mcpp.env",          // 这是哪种文档
-  "kindVersion": 1,            // 该 kind 的数据版本
-  "effects": [],               // 运行这条命令做了什么 —— 见 §4
-  "mcpp": { "version": "2026.8.8.3", "protocol": { "min": 1, "max": 1 } },
-  "data": { /* 随 kind 而定 */ },
+  "schemaVersion": 1,          // the ENVELOPE's version
+  "kind": "mcpp.env",          // which document this is
+  "kindVersion": 1,            // this kind's own data version
+  "effects": [],               // what running the command did — see §4
+  "mcpp": {
+    "version": "2026.8.8.3",
+    "protocol": { "min": 1, "max": 1 }
+  },
+  "data": { /* specific to `kind` */ },
   "diagnostics": []
 }
 ```
 
-`schemaVersion` 与 `kindVersion` 分开是有意的:单一全局版本号意味着给 `mcpp.env` 加
-一个字段会推高客户端为 `mcpp.xpkg` 读到的版本,而它无从判断真正变的是哪个。
+`schemaVersion` 与 `kindVersion` 被特意分开：如果只有一个全局版本号，给
+`mcpp.env` 增加一个字段就会推高客户端为 `mcpp.xpkg` 读到的版本号，而客户端
+无从判断真正变化的是哪一个。
 
-`effects` 永远存在。空数组表示「没有」;字段缺失会表示「未知」,那是另一个断言。
+`effects` 永远存在。空数组表示「什么都没做」；字段缺失会表示「未知」，那是
+另一个断言。
 
-命令产出了它的文档时 `data` 存在。命令在得到文档之前就失败时省略 `data`,而不是
-给一个空对象,原因写在 `diagnostics` 里;`mcpp.build-database` 就是这样的 kind(§8)。
+命令产出了它自己的文档时，`data` 才存在。命令在拿到文档之前就失败时，省略
+`data` 而不是给出一个空对象，原因写在 `diagnostics` 里；`mcpp.build-database`
+就是这样的 kind（见 §8）。
 
 ### 诊断
 
@@ -55,36 +62,39 @@ mcpp 不支持所请求的内容。
   "severity": "error" | "warning" | "note",
   "source": "mcpp",
   "message": "unknown key 'standrad'",
-  "path": "mcpp.toml",                                    // 没有则省略
-  "range": { "start": {"line":3,"column":1},
-             "end": {"line":3,"column":9} }               // 没有则省略
+  "path": "mcpp.toml",                       // omitted when there is none
+  "range": { "start": {"line": 3, "column": 1},
+             "end":   {"line": 3, "column": 9} }   // omitted when there is none
 }
 ```
 
-位置从 1 开始。`column` 数的是 **UTF-8 字节**,因此索引的是 mcpp 读到的同一份文件。
+位置从 1 开始计数。`column` 数的是 **UTF-8 字节**，因此索引的正是 mcpp 实际
+读到的那份文件。
 
-没有位置的诊断**省略** `path` 与 `range`,而不是填 0 —— `line: 0` 会把客户端指向一个
-不存在的位置。
+一条没有位置的诊断会省略 `path` 与 `range`，而不是填 0 —— `line: 0` 会把
+读者指向一个不存在的位置。
 
-`code` 永远存在。**解析 `code`,永远不要解析 `message`。**
+`code` 永远存在。解析 `code`，永远不要解析 `message`。
 
 ## 3. 请求机器输出
 
 ```
-mcpp <命令> --format json
+mcpp <command> --format json
 ```
 
-目前只支持 `json`。`ndjson` 保留给未来真正需要流式的场景,**现在不接受** —— 请求它是
-错误,不是静默回落。
+目前只支持 `json`。`ndjson` 为将来真正需要流式的场景保留，**现在不被接受**
+—— 请求它是一个错误，而不是静默地回落到别的格式。
 
-`--format` 已经表示其**产物**的命令改用 `--message-format json` 请求机器输出,与
-`mcpp test` 一致。`mcpp pack --format` 表示包格式(`tar`、`dir`、`msi`),因此它的报告是
-`mcpp pack --message-format json`(2026.9.16.1+)。形状随 kind 而定:测试随时间陆续完成,
-所以 `mcpp test` 每个测试一条流式记录;一次打包只有一个结果,所以 `mcpp pack` 输出一个信封。
+`--format` 已经用来表示某种**产物**的命令，改用 `--message-format json` 来
+请求机器输出，`mcpp test` 就是这样做的。`mcpp pack --format` 表示的是包格式
+（`tar`、`dir`、`msi`），所以它的报告方式是
+`mcpp pack --message-format json`（2026.9.16.1+）。具体形状随 kind 而定：
+`mcpp test` 的测试是随时间陆续完成的，所以它按测试逐条输出流式记录；一次
+`mcpp pack` 只有一个结果，所以它输出一个信封。
 
-### 不支持的值 / 未知选项
+### 不支持的值与未知选项
 
-两者都走 **stderr**、退出码 **2**,且**不往 stdout 写任何东西**:
+两者都写往 **stderr**，退出码为 **2**，并且**不向 stdout 写任何东西**：
 
 ```
 $ mcpp self env --format yaml
@@ -93,30 +103,32 @@ $ echo $?
 2
 ```
 
-一个还不知道自己会得到什么格式的请求,不该往协议独占的通道里写东西。结合 §1,客户端的
-规则就完整了:**stdout 上没有 JSON,就是不支持**,无论原因。
+一个还不知道自己会得到什么格式的请求，不应该往协议独占的那个通道里写东西。
+结合 §1，客户端的规则就是完整的了：**stdout 上没有 JSON，就意味着不支持**，
+无论原因是什么。
 
-**带信封命令**的退出码 —— 即 `--protocol-version` 声明的那几个 kind。这张表刻意只管
-它们:别的命令返回的码不在其中,写进来等于记录一个这些命令给不出的值。mcpp 全局的
-映射见[退出码契约](../specs/exit-codes.md)。
+**带信封命令**的退出码 —— 即 `--protocol-version` 所声明的那几个 kind。这张
+表刻意只覆盖它们：别的命令返回的退出码不在其中，把它写进来等于记录一件这些
+命令给不出的事实。跨越 mcpp 全部命令的完整映射见
+[退出码契约](../specs/exit-codes.md)。
 
 | 退出码 | 含义 |
 |---|---|
 | 0 | 成功 |
-| 1 | 命令跑了并且失败 —— 见 stderr;当 stdout 带信封时见 `diagnostics` |
-| 2 | 用法错误 —— 未知选项、不支持的值 |
-| 70 | 内部错误(未捕获异常) |
+| 1 | 命令运行了并且失败 —— 见 stderr；当 stdout 携带信封时见 `diagnostics` |
+| 2 | 用法错误 —— 未知选项、不支持的取值 |
+| 70 | 内部错误（未捕获的异常） |
 | 127 | 未知命令 |
 
-**`1` 可能与 stdout 上的信封同时出现。** `mcpp xpkg parse` 会把一份违反名字形态的
-描述符作为 JSON 报出来**并且**退 1:文档就是答案,退出码说明这个答案是一次拒绝。§1
-仍然成立 —— 解析 stdout,不要按退出码分支 —— 但一个把任何非零退出都当作「没有输出」
-的客户端,会丢掉它已经拿到的文档。
+**`1` 可以与 stdout 上的信封同时出现。** `mcpp xpkg parse` 会把一份违反命名
+形态的描述符以 JSON 形式报出**并且**退出 1：这份文档就是答案，退出码说明这个
+答案是一次拒绝。§1 依然成立 —— 解析 stdout，不要按退出码分支 —— 但一个把任何
+非零退出都当成「没有输出」的客户端，会丢掉它已经拿到手的文档。
 
-## 4. effects —— 命令在输出前执行的操作
+## 4. effects —— 命令在打印结果之前执行的动作
 
-带 untrusted-workspace 门的 IDE 必须在**运行之前**决定。等信封到手,它描述的事情已经
-发生了。所以同一份信息也静态提供:
+一个带有 untrusted-workspace 门禁的 IDE，必须在**运行之前**就做出决定。等
+信封送达时，它所描述的事情已经发生了。所以同一份信息也以静态方式提供：
 
 ```
 mcpp --protocol-version
@@ -124,6 +136,7 @@ mcpp --protocol-version
 
 ```jsonc
 {
+  "schemaVersion": 1,
   "kind": "mcpp.protocol",
   "envelope": { "min": 1, "max": 1 },
   "kinds":    { "mcpp.env": 1, "mcpp.xpkg": 1, "mcpp.cache": 1 },
@@ -135,83 +148,90 @@ mcpp --protocol-version
 }
 ```
 
-用具名 effects 而不是 `destructive: true|false`,因为布尔分不开「无害的」和「门存在的
-理由」:
+effects 采用具名的方式而不是一个 `destructive: true|false`，因为布尔值分不
+清「无害的动作」与「门禁真正要拦的那件事」：
 
 | effect | 含义 |
 |---|---|
 | `init-mcpp-home` | 首次使用时可能创建 `$MCPP_HOME`。**位于项目目录之外。** |
-| `read-project` | 读 manifest 与源码 |
-| `write-project` | 写入项目树(`target/`、compile DB) |
-| `write-global-cache` | 写共享构建缓存 |
-| `network` | 可能联网 |
-| `exec-build-script` | **执行工作区里的代码**(`build.mcpp`) |
+| `read-project` | 读取 manifest 与源码 |
+| `write-project` | 写入项目树（`target/`、compile DB） |
+| `write-global-cache` | 写入共享构建缓存 |
+| `network` | 可能发起网络请求 |
+| `exec-build-script` | **执行工作区里的代码**（`build.mcpp`） |
 
-多数门只在乎 `exec-build-script` 与 `write-project`,可以忽略 `init-mcpp-home` ——
-mcpp 给自己做初始化不是工作区在动作。
+多数门禁只关心 `exec-build-script` 与 `write-project`，可以忽略
+`init-mcpp-home` —— mcpp 给自己做初始化，不算工作区在动作。
 
-上表是命令**可能**做的事。信封里的 `effects` 是这次运行**做了**的事,其中 `network`
-按观测记录而不是按声明:本次运行启动过索引刷新、安装或 git 远程操作时即列出,包括失败
-的或被期限终止的那一次;在 `--offline` 下运行时从不列出。
+上表列出的是命令**可能**做的事。信封里的 `effects` 是这次运行**实际做了**的
+事，其中 `network` 按实际观测记录，而不是按声明：只要本次运行启动过索引
+刷新、安装，或者一次 git 远程操作，就会被列出，包括失败了的或被期限终止的
+那一次；在 `--offline` 下运行时永远不会列出。
 
 ## 5. `--json` 不等于 `--format json`
 
-有两条命令在本协议之前就发布了 `--json`:
+有两条命令在本协议存在之前就已经发布了 `--json`：
 
 ```
-mcpp xpkg parse <file> --json  ->  {"namespace": …, "name": …, …}
-mcpp cache list --json         ->  {"root": …, "entries": [ … ]}
+mcpp xpkg parse <file> --json     ->  {"namespace": …, "name": …, …}
+mcpp cache list --json            ->  {"root": …, "entries": [ … ]}
 ```
 
-这些 payload 是**裸的**(没有信封),而且已经有消费者在读。所以:
+那些 payload 是**裸的**——没有信封——而且已经有消费方在读取它们。所以：
 
-> **`--json` 永久保留它的 payload。`--format json` 才是带信封的那个。**
+> **`--json` 永久保留它的 payload。带信封的是 `--format json`。**
 
-`--json` 不弃用,使用它也**不打任何警告** —— 客户端在解析这份输出,警告会落在它中间。
+`--json` 没有被弃用，使用它也不会打印任何警告：客户端正在解析这份输出，一条
+警告会落在它中间。
 
-两种拼写由同一个来源产出,所以永远描述同一件事:一个答案,两种形状。
+两种拼法出自同一个数据来源，因此永远描述同一件事：一个答案，两种形状。
 
-## 6. 退出码
+## 6. 退出状态
 
-`mcpp run` 报告程序自己的退出码。整个取值空间分三段,只有第一段属于程序:
+`mcpp run` 报告的是程序自身的退出状态。整个取值空间分三段，只有第一段属于
+程序：
 
 | 区间 | 含义 |
 |---|---|
-| `0`–`124` | 程序跑过了,这是它自己的退出码,原样透传 |
-| `125`–`127` | 尝试启动但被拒绝 —— `127` 找不到,`126` 找到但不可执行,`125` 其他;对 `mcpp run --format <f>` 而言,一个是目录、且没有任何 runner 能到达的分发物也得到 `126`,它在启动之前被拒绝,含义相同(2026.9.14.2+) |
-| `2` | mcpp 在尝试启动之前就拒绝了:用法、配置或解析错误 |
+| `0`–`124` | 程序运行过了；这是它自己的状态，原样透传 |
+| `125`–`127` | 尝试过启动但被拒绝 —— `127` 是找不到，`126` 是找到了但不可执行，`125` 是其他原因；对 `mcpp run --format <f>` 而言，一个是目录、且没有任何 runner 能到达的分发物同样得到 `126`，它在启动之前就被拒绝，含义相同（2026.9.14.2+） |
+| `2` | mcpp 在尝试启动任何东西之前就拒绝了：用法、配置或解析错误 |
 
-2026.9.4.3 之前,所有非零退出码都被折成 `1`,为的是让 `2` 表示「起不来」以区别于
-「跑了但失败」。这个区别值得保留,代价不值得:`main` 返回 `3` 的程序会让
-`mcpp run` 退 `1`,qemu 报 `3` 的裸机镜像同样到达为 `1` —— 本项目让人使用的这条
-命令因此无法用于分支判断。
+在 2026.9.4.3 之前，所有非零状态都被折叠成 `1`，目的是让 `2` 能表示「起不来」
+以区别于「跑了但失败」。这个区分值得保留，但代价不值得：`main` 返回 `3` 的
+程序会让 `mcpp run` 退出 `1`，qemu 报出 `3` 的裸机镜像同样到达为 `1` ——
+本项目让人使用的这条命令因此无法用于分支判断。
 
-中间那一段是 `env`、`timeout`、`nice` 早已在用、且被 shell 文档化的取值,所以
-`126` 与 `127` 带着它们惯常的含义到达,而不是本项目分配的编号。
+中间那一段，是 `env`、`timeout`、`nice` 早已在用、并且被 shell 文档化的取
+值，因此 `126` 与 `127` 到达时带着它们惯常的含义，而不是本项目自行分配的
+编号。
 
-**程序自己也可以退 `125`–`127`,mcpp 不试图靠数字区分。** 区分二者的是:启动失败
-一定向 stderr 写出原因,而程序自己的退出码从不写。需要确定的客户端应当读 stderr,
-或使用 `--format json` —— 那里退出码是一个字段而不是一条通道。
+**程序自身也可以以 `125`–`127` 退出，mcpp 不试图靠数字去区分两者。** 区分它
+们的是：启动失败一定会向 stderr 写出原因，而程序自身的退出状态从不这样做。
+需要确定结果的客户端应当读 stderr，或者使用 `--format json` —— 那里退出
+状态是一个字段，不是一条通道。
 
-`mcpp test` 不变,仍为 `0` 或 `1`:它聚合多个程序,没有单一退出码可以透传。
-每个测试各自的退出码在 JSON 流的 `exit_code` 字段里(§8)。
+`mcpp test` 保持不变，仍然是 `0` 或 `1`：它聚合了多个程序的结果，没有单一的
+状态可以透传。每个测试各自的退出码在 JSON 流的 `exit_code` 字段里（见
+§8）。
 
 ## 7. 稳定性承诺
 
-对每个 `kind`,在同一 `kindVersion` 内:
+对每一个 `kind`，在同一个 `kindVersion` 之内：
 
-- 字段只**新增**,不删除
-- 字段含义不改变
-- 破坏性变更抬版本;需要过渡窗口时,`protocol.min`/`max` 重叠,两版都可读
+- 字段只会被**新增**，从不删除
+- 一个字段的含义永远不变
+- 破坏性变更会抬升版本号；在需要过渡窗口时，`protocol.min`/`max` 会重叠，
+  使两个版本都可读
 
-这个承诺只有被强制执行才值钱,所以每个 kind 都有一个「改字段名就变红」的测试。
-**没人能弄坏的 schema 不是 schema** —— `xlings interface --list` 声明了 20 个
-capability,其 `outputSchema` 全部只有 `{"exitCode": integer}`,而客户端看到版本号就会
-以为背后有契约。
+这个承诺只有被强制执行才有价值，因此每个 kind 都配有一个测试：字段名一改就
+变红。**没有人能弄坏的 schema 不是 schema** —— `xlings interface --list`
+声明了 20 个 capability，它们的 `outputSchema` 全部只有
+`{"exitCode": integer}`，而一个客户端看到版本号就会以为背后有一份契约。
 
-## 8. 各 kind
+## 8. 各个 kind
 
-### `mcpp.env` —— mcpp 使用的路径
+### `mcpp.env` —— mcpp 使用的各个路径
 
 ```
 mcpp self env --format json
@@ -219,7 +239,7 @@ mcpp self env --format json
 
 ```jsonc
 {
-  "initialized": false,          // 还没有 config.toml
+  "initialized": false,          // is there a config.toml yet?
   "mcppHome":    "/home/u/.mcpp",
   "registry":    "/home/u/.mcpp/registry",
   "xlingsHome":  "/home/u/.mcpp/registry",
@@ -230,27 +250,29 @@ mcpp self env --format json
 }
 ```
 
-这条路径**刻意是只读的**。人类用的 `mcpp self env` 会在 `$MCPP_HOME` 缺失时初始化它
-—— 在提示符下敲这条命令的人预期如此 —— 但一个客户端**询问东西在哪**,不该成为把东西
-放到那儿的原因。在从未运行过 mcpp 的机器上,得到的是它**将会**使用的路径与
-`initialized: false`,而磁盘未被触碰。
+这条命令刻意是只读的。人类使用的 `mcpp self env` 会在 `$MCPP_HOME` 缺失时
+初始化它 —— 在提示符下敲这条命令的人预期它会这样做 —— 但一个客户端**询问
+东西在哪**，不应该成为把东西放到那里的原因。在一台从未运行过 mcpp 的机器
+上，得到的输出是它**将会**使用的那些路径，加上 `initialized: false`，而磁盘
+未被触碰。
 
-这也是它存在的理由:没有它,客户端就得重新实现 mcpp 的 home 解析 —— 包括「PATH 上的
-`mcpp` 可能是 xlings shim 而不是真二进制」那一部分。
+这也是这个 kind 存在的理由：没有它，客户端就得自己重新实现一遍 mcpp 的 home
+解析逻辑 —— 包括「PATH 上的 `mcpp` 可能是一个 xlings shim 而不是真正的
+二进制」这一部分。
 
-### `mcpp.xpkg` —— 解析后的描述符
+### `mcpp.xpkg` —— 一份被解析的描述符
 
 ```
 mcpp xpkg parse <file.lua> --format json
 ```
 
-`data` 就是 `--json` 裸打印的那份文档。
+`data` 就是 `--json` 裸打印出来的那份文档。
 
-`mcpp` 字段为内联表的描述符产出完整文档:`namespace`、`name`、`versions`、
-`standard`、`import_std`、`sources`、`include_dirs`、`generated_files`、
-`generated_contents`、`targets`、`unknown_keys`。没有内联表的描述符以
-`"form": "A"` 代替构建信息。两种形态都携带 `versions` —— 描述符各平台
-`xpm` 表的版本键。
+`mcpp` 字段是内联表的描述符，产出的是完整文档：`namespace`、`name`、
+`versions`、`standard`、`import_std`、`sources`、`include_dirs`、
+`generated_files`、`generated_contents`、`targets`、`unknown_keys`。没有
+内联表的描述符，会用 `"form": "A"` 代替构建信息。两种形态都携带
+`versions` —— 描述符各平台 `xpm` 表的版本键。
 
 ### `mcpp.cache` —— 全局构建缓存
 
@@ -258,48 +280,49 @@ mcpp xpkg parse <file.lua> --format json
 mcpp cache list --format json
 ```
 
-`data` 是 `{root, entries[]}`,与 `--json` 裸打印的一致。
+`data` 是 `{root, entries[]}`，与 `--json` 裸打印出来的一致。
 
-### `mcpp.toolchain.list` —— 已安装的工具链,以及这台宿主服务的目标
+### `mcpp.toolchain.list` —— 已安装的工具链，以及这台宿主能服务的目标
 
 ```
 mcpp toolchain list --format json
 ```
 
-`data` 是 `{host, toolchains[], targets[]}`。一个工具链是
-`{family, version, default}`;Visual Studio 另有 `source: "system"` —— 它是在
-机器上被找到的,不是 mcpp 装的。一行目标是
-`{target, note, toolchain, pin, status, default}`,`status` 取
-`installed` / `available` / `via dependency graph` / `planned`。
+`data` 是 `{host, toolchains[], targets[]}`。一个工具链的形状是
+`{family, version, default}`；一份 Visual Studio 安装另有
+`source: "system"` —— 它是在机器上被定位到的，不是由 mcpp 安装的。一行目标
+的形状是 `{target, note, toolchain, pin, status, default}`，`status` 取
+`installed` / `available` / `via dependency graph` / `planned` 之一。
 
-**`toolchain` 与 `pin` 不是同一个字段写两遍。** `toolchain` 是这一行关联到
-什么 —— 已装的行是装了的载荷,词表行是那一行的约定。`pin` 只承载目标表的约定,
-没有约定的行为空。`x86_64-linux-gnu` 装了 gcc 而根本没有约定,所以要挑「约定是
-gcc 的行」必须读 `pin`。
+**`toolchain` 与 `pin` 不是把同一个字段写了两遍。** `toolchain` 表示这一行
+关联到什么 —— 已装的行是装好的载荷，词表行是它自己的约定。`pin` 只承载目标
+表自己的约定，没有约定的行留空。`x86_64-linux-gnu` 装了 gcc，却根本没有约定，
+所以要挑出「约定是 gcc」的那些行，必须读 `pin`。
 
-### `mcpp.why.toolchain` —— 一对 (目标, 工具链) 的解析结果
+### `mcpp.why.toolchain` —— 一对 (target, toolchain) 的解析结果
 
 ```
 mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
 ```
 
-它只解析并报告,不构建。`data`:
+它只解析并报告，不执行构建。`data`：
 
 | 字段 | |
 |---|---|
-| `requested` | `{target, toolchain}` —— 问的是什么 |
+| `requested` | `{target, toolchain}` —— 请求的内容 |
 | `status` | `ok` 或 `refused` |
-| `reason` | 拒绝的记号,或 `none` |
-| `compiler` | `{family, version, driver, chosenBy}` —— 真正会跑的驱动器,以及为什么是它 |
+| `reason` | 拒绝的记号，或 `none` |
+| `compiler` | `{family, version, driver, chosenBy}` —— 真正会运行的驱动器，以及选中它的原因 |
 | `triple` | `{requested, toolchain, llvm}` |
-| `cLibrary` | `{mode, path, origin, suppliesTarget}`;`mode` 取 `sysroot` / `payload-first` / `none`,`origin` 取 `payload` / `subos` / `host` / `none` |
-| `layers[]` | 目标侧五层:`{layer, interface, impl, origin, subset}` |
+| `cLibrary` | `{mode, path, origin, suppliesTarget}` —— `mode` 取 `sysroot` / `payload-first` / `none`，`origin` 取 `payload` / `subos` / `host` / `none` |
+| `layers[]` | 目标侧的五个层：`{layer, interface, impl, origin, subset}` |
 
-**`compiler.chosenBy` 回答「为什么是它」。** `{origin, requiredBy, replaced}`
-—— `origin` 与构建状态行用的是同一句话(`[toolchain] in mcpp.toml`、
-`your default`、`target default`、`required by the dependency graph`、
-`first-run default`)。当某条 `requires = ["mcpp:compiler=…"]` 做了决定时,
-`requiredBy` 点名那个包,`replaced` 点名被顶掉的那个 spec;没有发生时两者都为空。
+**`compiler.chosenBy` 回答「为什么是它」。** `{origin, requiredBy,
+replaced}` —— `origin` 与构建的状态行使用的是同一句话
+（`[toolchain] in mcpp.toml`、`your default`、`target default`、
+`required by the dependency graph`、`first-run default`）。当一条
+`requires = ["mcpp:compiler=…"]` 做出了这个决定时，`requiredBy` 点名那个
+包，`replaced` 点名被顶掉的那个 spec；两者在没有发生时都为空。
 
 ```jsonc
 "compiler": { "family": "clang", "version": "22.1.8", "driver": "…/clang++",
@@ -308,83 +331,86 @@ mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
                             "replaced":   "gcc@16.1.0" } }
 ```
 
-没有它,要问「为什么」的消费方只能去解析状态行 —— 而那正是这份文档存在的理由所要
-消除的字符串匹配。
+没有它，一个要问「为什么」的消费方就只能去解析状态行 —— 而消除这种字符串
+匹配，正是这份文档存在的理由。
 
-**`cLibrary` 与 `layers[].c-abi` 回答的是两个问题,`suppliesTarget` 说明哪一个
-管用。** `cLibrary` 描述的是**载荷**的链接模型 —— 一份由载荷供给的 C 库会用到的
-搜索路径。`layers[].c-abi` 描述的是**这次构建**。当依赖供给 C 库时两者分叉,而在
-`suppliesTarget` 之前,同一份文档同时报出两者却没有任何字段说明该信哪个:
+**`cLibrary` 与 `layers[].c-abi` 回答的是两个不同的问题，`suppliesTarget`
+说明该信哪一个。** `cLibrary` 描述的是**载荷**自己的链接模型 —— 一份由载荷
+供给的 C 库会使用的搜索路径。`layers[].c-abi` 描述的是**这次构建**本身。当
+某个依赖供给了 C 库时，两者会出现分歧，而在 `suppliesTarget` 出现之前，
+同一份文档会同时报出两者，却没有任何字段说明二者该信哪一个：
 
 ```jsonc
 "cLibrary": { "origin": "payload", "path": "…/xim-x-glibc/2.44/lib64",
-              "suppliesTarget": false },   // ← 新增;载荷并不在产物里
+              "suppliesTarget": false },   // ← added; the payload is not in the artifact
 "layers":   [ { "layer": "c-abi", "interface": "musl",
                 "impl": "openkal-musl@0.3.5", "origin": "graph" } ]
 ```
 
-是**新增一个字段**而不是给 `cLibrary` 改名或给 `mode` 加取值,因为 §7 承诺字段
-只增不删、且一个字段的含义永不改变。
+这里新增的是一个字段，而不是给 `cLibrary` 改名或者给 `mode` 加一个取值，
+因为 §7 承诺字段只增不减，且一个字段的含义永远不变。
 
-**2026.9.1.1 起,载荷供给的 glibc 让 `layers[].interface` 的**取值**变了** ——
-从 `gnu` 变为 `glibc`,Windows 上从 `gnu` 变为 `ucrt`。字段的**含义**没变(它仍然是
-「哪个实现」),所以 §7 仍然成立;变的是它不再报三元组的 env 段 —— 那是一次请求而
-不是一个实现,也不是任何一个 C 库的名字。现在的取值就是
-[22 —— 目标侧](22-target-side.md)一直列着的那些,并且包可以在
-`cfg(c-abi = …)` 谓词里与它们比较。按字面量 `gnu` 取值的客户端需要更新;
+**2026.9.1.1 起，一份由载荷供给的 glibc 使 `layers[].interface` 的取值发生了
+变化** —— 从 `gnu` 变为 `glibc`，在 Windows 上从 `gnu` 变为 `ucrt`。字段的
+含义没有变（它依然表示「是哪一个实现」），因此 §7 仍然成立；变化的是它不再
+报告三元组的 env 段 —— 那是一次请求，而不是一个实现，也不是任何 C 库的名字。
+现在的取值正是 [22 —— 目标侧](22-target-side.md) 一直列出的那些，包也可以在
+`cfg(c-abi = …)` 谓词里与它们比较。按字面量 `gnu` 取值判断的客户端需要更新；
 `musl`、`picolibc`、`libSystem` 不受影响。
 
-**`reason` 是一个记号,不是一句话。** 拒绝的消息仍然写给人看,仍然点名目标、
-规则与出路;而一个要给结果分类的程序读 `reason`:
+**`reason` 是一个记号，不是一句话。** 拒绝的消息仍然是写给人看的，仍然点名
+目标、规则与出路 —— 但一个要给结果分类的程序读的是 `reason`：
 
 | `reason` | |
 |---|---|
-| `unknown-target` | 这个拼写不指向任何一行,`(arch, os)` 也没有对应的组 |
-| `ambiguous-request` | 该 `(arch, os)` 有多行受支持,而词法默认不在其中 |
-| `compiler-requirement-conflict` | 图要求的编译器在这里用不了 |
-| `tier-planned` | 词表里有这一行,还没有任何东西接线 |
-| `host-cannot-serve` | 本机没有载荷,依赖也没有供给这个系统 |
-| `capability-pin` | 这一行的工具链是能力陈述,不是偏好 |
-| `convention-unreplaced` | 约定被推翻了,而没有任何东西接替它 |
-| `os-mismatch` | 请求的与解析出的三元组指向不同的操作系统 |
-| `layer-requirement` | 某个包要求的层,解析没有给出 |
-| `layer-ordering` | 五层叠不起来 |
-| `exclusive-capability` | 一个能力有多个提供者,而其中至少一个声明了独占 |
-| `version-floor-unmet` | 一个包对机器的要求高于机器被声明拥有的 |
+| `unknown-target` | 该拼写不对应任何一行，`(arch, os)` 也没有对应的组 |
+| `ambiguous-request` | 该 `(arch, os)` 有多行受支持，且没有一行是默认值 |
+| `compiler-requirement-conflict` | 图所要求的编译器在这里不可用 |
+| `tier-planned` | 词表里存在这一行，但还没有任何东西接线 |
+| `host-cannot-serve` | 本机没有载荷，也没有依赖供给这个系统 |
+| `capability-pin` | 这一行的工具链是一项能力陈述，不是一个偏好 |
+| `convention-unreplaced` | 约定被推翻了，而没有任何东西接替它 |
+| `os-mismatch` | 请求的三元组与解析出的三元组命名不同的系统 |
+| `layer-requirement` | 某个包要求的层，解析结果没有提供 |
+| `layer-ordering` | 五个层无法叠加 |
+| `exclusive-capability` | 一项能力有多个提供者，其中至少一个声明了独占 |
+| `version-floor-unmet` | 某个包对机器的要求，高于机器被声明拥有的水平 |
 | `accel-mismatch` | 一条 `[build] sources` 条目被约束到本次构建未覆盖的设备集合 |
-| `accel-backend-undeclared` | 一条 `[build] sources` 条目命名了本包 `[package] accelerators` 未列出的后端 |
-| `device-source-unconsumed` | 一个设备类源文件没有到达任何 action,因此没有东西编译它 |
-| `host-module-missing` | `build.mcpp` 导入了没有任何依赖以 host module 形式提供的模块 |
-| `tool-version-conflict` | 两处声明把同一个 xlings 包定在不能同时成立的版本上 |
-| `shared-library-cxx-runtime` | C++ 运行时来自图中的包,而依赖的 C++ 共享库没有声明私有副本 |
-| `offline-download-required` | 本次运行离线,而规划需要下载:工具链、包、git 修订或包索引 *(2026.9.16.1+)* |
-| `package-cycle` | 依赖图中存在包的环;消息列出环上的边 *(2026.9.16.1+)* |
-| `program-cxx-runtime-split` | 声明了自含 C++ 运行时的程序或测试,加载了本次构建中耦合到共享运行时的 C++ 共享库 *(2026.9.16.1+)* |
-| `static-package-in-two-images` | 一个静态包被本次构建的多个映像到达,而在该目标上一个映像不能使用另一个映像里的副本 *(2026.9.16.1+)* |
-| `c-env-unrealisable` | 解析出的 C 库的 `[c-abi]` 声明在这个目标上没有已知的实现,或解析出的编译器做不到 *(2026.9.18.1+)* |
-| `c-env-verification-mismatch` | 用实现出来的 `[c-abi]` 配置编译的探针,与声明不符 *(2026.9.18.1+)* |
-| `platform-dependency` | `[build] platform-dependencies = "refuse"`,而图里有包带进了平台 SDK *(2026.9.18.1+)* |
-| `interface-not-provided` | 某个包的 `[kernel-abi] requires-interfaces` 点名了解析出的实现不提供的接口 *(2026.9.20.1+)* |
-| `apple-sdk-absent` | 目标需要本机没有的 Apple SDK;它不可再分发,所以 mcpp 定位它而不安装它 |
-| `lld-required-absent` | 目标直接经 lld 链接,而解析出的工具链载荷不带 lld |
-| `host-tool-toolchain` | 交叉 `--target` 下的 `build.mcpp` 需要一个可解析的**宿主**工具链,而一个都没设 |
-| `std-module-precompile` | 标准库的模块在这个配置下无法预编译 |
-| `other` | 一处还没有被命名的拒绝分支 |
-
-**其中一个令牌也由 `mcpp build` 自己打印。** `interface-not-provided` 出现在拒绝消息里,
-用方括号包着,与 `E0006` 同一个约定。一条只有人能认出的拒绝,会逼迫每一个机器消费者去匹配
-散文——而那种散文,一个包自己的编译错误有可能恰好包含;mcpp-index 的兼容性测量正是靠这个
-令牌把「这个图不供给这个成员所要的」与「这个成员没能构建」分开,而这个区分决定了一个成员
-算不算进兼容率。
-
-**只要问题被回答了就退 0,包括答案是「拒绝」。** 「它能不能构建,不能的话
-为什么」被「不能,因为这一行的 pin 是能力陈述」完整地回答了。非零退出的含义是
-这次查询本身没跑起来。
-
-**它声明的 effects 故意偏宽。** `--protocol-version` 为这条命令列出
-`network`、`write-global-cache` 与 `exec-build-script`:答案来自与构建同一次的
-解析,而那可能拉取包、安装载荷、并运行某个依赖的构建程序。客户端是在**运行之前**
-读这张表来决定放不放行的,漏报一项就是一句不成立的安全承诺。
+| `accel-backend-undeclared` | 一条 `[build] sources` 条目命名的后端，未出现在该包自己的 `[package] accelerators` 中 |
+| `device-source-unconsumed` | 一个设备类源文件没有到达任何 action，因此没有任何东西编译它 |
+| `host-module-missing` | `build.mcpp` 导入的模块，没有任何依赖以 host module 的形式提供 |
+| `tool-version-conflict` | 两处声明把同一个 xlings 包定在不能同时成立的两个版本上 |
+| `shared-library-cxx-runtime` | 图所在的构建中，C++ 运行时是一个包，而某个依赖的 C++ 共享库没有声明私有副本 |
+| `offline-download-required` | 本次运行离线，而规划需要下载某样东西：工具链、包、git 修订，或包索引 *(2026.9.16.1+)* |
+| `package-cycle` | 依赖图中存在一个包的环；消息列出环上的边 *(2026.9.16.1+)* |
+| `program-cxx-runtime-split` | 一个声明了自含 C++ 运行时的程序或测试，加载了本次构建中耦合到共享运行时的 C++ 共享库 *(2026.9.16.1+)* |
+| `static-package-in-two-images` | 一个静态包被本次构建的多个映像到达，而在该目标上一个映像不能使用另一个映像里的副本 *(2026.9.16.1+)* |
+| `c-env-unrealisable` | 解析出的 C 库的 `[c-abi]` 声明在这个目标上没有已知的实现方式，或者解析出的编译器做不到这一点 *(2026.9.18.1+)* |
+| `c-env-verification-mismatch` | 用已实现出的 `[c-abi]` 配置编译出的探针，其结果与声明不符 *(2026.9.18.1+)* |
+| `platform-dependency` | `[build] platform-dependencies = "refuse"`，而图里有某个包带来了平台 SDK *(2026.9.18.1+)* |
+| `interface-not-provided` | 某个包的 `[kernel-abi] requires-interfaces` 点名了一个解析出的实现并不提供的接口 *(2026.9.20.1+)* |
+| `apple-sdk-absent` | 目标需要本机没有的一个 Apple SDK；它是被定位而不是被安装的，因为它不可再分发 |
+| `lld-required-absent` | 目标直接通过 lld 链接，而解析出的工具链载荷不带 lld |
+| `host-tool-toolchain` | 一个交叉 `--target` 下的 `build.mcpp` 需要一个可解析的**宿主**工具链，而一个都没有配置 |
+| `std-module-precompile` | 标准库的模块在这个配置下无法被预编译 |
+| `other` | 一个尚未被赋予记号的拒绝分支 |
+
+**其中一个记号也由 `mcpp build` 自己打印。** `interface-not-provided` 会
+出现在拒绝消息本身里，用方括号括着，与 `E0006` 是同一个约定。一个只有人能
+认出来的拒绝，会逼迫每一个机器消费方去匹配一段散文 —— 而这段散文，一个包
+自己的编译错误恰好也可能包含；mcpp-index 的兼容性测量正是靠这个记号，把
+「这个图没有供给这个成员所要求的」与「这个成员没能构建」区分开，而这个区分
+决定了一个成员算不算进兼容率。
+
+**只要问题被回答了就退出 0，包括答案是「拒绝」这种情况。** 「这次构建能不能
+成立，不能的话为什么」被「不能，因为这一行的 pin 是一项能力陈述」完整地
+回答了。非零退出的含义是这次查询本身没能运行起来。
+
+**它声明的 effects 故意偏宽。** `--protocol-version` 为这条命令列出了
+`network`、`write-global-cache` 与 `exec-build-script`：答案来自与一次构建
+相同的解析过程，而那个过程可能拉取包、安装载荷，并运行某个依赖的构建程序。
+客户端是在**运行之前**读这张表来决定是否放行的，漏报任何一项都等于给出一句
+不成立的安全承诺。
 
 ### `mcpp.build-database` —— 以构建数据库表达的构建计划 *(mcpp 2026.9.15.1+)*
 
@@ -392,33 +418,36 @@ mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
 mcpp emit build-database [--spec s1|compile-commands] --format json
 ```
 
-它按 `mcpp build --configure-only` 的方式、用相同的选择器规划,不写入工程目录。
-`data` 为:
+它按 `mcpp build --configure-only` 的方式、用相同的选择器规划，不写入项目
+目录。`data` 为：
 
 | 字段 | |
 |---|---|
-| `spec` | `{"name": "s1", "version": "0.2.0"}`;使用 `--spec compile-commands` 时为 `{"name": "compile-commands"}` |
-| `database` | 该规范的文档:S1 构建数据库,或 `mcpp build --configure-only` 写入 `compile_commands.json` 的条目 |
-| `watch` | 变化后可能改变文档的输入:相对工作区根的路径与 glob,或绝对路径 |
-| `inputs-fingerprint` | `fnv1a:<16 位十六进制>`,上述输入、mcpp 版本与选择器的摘要 |
-
-不带 `--format` 时命令只输出文档;`-o <file>` 把原本输出的内容写入 `<file>`。文档的
-内容、不写工程目录的保证与 `watch` 的规则见 [SPEC-005](../specs/build-database.md)。
-
-失败时省略 `data` 并以 1 退出:不在工程中时诊断码为 `MCPP_BUILD_DATABASE_NO_PROJECT`;
-离线规划(`--offline`、`MCPP_OFFLINE`、`MCPP_NO_AUTO_INSTALL`)需要下载某样东西(工具链、
-包、git 修订或包索引,消息指出第一个)时为 `MCPP_OFFLINE_DOWNLOAD_REQUIRED`;其他原因的
-规划失败为 `MCPP_BUILD_DATABASE_PLAN_FAILED`。第一种不是工程的缺陷,不带 `--offline`
-运行一次即可消除。警告不影响文档:
+| `spec` | `{"name": "s1", "version": "0.2.0"}`；使用 `--spec compile-commands` 时为 `{"name": "compile-commands"}` |
+| `database` | 该规范对应的文档：一份 S1 构建数据库，或者 `mcpp build --configure-only` 写入 `compile_commands.json` 的那些条目 |
+| `watch` | 一旦发生变化就可能改变这份文档的输入：相对工作区根目录的路径与 glob，或绝对路径 |
+| `inputs-fingerprint` | `fnv1a:<16 位十六进制>`，对上述输入、mcpp 版本与选择器求出的摘要 |
+
+不带 `--format` 时，命令只输出这份文档；`-o <file>` 会把原本要输出的内容
+写入 `<file>`。文档的内容、不写入项目目录这条保证，以及 `watch` 的规则，见
+[SPEC-005](../specs/build-database.md)。
+
+失败时省略 `data` 并以 1 退出，诊断码为：不在项目中时是
+`MCPP_BUILD_DATABASE_NO_PROJECT`；离线规划（`--offline`、`MCPP_OFFLINE`、
+`MCPP_NO_AUTO_INSTALL`）需要下载某样东西（工具链、包、git 修订，或包索引，
+消息会指出第一个）时是 `MCPP_OFFLINE_DOWNLOAD_REQUIRED`；因其他原因规划失败
+时是 `MCPP_BUILD_DATABASE_PLAN_FAILED`。三者中的第一种不是项目的缺陷：不带
+`--offline` 再运行一次即可消除它。警告不影响文档本身：
 
 | 诊断码 | |
 |---|---|
-| `MCPP_LOCK_WOULD_CHANGE` | 解析结果与工程的 `mcpp.lock` 不一致,命令不写这个文件 |
-| `MCPP_GENERATED_FILE_NOT_MATERIALIZED` | 根包 `[build] generated_files` 中的某个文件缺失或内容过期,命令不写这个文件 |
-| `MCPP_BUILD_DATABASE_STD_UNIT_UNDESCRIBED` | 没有标准库构建命令点名其模块源文件,该单元不被列出 |
+| `MCPP_LOCK_WOULD_CHANGE` | 解析结果与项目的 `mcpp.lock` 不一致，命令不写这个文件 |
+| `MCPP_GENERATED_FILE_NOT_MATERIALIZED` | 根包 `[build] generated_files` 中的某个文件缺失或内容已过期，命令不写这个文件 |
+| `MCPP_BUILD_DATABASE_STD_UNIT_UNDESCRIBED` | 没有任何标准库构建命令点名它的模块源文件，该单元因此不被列出 |
 
-`--protocol-version` 为这条命令声明 `init-mcpp-home`、`read-project`、`network`、
-`write-global-cache` 与 `exec-build-script`,从不声明 `write-project`。
+`--protocol-version` 为这条命令声明 `init-mcpp-home`、`read-project`、
+`network`、`write-global-cache` 与 `exec-build-script`，从不声明
+`write-project`。
 
 ### `mcpp.pack` —— 一次打包的产物 *(mcpp 2026.9.16.1+)*
 
@@ -426,18 +455,20 @@ mcpp emit build-database [--spec s1|compile-commands] --format json
 mcpp pack [target] [--format <f>] [--target <triple>...] --message-format json
 ```
 
-信封在命令结束后输出一次;所有给人读的行都走 stderr,包括打包启动的构建程序与工具的输出。
-`data` 为:
+信封在命令结束后输出一次；所有给人看的行都改走 stderr，包括打包过程启动的
+构建程序与工具输出的内容。`data` 为：
 
 | 字段 | |
 |---|---|
-| `artifacts` | 每个产物一条记录:`path`(绝对路径)、`type`(`file` 或 `directory`)、`format`(`--format` 取值,省略时为 `tar`)与 `targets`(进入该产物的每条腿的规范三元组)。分派格式报告本次请求引入的 action 的终端输出;多 `--target` 的 Android 打包报告一个产物,其 `targets` 列出每条腿 |
-| `stage` | 产物所来自的那棵树:`dir`、`manifest`(即下文的暂存清单)与 `closure`(`walked` 或 `not-walked`);库包以及未暂存任何树时为 `null` |
+| `artifacts` | 每个产出的产物一条记录：`path`（绝对路径）、`type`（`file` 或 `directory`）、`format`（`--format` 的取值，省略时为 `tar`），以及 `targets`（进入该产物的每条腿的规范三元组）。被分派的格式报告本次请求引入的那些 action 的终端输出；一个多 `--target` 的 Android 打包报告一个产物，其 `targets` 列出每一条腿 |
+| `stage` | 该产物所来自的那棵树：`dir`、`manifest`（即下文的暂存清单）与 `closure`（`walked` 或 `not-walked`）；库包，以及没有暂存任何树的情形，此字段为 `null` |
 
-失败时省略 `data`,以命令自身的退出码退出,并带诊断码 `MCPP_PACK_FAILED`;原因在 stderr 上。
-每次运行的 `effects` 为 `read-project`、`write-project` 与 `write-global-cache`,有构建程序运行时
-再加 `exec-build-script`。`--protocol-version` 为 `pack` 声明 `init-mcpp-home`、
-`read-project`、`write-project`、`network`、`write-global-cache` 与 `exec-build-script`。
+失败时省略 `data`，以命令自身的退出码退出，并携带诊断码
+`MCPP_PACK_FAILED`；原因写在 stderr 上。每次运行的 `effects` 是
+`read-project`、`write-project` 与 `write-global-cache`，若运行了某个构建
+程序则再加上 `exec-build-script`。`--protocol-version` 为 `pack` 声明
+`init-mcpp-home`、`read-project`、`write-project`、`network`、
+`write-global-cache` 与 `exec-build-script`。
 
 ### `mcpp test --message-format json` —— 测试流
 
@@ -445,76 +476,83 @@ mcpp pack [target] [--format <f>] [--target <triple>...] --message-format json
 mcpp test [pattern] [--workspace] --message-format json
 ```
 
-这条流早于 §2 的信封,也不被信封包裹:它是 NDJSON,每个测试结束时一条记录,随后每个
-成员一条汇总记录。`--workspace` 运行以一条 `workspace_summary` 记录结束。§7 的保证
-对它同样成立 —— 字段只增不减,字段含义不变 —— 下表是 2026.9.2.1 时的契约。
+这条流早于 §2 的信封，也不被它包裹：它是 NDJSON，每个测试结束时一条记录，随后
+每个成员一条汇总记录。`--workspace` 运行以一条 `workspace_summary` 记录
+结束。§7 的保证对它同样成立 —— 字段只增不减，字段含义永不改变 —— 下表是
+2026.9.2.1 时点的契约。
 
-每个测试:
+每个测试：
 
 | 字段 | |
 |---|---|
-| `member` | workspace 成员;workspace 之外为 `""` |
-| `test` | 按路径命名的测试名(`tests/00-a/0.cpp` → `00-a/0`) |
+| `member` | 所属的 workspace 成员；在 workspace 之外为 `""` |
+| `test` | 按路径命名的测试名（`tests/00-a/0.cpp` → `00-a/0`） |
 | `status` | `pass`、`compile_fail`、`run_fail`、`not_run` 或 `built` |
-| `exit_code` | 测试的退出状态;`not_run` 与 `built` 时为 `0` |
-| `signal` | 状态编码了信号时是信号号,否则 `null` |
-| `duration_ms` | 这个测试构建+运行的墙钟时间 |
-| `timed_out` | 被 `--timeout` 杀掉时为 `true`(`run_fail`) |
-| `compile_output`、`run_output` | 捕获的诊断输出 |
-| `reason` | 仅 `not_run`:一句话说明原因;其余为 `""` |
+| `exit_code` | 该测试的退出状态；`not_run` 与 `built` 时为 `0` |
+| `signal` | 状态编码了信号时为信号编号，否则为 `null` |
+| `duration_ms` | 该测试构建加运行的墙钟时间 |
+| `timed_out` | 被 `--timeout` 杀掉时为 `true`（`run_fail`） |
+| `compile_output`、`run_output` | 捕获到的诊断输出 |
+| `reason` | 仅 `not_run` 时：一句话说明原因；其余情况为 `""` |
 
-汇总记录 `{"summary": {...}}`:
+汇总记录，`{"summary": {...}}`：
 
 | 字段 | |
 |---|---|
 | `member`、`passed`、`failed` | 计数 |
 | `not_run` | 已构建但没有执行的测试数 |
-| `not_run_reason` | 它们共同的原因,或 `""` |
+| `not_run_reason` | 它们共同的原因，或 `""` |
 | `built` | 在 `--no-run` 下构建、本就不打算执行的测试数 |
-| `elapsed_ms`、`build_ms`、`run_ms` | 墙钟时间,分段 |
-
-**`built` 与 `not_run` 是两个不同的答案,分开计数。** 两者描述的都是「编译了但没有
-执行」的测试,相似之处到此为止:`not_run` 意味着 mcpp 试过而做不到,因此问题仍然悬着,
-退出码是 2;`built` 意味着 `--no-run` 要求不要执行,因此构建就是问题的全部,退出码是 0。
-把两者相加的消费方,会把一次它从未要求过的运行,报成一次无法完成的运行。
-
-**`not_run` 既不是 `pass` 也不是 `run_fail`,退出码也这么说(2026.9.2.1)。**
-本机无法加载测试产物(交叉目标未声明 runner 时的 `Exec format error`),或声明的
-`[target.<triple>].runner` 找不到、启动不了时,测试为 `not_run`。这是关于整次调用的
-事实:确立一次,其余测试直接报告为 `not_run` 而不再启动,进程以 **2** 退出。退出码 1
-含义不变 —— 有测试运行并失败;0 表示每个测试都运行并通过。只读退出码判 pass/fail 的
-客户端必须处理 2;由 `failed == 0` 推断「全部通过」的客户端还必须读 `not_run`。
-
-`workspace_summary` 增加 `tests_not_run`(各成员之和)、`tests_built`(`--no-run` 下
-构建的测试数之和)与 `unrunnable_members`(所有测试都 `not_run` 的成员),与既有的
-`not_run` 列表并列;后者仍然指 `--workspace-timeout` 到达时尚未开始的成员。
-`tests_built` 与 `tests_not_run` 分开,理由和逐成员的那两个字段一样:一个是被悬着的
-问题,另一个是压根没问的问题。
+| `elapsed_ms`、`build_ms`、`run_ms` | 墙钟时间，分段给出 |
+
+**`built` 与 `not_run` 是两个不同的答案，分开计数。** 两者描述的都是一个
+编译过、没有执行的测试，相似之处到此为止：`not_run` 意味着 mcpp 试过而做不
+到，问题因此仍然悬而未决，退出码是 2；`built` 意味着 `--no-run` 要求不要
+执行，构建就是问题的全部，退出码是 0。把两者相加的消费方，会把一次它从未要求
+过的运行，报告成一次没能完成的运行。
+
+**`not_run` 既不是 `pass` 也不是 `run_fail`，退出码也说明了这一点
+（2026.9.2.1）。** 当本机无法加载测试产物时（比如交叉目标未声明 runner 时的
+`Exec format error`），或者声明的 `[target.<triple>].runner` 找不到、启动不
+了时，该测试被标记为 `not_run`。这是关于整次调用的事实：它被确立一次之后，
+其余测试直接报告为 `not_run` 而不再启动，进程以 **2** 退出。退出码 1 的含义
+不变 —— 有测试运行过并且失败了；0 表示每个测试都运行过并且通过了。只按退出
+码判断 pass/fail 的客户端必须处理 2 这个值；由 `failed == 0` 推断「全部通过」
+的客户端也必须读取 `not_run`。
+
+`workspace_summary` 增加了 `tests_not_run`（各成员之和）、`tests_built`
+（`--no-run` 下构建的测试数之和）与 `unrunnable_members`（所有测试都是
+`not_run` 的那些成员），与既有的 `not_run` 列表并列；后者仍然指
+`--workspace-timeout` 到期时尚未开始的那些成员。`tests_built` 与
+`tests_not_run` 分开计数，理由与逐成员的那两个字段相同：一个是被悬置的问题，
+另一个是压根没被问过的问题。
 
 ### 暂存清单
 
-`mcpp pack` 在它暂存的树旁边写出 `<staged tree>.stage-manifest`,点名
-`${mcpp.stage_dir}` 的 `artifact` action 依赖这个文件(见
-[30](30-build-mcpp.md#产出可分发物pack_format-与-stage_dir20269111))。它是按行
-组织的文本文件而不是 JSON 信封,各行按以下顺序构成三块:
+`mcpp pack` 在它暂存的树旁边写出 `<staged tree>.stage-manifest`，一个点名
+`${mcpp.stage_dir}` 的 `artifact` action 依赖这个文件（见
+[30](30-build-mcpp.md#产出可分发物pack_format-与-stage_dir20269111)）。它是
+一个按行组织的文本文件，而不是一个 JSON 信封，各行按下列顺序构成三块：
 
 | 行 | 内容 |
 |---|---|
-| `closure = walked` 或 `closure = not-walked` | 第一行:树所需的每一个库是否都已解析 |
-| `reason = <text>` | 仅在 `closure = not-walked` 时出现;一行 |
-| `needs<TAB><name><TAB><where>` *(mcpp 2026.9.14.2+)* | 闭包读到的每个库名一行,已排序;`<where>` 是暂存库相对于树的路径、目标提供的库记为 `platform`,或 `unresolved` |
-| `<size> <path>` 或 `link <path>` | 每个暂存文件或符号链接一行,已排序 |
+| `closure = walked` 或 `closure = not-walked` | 第一行：树所需要的每一个库是否都已解析 |
+| `reason = <text>` | 只在 `closure = not-walked` 时出现；一行 |
+| `needs<TAB><name><TAB><where>` *(mcpp 2026.9.14.2+)* | 闭包读到的每一个库名各占一行，已排序；`<where>` 是暂存库相对于树的路径、目标机提供的库记为 `platform`，或 `unresolved` |
+| `<size> <path>` 或 `link <path>` | 每一个暂存文件或符号链接各占一行，已排序 |
 
-`<name>` 按需要它的对象的拼写给出:`DT_NEEDED` 条目、PE 导入名或 Mach-O install
-name。`needs` 行的字段以 TAB 分隔,因为名字与路径都可能含空格。不打包任何东西的
-模式(`system`、`static`)暂存的树不带 `needs` 行,更早的 mcpp 暂存的树同样不带;
-自行放置库的读者读这些行,而不是从 `lib/` 下的文件推断闭包。
+`<name>` 按需要它的对象自己的拼写给出：一条 `DT_NEEDED` 条目、一个 PE 导入
+名，或一个 Mach-O install name。`needs` 行的各字段以 TAB 分隔，因为名字与
+路径都可能包含空格。一棵由不打包任何东西的 mode（`system`、`static`）暂存
+出的树不带 `needs` 行，由更早版本的 mcpp 暂存出的树同样不带；自行放置库的
+读者应当读取这些行，而不是从 `lib/` 下的文件推断闭包。
 
 ## 当前边界
 
-- **退出码表的作用域只到它点名的那些命令。** 别的命令返回的码不在表里,而把它加进来
-  等于记录一件那些命令承诺不了的事。
-- 没有位置的诊断会**省略** `path` 与 `range`,而不是送 0:`line: 0` 会指向一个不存在
-  的位置。
-- stdout 上没有 JSON 就意味着「不支持」,无论原因是什么 —— 旧版引擎、未知选项,或者
-  这条命令根本没有机器格式。客户端仅凭这条流分辨不出这三者。
+- **退出码表的作用域仅限于它点名的那些命令。** 别的命令返回的退出码不在表
+  里，把它加进来等于记录一件这些命令承诺不了的事。
+- 一条没有位置的诊断会省略 `path` 与 `range`，而不是发送 0：`line: 0` 会指向
+  一个不存在的位置。
+- stdout 上没有 JSON，就意味着「不支持」，无论原因是什么 —— 一个较旧的引擎、
+  一个未知选项，或者一条根本没有机器格式的命令。客户端仅凭这一条流本身，分辨
+  不出这三种情况。
diff --git a/docs/zh/51-supported-versions.md b/docs/zh/51-supported-versions.md
index f0a3588f6..11df5ecf4 100644
--- a/docs/zh/51-supported-versions.md
+++ b/docs/zh/51-supported-versions.md
@@ -1,94 +1,97 @@
 # 51 —— 受支持的版本与兼容性
 
-**读者:**带着政策问题来的人 —— 一次评审流程、一次隔网构建、一个被钉住的版本。
+**读者：**带着政策问题而来的人——一次评审流程、一次隔网构建、一个被钉住的版本。
 
-**本章回答的那一个问题:**哪些发布受支持、版本之间什么可以变、什么不可以。
+**本章回答的那一个问题：**哪些发布受支持、支持多久，以及版本之间什么可以变、
+什么不可以变。
 
-**不在这里:**退出码表,那是 [SPEC-003](../specs/exit-codes.md);以及机器输出的
-schema,那是 [50 —— 机器可读输出](50-machine-output.md)。
+**不在这里：**退出码表，那是 [SPEC-003](../specs/exit-codes.md)；机器输出的
+schema，那是 [50 —— 机器可读输出](50-machine-output.md)。
 
-本文陈述哪些发布受支持、支持多久、以及版本之间什么可以变化。它之所以存在,是因为
-一个采用 mcpp 的工程会被它自己的评审流程问到这些问题,而只活在维护者脑子里的答案
-无法被引用。
+本文陈述哪些发布受支持、支持多久，以及版本之间允许发生什么变化。它的存在是因为
+一个采用 mcpp 的工程会被自身的评审流程问到这些问题，而只存在于维护者脑子里的
+答案无法被引用。
 
 ## 版本号
 
-发布以 `YYYY.M.D.N` 命名 —— 发布日期,加上当天发布的序号。这套方案的数字**不携带
-任何兼容性承诺**:`2026.9.4.1` 不是 `2026.9.3.2` 的「小版本」。什么可以变、什么
-不可以,由下文陈述,而不是编码在数字里。
+发布以 `YYYY.M.D.N` 命名——发布日期，加上当天发布的序号。这套方案的数字不携带
+任何兼容性承诺：`2026.9.4.1` 不是 `2026.9.3.2` 的「小版本」。什么可以变、什么
+不可以变，由下文陈述，而不是编码在版本号里。
 
 ## 支持范围
 
 | | |
 |---|---|
 | **受支持** | 最新的一个发布 |
-| **安全修复** | 最新的发布,以及上一个自然月的最后一个发布 |
+| **安全修复** | 最新的发布，以及上一个自然月的最后一个发布 |
 | **不受支持** | 更旧的一切 |
 
-一个发布是被取代,而不是被撤回。更旧版本的已发布资产与索引条目原样保留,因为某个
-工程可能钉住了它,移除会弄坏一个本来正常的构建。
+发布是被取代，不是被撤回。更旧版本的已发布资产与索引条目保持原位，因为某个工程
+可能钉住了其中一个，移除会破坏一个本来能正常构建的工程。
 
 ## 版本之间允许的变化
 
-引擎自身的各个接口稳定性并不相同,这个差别值得精确陈述。
+引擎自身各个接口的稳定性并不相同，这个差别值得精确陈述。
 
 | 面 | 稳定性 |
 |---|---|
-| `mcpp.toml` 的键 | 只增。既有键保持其含义;无法识别的键会被报告,绝不静默忽略 |
-| CLI 命令与旗标 | 只增。被取代的拼写保留为别名 |
-| 机器输出(`--message-format json`) | 由 `schemaVersion` 版本化,见 [50](50-machine-output.md) |
-| `build.mcpp` 指令协议 | 版本化,见 `kProtocolVersion`。引擎遇到声明**更高**版本的程序会拒绝,而不是猜测 |
-| `mcpp.lock` 格式 | 由 `schemaVersion` 版本化;更旧的文件在读取时迁移 |
-| 目标表的行 | 只增。一行的档位可以上升;只要还有已发布的包以它为目标,该行不会被移除 |
-| 构建指纹、缓存布局、`target/` 的内容 | **不是接口。** 它们不经通知即变化,任何东西都不应解析它们 |
-
-一个调用了其引擎自带 `mcpp` 模块中不存在的函数的 `build.mcpp`,失败发生在构建
-程序的**编译**期,而不是通过协议错误。协议号管的是线上的指令;类型化 API 由装的是
-哪个引擎决定。两者都写在这里,是因为包作者看到的失败取决于他越过了哪一条。
+| `mcpp.toml` 的键 | 只增。既有键保持原有含义；无法识别的键会被报告，不会被静默忽略 |
+| CLI 命令与旗标 | 只增。被替换的拼写保留为别名 |
+| 机器输出（`--message-format json`） | 由 `schemaVersion` 版本化，见 [50](50-machine-output.md) |
+| `build.mcpp` 指令协议 | 版本化，见 `kProtocolVersion`。引擎遇到声明版本**高于**自身的程序会拒绝，而不是猜测 |
+| `mcpp.lock` 格式 | 由 `schemaVersion` 版本化；更旧的文件在读取时被迁移 |
+| 目标表的行 | 只增。一行的档位可以上升；只要还有已发布的包以它为目标，该行就不会被移除 |
+| 构建指纹、缓存布局、`target/` 的内容 | **不是接口。** 它们不经通知即变化，任何东西都不应解析它们 |
+
+一个调用了自身引擎所带 `mcpp` 模块中不存在的函数的 `build.mcpp`，失败发生在
+构建程序的**编译**阶段，而不是通过协议错误。协议号管的是线上的指令；类型化 API
+由所装的引擎决定。两者都写在这里，是因为包作者看到的失败取决于他越过了哪一条边界。
 
 ## 复现一次构建
 
-`mcpp.lock` 记录一次构建解析出了什么。`--locked` 断言解析与它一致,不一致则失败并
-点名移动了的那个包:
+`mcpp.lock` 记录一次构建解析出的结果。`--locked` 断言当前解析与它一致，不一致
+则失败，并点名发生变化的那个包：
 
 ```
 error: --locked was given and this resolution differs from mcpp.lock:
          mcpplibs.cmdline 0.0.1 -> 0.0.2
 ```
 
-发布构建、审计或 CI 作业应当传 `--locked`。它会关掉构建快路径,因此断言总会跑到。
+发布构建、审计或 CI 作业应当传入 `--locked`。它会关闭构建快路径，因此该断言
+总会执行。
 
-锁**尚未约束**解析 —— 它记录并校验解析。把锁作为解析的输入来钉住它,是对解析器
-的另一项改动。
+锁尚不约束解析——它只记录并校验解析结果。把锁作为解析的输入来钉住结果，是对
+解析器的另一项改动。
 
 ## 物料清单
 
-`mcpp emit sbom` 写出一份描述**已记录**解析的 CycloneDX 1.5 文档:
+`mcpp emit sbom` 写出一份描述**已记录**解析结果的 CycloneDX 1.5 文档：
 
 ```bash
 mcpp emit sbom -o sbom.json
 ```
 
-它读 `mcpp.lock` 而不是重新解析,因为一份描述了与所构建者不同的图的文档,比没有
-文档更糟。mcpp 不知道其许可证的组件被写成 `NOASSERTION` 而不是省略:缺席的字段
-读起来像「未检查」。
+它读取 `mcpp.lock` 而不是重新解析，因为一份描述了与实际构建不同的依赖图的
+文档，比没有文档更糟。许可证 mcpp 无法识别的组件会被写成 `NOASSERTION` 而不是
+省略：缺失的字段读起来像「未检查」。
 
-## 离线与内网使用
+## 离线与隔网使用
 
-`--offline`(或 `MCPP_OFFLINE=1`)阻止一切网络访问:索引刷新、包下载与工具链安装。
-需要其中之一的构建会点名它所需要的东西然后失败,而不是伸手出去。
+`--offline`（或 `MCPP_OFFLINE=1`）会阻止一切网络访问：索引刷新、包下载与
+工具链安装。需要其中之一的构建会点名自己所需要的东西并失败，而不是尝试联网。
 
 ## 报告问题
 
-缺陷与安全报告提交到拥有该组件的仓库的 issue tracker —— 引擎、包索引,或者那个包
-自身。一份点明了版本、宿主、目标与命令的报告是可执行的;没有这四样的报告通常换来
-一次索要它们的回复。
+缺陷与安全报告提交到拥有该组件的仓库的 issue tracker——引擎、包索引，或者
+包本身。一份点明了版本、宿主、目标与命令的报告是可处理的；缺了这四项的报告
+通常会换来一次索要它们的回复。
 
 ## 当前边界
 
-- **`mcpp.lock` 目前还不约束解析。** 它记录一次构建解析出的结果,`--locked` 核验新的
-  解析与它一致;把锁作为解析的**输入**来钉住结果,是对解析器的另一项改动。
-- SBOM 描述的是**已记录的**那次解析,而不是重新解析一次,所以在改了 manifest 之后、
-  `mcpp update` 之前写出的文档,描述的是更早的那张图。
-- 许可证 mcpp 不认识的组件会被写成 `NOASSERTION` 而不是省略,因为缺失的字段读起来
-  是「没有检查过」。
+- **`mcpp.lock` 目前尚不约束解析。** 它记录一次构建解析出的结果，`--locked`
+  核验新的解析与它一致；把锁作为解析的**输入**来钉住结果，是对解析器的另一项
+  改动。
+- SBOM 描述的是**已记录**的那次解析，而不是重新解析一次，因此在修改 manifest
+  之后、执行 `mcpp update` 之前写出的文档，描述的是更早的那张依赖图。
+- 许可证 mcpp 无法识别的组件会被写成 `NOASSERTION` 而不是省略，因为缺失的
+  字段读起来像「未检查」。
diff --git a/docs/zh/90-build-from-source.md b/docs/zh/90-build-from-source.md
index b9cc2a285..a990f457f 100644
--- a/docs/zh/90-build-from-source.md
+++ b/docs/zh/90-build-from-source.md
@@ -1,20 +1,21 @@
 # 90 —— 从源码构建与参与贡献
 
-**读者:**要构建并修改 mcpp 本身的贡献者。
+**读者：** 要构建并修改 mcpp 本身的贡献者。
 
-**本章回答的那一个问题:**mcpp 怎样从源码构建、它自己的测试怎样组织,以及一次
-贡献要满足什么。
+**本章回答的那一个问题：** mcpp 怎样从源码构建、它自己的测试怎样组织，以及
+一次贡献要满足什么。
 
-**不在这里:**用户怎样构建自己的工程,那是 [01 —— 快速开始](01-getting-started.md);
-以及一次发布怎样切出来,那是 [92 —— 发布 mcpp](92-release.md)。
+**不在这里：** 用户怎样构建自己的工程，那是
+[01 —— 快速开始](01-getting-started.md)；以及一次发布怎样切出来，那是
+[92 —— 发布 mcpp](92-release.md)。
 
-> mcpp 采用自托管模式 —— 通过 mcpp 自身从源码构建 mcpp。
-> 任何已具备可运行 mcpp 二进制的环境均可完成源码构建。
+> mcpp 是自托管的——mcpp 通过自身从源码构建 mcpp。
+> 任何已经具备可运行 mcpp 二进制的环境，都可以从源码构建。
 
 ## 准备
 
-参照 [01 — 快速开始](01-getting-started.md) 安装一份现成的 mcpp,
-然后克隆仓库:
+按照 [01 —— 快速开始](01-getting-started.md) 安装一份可用的 mcpp，然后
+克隆仓库：
 
 ```bash
 git clone https://github.com/mcpp-community/mcpp
@@ -24,152 +25,169 @@ cd mcpp
 ## 构建与测试
 
 ```bash
-mcpp build              # 使用现成 mcpp 编译当前源码 → ./target/.../bin/mcpp
-mcpp run -- --version   # 运行刚构建出的产物
-mcpp test               # 构建并运行 tests/**/*.cpp 中发现的 C++ 测试(包含 tests/unit)
+mcpp build              # compile the current source with the existing mcpp → ./target/.../bin/mcpp
+mcpp run -- --version   # run the artifact you just built
+mcpp test               # build and run C++ tests discovered under tests/**/*.cpp (including tests/unit)
 ```
 
-`mcpp test` 不执行 `tests/e2e/` 下的 shell 端到端套件;应单独让它使用刚构建的二进制。
+`mcpp test` 不运行 `tests/e2e/` 下的 shell 端到端套件；应针对刚构建出的
+二进制单独运行这些脚本。
 
-首次构建会自动拉取默认工具链,详见
-[20 — 工具链管理](20-toolchains.md)。
+首次构建会自动拉取默认工具链，详见
+[20 —— 工具链管理](20-toolchains.md)。
 
-如需生成与 release 一致的全静态二进制(对应 `release.yml` 走的路径):
+要生成与一次 release 完全一致的全静态二进制（`release.yml` 走的正是这条
+路径）：
 
 ```bash
 mcpp build --target x86_64-linux-musl
-# → target/x86_64-linux-musl/.../bin/mcpp 为全静态 ELF
+# → target/x86_64-linux-musl/.../bin/mcpp is a fully static ELF
 ```
 
 ## 源码结构
 
-mcpp 是一个**工作空间**。`modules/` 里是引擎 import 的九个包;`src/` 是引擎本身。
+mcpp 是一个**工作空间**。`modules/` 下是引擎 import 的九个包；`src/` 是
+引擎本身。
 
 ```
-modules/                  工作空间成员,被 src/ import
-├── manifest/             manifest 与描述符解析
-├── platform/             操作系统抽象
-├── toolchain-model/      三元组、方言、指纹、链接模型
-├── buildmcpp/            build.mcpp 契约:协议、指令表、provisions
-├── source-kind/          源文件角色分类
-├── versioning/           本二进制的版本,以及 SemVer 约束解析
-├── dyndep/               ninja dyndep 产出
-├── libs/                 内嵌的文本格式解析器
-└── log/                  分级日志
+modules/                  workspace members, imported by src/
+├── manifest/             manifest and descriptor parsing
+├── platform/             operating-system abstraction
+├── toolchain-model/      triples, dialects, fingerprints, the link model
+├── buildmcpp/            the build.mcpp contract: protocol, directives, provisions
+├── source-kind/          source-file role classification
+├── versioning/           this binary's version, and SemVer requirements
+├── dyndep/               ninja dyndep emission
+├── libs/                 vendored text-format parsers
+└── log/                  leveled logging
 
 src/
-├── main.cpp              入口
-├── cli.cppm  cli/        命令分发与各条命令
-├── build/                构建编排与 ninja 后端
-├── modgraph/             P1689 模块扫描与依赖图
-├── pm/                   解析器与包管理命令
-├── toolchain/            探测、指纹、std 模块
-├── pack/  publish/       mcpp pack、mcpp publish 与 xpkg 产出
-├── fetcher/  fallback/   下载、安装、回退解析
-├── bmi_cache/            跨工程 BMI 缓存
-├── runtime/  xlings/     运行时契约与 xlings 桥
-├── freestanding/         裸机目标、链接行与 runner
-└── scaffold/             `mcpp new` 与模板
+├── main.cpp              entry point
+├── cli.cppm  cli/        command dispatch and the commands
+├── build/                build orchestration and the ninja backend
+├── modgraph/             P1689 module scanning and the dependency graph
+├── pm/                   the resolver and the package-management commands
+├── toolchain/            detection, fingerprinting, the std module
+├── pack/  publish/       mcpp pack, mcpp publish and xpkg generation
+├── fetcher/  fallback/   download, installation, fallback resolution
+├── bmi_cache/            the cross-project BMI cache
+├── runtime/  xlings/     the runtime contract and the xlings bridge
+├── freestanding/         bare-metal targets, link line and runner
+└── scaffold/             `mcpp new` and templates
 
 tests/
-├── unit/                 108 个 C++ 测试,由 `mcpp test` 发现
-└── e2e/                  370 个对真实二进制运行的 shell 脚本
+├── unit/                 108 C++ tests, discovered by `mcpp test`
+└── e2e/                  370 shell scripts against a real binary
 ```
 
 ## 测试组织
 
-两层,回答的是不同的问题。
+两层，回答的是不同的问题。
 
-**单元测试**(`tests/unit/`,108 个)是 `mcpp test` 发现的 C++ 程序。它们检验一个模块
-的契约,不需要二进制、也不需要文件系统状态。
+**单元测试**（`tests/unit/`，108 个文件）是 `mcpp test` 发现的 C++
+程序。它们检验一个模块的契约，不需要二进制、也不需要文件系统状态。
 
-**端到端测试**(`tests/e2e/NN_<name>.sh`,370 个)拿真实的 `mcpp` 二进制跑真实工程。
-`run_all.sh` 是 CI 的入口。`mcpp test` **不**运行它们。
+**端到端测试**（`tests/e2e/NN_<name>.sh`，370 个文件）拿真实的 `mcpp`
+二进制跑真实工程。`run_all.sh` 是 CI 的入口。`mcpp test` **不**运行它们。
 
 ```bash
-MCPP=<新构建的 mcpp 二进制> bash tests/e2e/02_new_build_run.sh
+MCPP=<fresh-mcpp-binary> bash tests/e2e/02_new_build_run.sh
 ```
 
-**由能力闸门决定哪些会跑。** e2e 脚本开头几行声明它需要什么,不具备该能力的 runner
-会跳过它:
+**由能力闸门决定哪些会跑。** e2e 脚本开头几行声明它需要什么，不具备该
+能力的 runner 会跳过它：
 
 ```bash
 #!/usr/bin/env bash
 # requires: elf gcc
 ```
 
-在用的有 `gcc`(80 个脚本)、`elf`、`unix-shell`、`llvm`、`jq` 与 `fresh-sandbox`。
-一个要求「任何 CI job 都不提供的能力」的脚本**在任何地方都不会跑**,它的绿色什么都不
-说明 —— 新增脚本时要核对确有 job 供给它所要的能力。
+在用的有 `gcc`（80 个脚本）、`elf`、`unix-shell`、`llvm`、`jq` 与
+`fresh-sandbox`。一个要求「任何 CI job 都不提供的能力」的脚本**在任何
+地方都不会跑**，它的绿色什么都不说明——新增脚本时要核对确有 job 供给
+它所要的能力。
 
 ## 写一条真的在测东西的判据
 
-本仓库最可迁移的一条规则,也是被跳过时会静默失效的那一条:
+本仓库最可迁移的一条规则，也是被跳过时会静默失效的那一条：
 
-> **写完判据之后,把修复拿掉,跑一次。** 从未被看见失败过的判据,不能说它测到了什么。
+> **写完判据之后，把修复拿掉，跑一次。** 从未被看见失败过的判据，不能说
+> 它测到了什么。
 
-它能抓住三种形态,每一种在这里都至少发生过一次:
+它能抓住三种形态，每一种在这里都至少发生过一次：
 
 | 形态 | 形式 |
 |---|---|
 | 判据从没跑到 | 测试被闸在一个没有任何 job 提供的能力上 |
-| 判据不可能失败 | 子串搜索,任何措辞都能满足它 |
-| 判据施加在错误的对象上 | 夹具目录跨次累积,于是搜索回答的是更早那次构建 |
+| 判据不可能失败 | 子串搜索，任何措辞都能满足它 |
+| 判据施加在错误的对象上 | 夹具目录跨次累积，于是搜索回答的是更早那次构建 |
 
-也要说出分母。「表里每一台宿主都被扫过」是一条判据;「扫描没发现问题」不是 —— 因为
-空的枚举同样什么都发现不了。
+也要说出分母。「表里每一台宿主都被扫过」是一条判据；「扫描没发现问题」
+不是——因为空的枚举同样什么都发现不了。
 
 ## 测试之外 CI 还跑的检查
 
-`.github/tools/` 里有十八个脚本。第一个 PR 之前值得知道的有四个:
+`.github/tools/` 里有十八个脚本。第一个 PR 之前值得知道的有四个：
 
 | 脚本 | 拒绝的内容 |
 |---|---|
-| `check_docs_style.sh` | 疑问句标题、参考章节里的第二人称、标题结构落后于英文的中文页 |
+| `check_docs_style.sh` | 疑问句标题、参考章节里的第二人称、标题结构落后于英文的 简体中文 页 |
 | `check_docs_structure.sh` | 章节引用设计记录、解析不到的 `docs/NN-*.md` 路径、翻译里少掉的表格 |
 | `check_version_pins.sh` | 版本号只写在一处而别处没跟上 |
-| `check_modules_wiring.sh` | 只接进了「三处必须知道它的地方」中的一部分的工作空间成员 |
-
-
-## 新增一个 manifest 字段:准入标准
-
-> **语法封闭,词汇开放**:谁拥有解析语义谁定义键;谁拥有领域知识谁定义值。
-
-- mcpp 只定义**机制**(features 并集/闭包、capability require/provide/override、
-  profile→编译器旗标、platform→triple),键与形状固定;feature 名、能力名、
-  后端名等**领域词汇只出现在值里**,不进 mcpp 代码。
-- **不支持包自定义 toml 键**:键合法性不得依赖"先解析目标包",否则 manifest
-  失去静态可解析性(lockfile/LSP/审计的前提)。包的扩展点 = 固定机制内的开放值域。
-- 包级旋钮统一收敛进 features;糖键(如 `backend=`)进入核心语法须满足:
-  ① 领域中立(跨生态通用模式)② 1:1 脱糖、零新增解析语义。
+| `check_modules_wiring.sh` | 只接进了「三处必须知道它的地方」中一部分的工作空间成员 |
+
+## 新增一个 manifest 字段：准入标准
+
+> **语法封闭，词汇开放**：谁拥有解析语义，谁定义键；谁拥有领域知识，
+> 谁定义值。
+
+- mcpp 只定义**机制**（feature 并集/闭包、capability
+  require/provide/override、profile→编译器旗标、platform→triple）；键与
+  形状是固定的。feature 名、能力名、后端名这类领域词汇**只出现在值
+  里**，绝不进入 mcpp 的代码。
+- **不支持包自定义 toml 键**：键的合法性不得依赖"先解析目标包"，否则
+  manifest 会失去静态可解析性（这是 lockfile / LSP / 审计的前提）。一个
+  包的扩展点 = 固定机制之内的开放值域。
+- 包级旋钮统一收敛进 feature；糖键（例如 `backend=`）要进入核心语法，须
+  满足：①领域中立（是跨生态的通用模式）②与既有语法 1:1 脱糖、零新增
+  解析语义。
+- **一个键若只是重复了别处已经给出的答案，就不被采纳。** 一件事有两处
+  可以陈述，就是两处可能互相矛盾，而这种失败是静默的——不论哪个读者
+  在这场竞速里落败，读到的就是错的。库的打包
+  （[12](12-binary-distribution.md)）是现成的例子：它新增了**零**个
+  manifest 键，因为打什么由 `[targets.<n>].kind` 回答，发布哪个接口由
+  `[lib]` 加模块图回答，哪些头文件是公开的由 `[build].include_dirs`
+  回答，每个产物的证据由 `[[runtime.artifacts]]` 回答。
+- 一个字段若描述的是某个**生成出来**的包**是什么**（而不是一次构建
+  应当**做什么**），就属于 `[[runtime.artifacts]]`——见 §2.11。
+  `provenance` 以 `mcpp-pack` 开头，正是这一标记让一个目录被认作生成出来
+  的产物，而 mcpp 拒绝在其内部执行 `build`。
 
 ## Issue 与 PR 提交规范
 
-
-
 ### Issue
 
-提交至 [github.com/mcpp-community/mcpp/issues](https://github.com/mcpp-community/mcpp/issues),
-建议附带以下信息:
+提交至 [github.com/mcpp-community/mcpp/issues](https://github.com/mcpp-community/mcpp/issues)，
+建议附带以下信息：
 
 - `mcpp self env` 的完整输出
-- 失败命令的完整输出(配合 `MCPP_LOG_LEVEL=debug` 可获得更详细信息)
-- 操作系统、发行版、glibc 版本(可通过 `ldd --version` 查看)
+- 失败命令的完整输出（配合 `MCPP_LOG_LEVEL=debug` 可获得更详细的信息）
+- 操作系统、发行版、glibc 版本（可通过 `ldd --version` 查看）
 
 ### Pull Request
 
-mcpp 处于早期迭代阶段,接口可能调整,提交 PR 前请注意:
+mcpp 处于早期迭代阶段，接口可能调整，提交 PR 前请注意：
 
-1. 涉及 CLI 或 `mcpp.toml` schema 的改动,建议先开 issue 对齐方向。
-2. 单个 PR 聚焦单一改动;commit 标题使用英文 imperative 形式
-   (`fix: ...` / `feat: ...`)。
-3. 行为改动或测试文档改动在提交前运行 `mcpp test`，并让相关 E2E 脚本使用刚构建的
-   二进制通过；纯文档改动复核示例和链接，并用 `gh pr checks <pr-number>` 确认 PR
-   实际 required checks。
+1. 涉及 CLI 或 `mcpp.toml` schema 的改动，请先开 issue 对齐方向。
+2. 单个 PR 只聚焦一处改动；commit 标题使用英文祈使式（`fix: ...` /
+   `feat: ...`）。
+3. 涉及行为改动或测试文档的改动，提交前针对刚构建出的二进制运行
+   `mcpp test` 与相关的 E2E 脚本。纯文档改动应复核示例与链接；用
+   `gh pr checks <pr-number>` 查看该 PR 实际的 required checks。
 
 ## 社区资源
 
 - [社区论坛](https://forum.d2learn.org/category/20)
-- 交流群 QQ: 1067245099
-- [mcpp-index](https://github.com/mcpplibs/mcpp-index) — 默认包索引
-- [mcpplibs](https://github.com/mcpplibs) — 配套的模块化 C++ 库集合
+- 交流群 QQ：1067245099
+- [mcpp-index](https://github.com/mcpplibs/mcpp-index)——默认包索引
+- [mcpplibs](https://github.com/mcpplibs)——配套的模块化 C++ 库集合
diff --git a/docs/zh/91-toolchain-internals.md b/docs/zh/91-toolchain-internals.md
index f935c8040..4a4ec2159 100644
--- a/docs/zh/91-toolchain-internals.md
+++ b/docs/zh/91-toolchain-internals.md
@@ -1,131 +1,148 @@
 # 91 —— 工具链机制内幕
 
-**读者:**贡献者,或者正在排查「工具链为什么解析成这样」的用户。
+**读者：** 贡献者，或者正在排查「工具链为什么解析成这样」的用户。
 
-**本章回答的那一个问题:**mcpp 实际上怎样解析、安装并拼装一条工具链,以及每个
+**本章回答的那一个问题：** mcpp 究竟如何解析、安装并组装一条工具链，以及每个
 flag 由哪一层决定。
 
-**不在这里:**怎样**选择**一条工具链,那是 [20 —— 工具链管理](20-toolchains.md)。
-本章是它底下的机制,而这里没有任何东西是稳定接口。
+**不在这里：** 如何**选择**一条工具链，那是
+[20 —— 工具链管理](20-toolchains.md)。本章讲的是它之下的机制，这里的任何内容
+都不是稳定接口。
 
-> 本文详细描述 mcpp 工具链机制的内部工作原理,以及如何扩充新工具链、新架构乃至
-> 嵌入式目标的支持。与面向用户的 [20 — 工具链管理](20-toolchains.md)(CLI 用法)
-> 互补,本文面向贡献者与维护者。
+> mcpp 工具链机制的内部工作原理，以及如何用新工具链、新架构，及（最终）嵌入式
+> 目标扩展它。与面向用户 CLI 的 [20 —— 工具链管理](20-toolchains.md) 互补。
+> 本文面向贡献者与维护者。
 
-## 1. 一张图看全模型
+## 1. 一张图看懂整个模型
 
 ```
-mcpp.toml [xlings].subos / mcpp 管理的默认运行时
+mcpp.toml [xlings].subos / mcpp-managed default runtime
         ▼
-解析 runtime binding             ← 产物将加载哪个 libc(§2.1)——是答案,不是搜索
+resolve runtime binding          ← which libc the artifact will load (§2.1) — an
+                                   answer, not a search
         ▼
-解析工具链 payload               ← 项目/default/install 入口共享同一管线
+resolve toolchain payload        ← project/default/install paths share one pipeline
         ▼
-ensure_post_install_fixup()      ← 精确 glibc@version、marker 闸门,不取 readdir 首项
+ensure_post_install_fixup()      ← exact glibc@version, marker-gated; never readdir-first
         ▼
-detect / probe                   ← triple、sysroot、payload 路径(glibc、linux-headers)
+detect / probe                   ← triple, sysroot, payload paths (glibc, linux-headers)
         ▼
-ToolchainLinkModel(C 库轴的唯一解析器)
-        ├──► flags.cppm        (主构建编译/链接 flags)
-        ├──► stdmod.cppm       (`import std;` BMI 预编译)
-        ├──► build_program     (build.mcpp 宿主编译)
-        └──► cfg 再生          (供人类直接使用的 clang++.cfg)
+ToolchainLinkModel (single resolver for the C-library axis)
+        ├──► flags.cppm        (main build compile/link flags)
+        ├──► stdmod.cppm       (`import std;` BMI precompile)
+        ├──► build_program     (build.mcpp host compiles)
+        └──► cfg regeneration  (the human-facing clang++.cfg)
         ▼
-hermetic 链接校验(`-###` 干跑)  ← 校验沙箱 CRT/loader 的解析结果
+hermetic link check (`-###` dry-run)  ← checks sandbox CRT/loader resolution
         ▼
-链接 → 内部 ELF 物理校验        ← 校验真实产物及解析闭包(§6.1)
+link → internal ELF physics check    ← validates the artifact and resolved closure (§6.1)
 ```
 
-贯穿一切的两条原则:
+贯穿全篇的两条原则：
 
-1. **沙箱工具链默认接受 hermetic 校验。** 在正常的 payload-first 或 sysroot 路径中,
-   产物的 CRT 启动对象、libc、动态链接器必须解析在允许的沙箱前缀内。这不是无条件的
-   隔离保证:`CLibMode::None` 会落到宿主默认,系统/PATH 编译器是显式选择宿主世界,
-   `[build] allow_host_libs = true` 或 `MCPP_ALLOW_HOST_LIBS=1` 会退出宿主库校验。
-   在没有编译器、没有 `/usr/lib/**/Scrt1.o` 的机器(全新 WSL2、精简容器)上,正常的
-   沙箱路径仍可工作。
-2. **每层路径知识只有一个属主。** 过去"如何对 payload glibc 链接"有四份漂移副本,
-   现在收敛为一个解析器(`linkmodel`);过去 fixup 行为按入口路径各自为政,现在
-   是一条管线。副本间漂移正是一整类 bug 的来源(issue #195)。
+1. **沙箱工具链默认接受 hermetic 校验。** 对于常规的 payload-first 或 sysroot
+   路径，产物的 CRT 启动对象、libc 与动态链接器必须解析到允许的沙箱前缀之下。
+   这不是一项无条件的隔离保证：`CLibMode::None` 会回落到宿主默认值，系统 /
+   PATH 编译器是显式选择宿主世界，`[build] allow_host_libs = true` 或
+   `MCPP_ALLOW_HOST_LIBS=1` 会退出宿主库检查。在既没有编译器、也没有
+   `/usr/lib/**/Scrt1.o` 的机器上（全新的 WSL2、精简容器），常规沙箱路径仍能
+   正常工作。
+2. **每一层的路径知识只有一个属主。** 过去「如何链接 payload glibc」有四份
+   彼此漂移的副本，现在收敛为一个解析器（`linkmodel`）；过去按入口路径各自
+   维护的 fixup 行为，现在是一条管线。副本之间的漂移正是一整类 bug 的来源
+   （issue #195）。
 
 ## 2. 工具链解析
 
-自 0.0.93 起,身份由两条正交轴构成:`ToolchainSpec` 是
-`(family ∈ gcc|llvm|msvc,version,target Triple)`。`triple.cppm` 负责唯一的
-triple 解析器与封闭的已知 target 词汇表;`compat.cppm` 只处理旧拼写
-(`gcc@15.1.0-musl`、`musl-gcc`、`mingw`、`mingw-cross`、`clang`、
-`<triple>-gcc`),解析时归一化且永久兼容。`to_xim_package` 把
-`(family,target,host)` 映射为含 xim 包名、版本、前端候选的
-`XimToolchainPackage`;这也是 Linux 宿主的 `mingw-cross-gcc` 与 Windows
-宿主的 `mingw-gcc` 等分发层名称存在的位置,它们不是面向用户的写法。payload 经
-xlings 后端解析/自动安装到沙箱
-(`$MCPP_HOME/registry/data/xpkgs/xim-x-<name>/<version>/`)。
+自 0.0.93 起，身份由两条正交的轴构成：`ToolchainSpec` 是
+`(family ∈ gcc|llvm|msvc, version, target Triple)`。`triple.cppm` 是唯一的
+triple 解析器，加上封闭的已知目标词汇表；`compat.cppm` 是唯一认识旧拼法的
+文件（`gcc@15.1.0-musl`、`musl-gcc`、`mingw`、`mingw-cross`、`clang`、
+`<triple>-gcc` —— 解析时归一化，永久接受）。`to_xim_package` 是一个
+*(family, target, host)* 到 payload 的映射，产出带 xim 包名、版本与前端候选
+的 `XimToolchainPackage` —— host 拆分的分发名，如 Linux 宿主上的
+`mingw-cross-gcc` 与 Windows 宿主上的 `mingw-gcc`，就存在于这一层；它们是
+当前分发层的身份，不是面向用户的拼法。payload 经 xlings 后端解析 / 自动
+安装到沙箱中（`$MCPP_HOME/registry/data/xpkgs/xim-x-<name>/<version>/`）。
 
-`detect`/`probe`(`src/toolchain/detect.cppm`、`probe.cppm`)随后推导:
+`detect`/`probe`（`src/toolchain/detect.cppm`、`probe.cppm`）随后推导出：
 
-| 字段 | 方式 |
+| Field | Derivation |
 |---|---|
 | `targetTriple` | `<compiler> -dumpmachine` |
-| `sysroot` | `-print-sysroot`(校验必须真带 libc 头);xlings 构建的 GCC 烙的是构建机路径,有 remap 回退 |
-| `payloadPaths` | 由解析出的 runtime binding(§2.1)**精确指名** glibc payload;linux-headers 仍按兄弟 xpkg 发现。没有 binding 就不走 payload-first——这是设计,不是缺陷 |
-| 运行库目录 | 工具链私有 lib 目录,用于产物的 `-L`/`-rpath` |
-
-### 2.1 runtime binding:绑定的 libc,只决定一次
-
-payload-first 的构建会链接到某个具体的 glibc,而**是哪一个**是根项目本地开发 OS 的事实,
-不该从编译器路径或 shell 状态推断。mcpp 只有两种选择:
-
-1. 未声明 `[xlings].subos`:使用全局 mcpp 配置所选 xlings home 中已初始化的
-   `McppDefault` (`subos/default`)。
-2. `[xlings] subos = "<name>"`:使用 `NamedSubos(name)`;显式 `"default"`
-   仍保留命名选择身份,其他名称解析到根项目的本地 xlings scope。
-
-workspace 构建由 workspace root 选择;member 与 dependency 声明不合并、不传递。
-`XLINGS_ACTIVE_SUBOS`、current、编译器 owner home 以及 CLI/环境 override 都不是第三层。
-**矛盾报错,缺席降级。** 点名的环境不存在是 hard error —— 该请求无法被满足,
-换一个环境会让同一份 `mcpp.toml` 在不同机器上意味着不同 ABI,绝不回退
-default/active/编译器烙入状态。
-
-而「环境存在但没有自我描述」是另一回事,它**降级**:记 `declared = false` 与一条
-调用方必须打印的 note;runtime 规则报 `inconclusive` 而不是给出判决;没有可用的
-payload-first binding(mcpp 拒绝猜一个 libc 版本,因而 hermeticity 检查会如实报告
-回退到宿主)。**构建不被中止。** 同理,`subos_info` 的 schema **高于**本 mcpp 所理解的
-版本时,读懂的字段照用并附 note —— 这正是读取器自己写下的规矩:**发布数据不得使
-读它的程序失效**。直接拒绝就是 2026.8.10.2 在 Windows 上停掉每一次 `mcpp build` /
-`mcpp test` 的原因(那里 xlings 根本不写这个 block,它承载的事实也不存在,
-openxlings/xlings#543)。
-
-该 contract 只读取一次形成 `RuntimeBinding` snapshot,
-由 configure/link/run/test 与 fast-path cache 共同使用。
-Linux snapshot 还记录所选 loader/libc 目录的规范路径及可选的创建宿主 glibc floor;
-它们是链接后校验的证据,不是新的选择入口。
-
-当解析后的 SubOS view 可规范化到一个受管 glibc payload 时，该真实 view 是权威事实。
-旧 xlings 状态可能在 view 已原子切到受管 2.44 后仍保留 `runtime = "glibc@2.39"`；此时
-mcpp 在同一 binding 中记录真实的 2.44 身份与路径。若旧 view 是断链，mcpp 只允许解析
-`runtime` 精确指名的 payload；不会枚举已安装版本，也不会挑“最近/最新”版本。两条路径
-都只消费 xlings 给出的事实，不引入 mcpp 自己的运行时选择策略。
-
-没有 binding 是**拒绝**而不是取默认值:`CLibMode::PayloadFirst` 会被放弃,而不是
-去挑一个 libc。
-
-被它取代的旧规则是:向某个目录问"那个 glibc",然后拿 `readdir` 吐出的第一项。
-只装了一个 glibc 时它永远正确,所以从来没有东西逼它正确——而一条带
-`xim:glibc@>=2.38` 的依赖就足以装进第二个。这在 mcpp-index 上真实发生过:编译侧
-取了 2.44,而产物的 interpreter(装机时冻结在 gcc specs 里)仍指向 2.39;二进制
-引用了 `GLIBC_2.42` 符号,却跑在没有这些符号的运行时上,且报错落在与"拉进第二个
-glibc 的那条依赖"毫无关系的包上。目录顺序不是决策依据。
-
-因为 binding 决定产物加载什么,完整规范化 contract hash 是工具链指纹第 11 个字段——
-即使两个命名 SubOS 都使用同一 glibc,只要 provider 或环境声明不同也绝不能共用缓存。
-
-注意:probe 已**不再**从 clang cfg 挖 `--sysroot`——cfg 是这套机制的输出,
-不是输入(见 §5)。
-
-### 2.2 通用运行时 provider 与 artifact
-
-`RuntimeBinding` 还携带 xlings 为所选开发 OS 解析好的 provider-neutral fact。
-`subos_info.runtime_contract` 是 schema 1 上可选、可加的 block:
+| `sysroot` | `-print-sysroot`（经校验：必须真的带有 libc 头文件），并为烙有构建期路径、在本机不存在的 xlings 构建版 GCC 提供 remap 回退 |
+| `payloadPaths` | 由已解析的 runtime binding（§2.1）精确指名 glibc payload；linux-headers 仍作为同级 payload 被发现。没有 binding 就没有 payload-first，这是设计使然 |
+| runtime dirs | 工具链私有的 lib 目录，供产物的 `-L`/`-rpath` 使用 |
+
+注意，probe 刻意**不再**从 clang cfg 中挖 `--sysroot`：cfg 是这套机制的输出，
+不是输入（见 §5）。
+
+### 2.1 runtime binding —— 一个 libc，只决定一次
+
+payload-first 的构建会链接到某一个具体的 glibc，而**是哪一个**，是根项目
+本地开发 OS 的事实，不应从编译器路径或 shell 状态推断。mcpp 恰好有两种
+选择方式：
+
+1. 未声明 `[xlings].subos`：使用 `McppDefault`，即全局 mcpp 配置所选 xlings
+   home 中已初始化的 `subos/default`。
+2. `[xlings] subos = "<name>"`：使用 `NamedSubos(name)`。显式写出的
+   `"default"` 仍然是一次具名选择；其他名字在根项目本地的 xlings scope 中
+   解析。
+
+workspace 构建期间由 workspace root 拥有这次选择。member 与 dependency 的
+声明既不合并也不传播；同一个 member 的声明只在它作为独立 root 时才生效。
+`XLINGS_ACTIVE_SUBOS`、`current`、编译器所属的 home，以及命令行 / 环境变量
+的 override，都不构成第三种选择层级。
+
+点名的环境不存在时是硬错误，绝不回退到 default / active / 编译器烙入的
+状态 —— 该请求无法被满足，而换成另一个环境会让同一份 `mcpp.toml` 在不同
+机器上对应不同的 ABI。
+
+而「SubOS 存在，但**没有自我描述**」是另一种情形，它会**降级**：
+`declared = false` 被记录下来，并附一条调用方必须打印的说明；runtime 规则
+报告 `inconclusive` 而不是给出判决；也没有 payload-first binding 可用
+（mcpp 拒绝去猜一个 libc 版本，因此 hermeticity 检查会如实报告回退到
+宿主）。构建不会因此中止。同理，当 `subos_info` 的 schema **新于**当前
+mcpp 所理解的版本时，mcpp 读取它认识的那些字段，并附一条说明 —— 这正是
+这个读取器自己写下的规则：发布数据不得使读取它的程序失效。直接拒绝正是
+2026.8.10.2 在 Windows 上让每一次 `mcpp build` 与 `mcpp test` 都停摆的
+原因：那里 xlings 根本不写这个 block，它承载的那些事实也就不存在
+（openxlings/xlings#543）。
+
+mcpp 只把 SubOS 读取一次，形成一份 `RuntimeBinding` 快照，把其中的 libc
+身份喂给 payload probing，并在 configure/link/run/test 与 fast-path cache
+中复用同一份快照。在 Linux 上，该快照还记录所选 loader/libc 目录的规范
+路径，以及可选的创建宿主 glibc 下限。这些是链接后校验器使用的证据，不是
+另一套选择机制。
+
+当解析出的 SubOS view 能够规范地指名一个受管的 glibc payload 时，它就是
+权威事实。较旧的 xlings 状态可能在 view 已原子切换到受管的 2.44 payload
+之后，仍保留着 `runtime = "glibc@2.39"`；此时 mcpp 记录的是真实的 2.44
+身份与路径。若较旧的 view 含有一条断链，mcpp 只会解析 `runtime` 精确指名
+的那个 payload；它从不枚举已安装版本，也不会挑选「最近的」或「最新的」
+那一个。两条路径都只消费 xlings 给出的事实，并保持单一的 RuntimeBinding，
+而不引入 mcpp 自己的运行时选择策略。
+
+没有 binding 是一次**拒绝**，不是取默认值：`CLibMode::PayloadFirst` 会
+被放弃，而不是去挑一个 libc。
+
+被它取代的旧规则，是向某个目录询问「那个 glibc」，然后取 `readdir` 吐出
+的第一项。只装了一个 glibc 时，这样做永远正确，因此从来没有什么迫使它
+正确 —— 而一条带 `xim:glibc@>=2.38` 的依赖就足以装进第二个 glibc。这在
+mcpp-index 上真实发生过：编译侧拿到的是 2.44，而产物的 interpreter（在
+安装时冻结进 gcc 的 specs 里）仍然指名 2.39；二进制引用了 `GLIBC_2.42`
+符号，却跑在没有这些符号的运行时上，故障浮现在与「拉进第二个 glibc 的
+那条依赖」毫无关系的包上。目录顺序不是一种决策依据。
+
+由于 binding 决定产物加载什么，完整的规范化 contract hash 是工具链指纹
+的第 11 个字段 —— 即使两个具名 SubOS 环境恰好使用同一个 glibc，只要它们
+的 provider 或环境声明不同，也绝不能共用同一条缓存记录。
+
+### 2.2 通用的 runtime provider 与 artifact
+
+`RuntimeBinding` 还携带 xlings 为所选开发 OS 解析出的、provider 无关的
+事实。`subos_info.runtime_contract` 是 schema 1 上一个可选、可加的
+block：
 
 ```json
 {
@@ -145,411 +162,471 @@ glibc 的那条依赖"毫无关系的包上。目录顺序不是决策依据。
 }
 ```
 
-binding parser 只解析一次 `${subosdir}` 和相对 artifact 路径,排序 fact,并把它们纳入
-contract hash 与 cache snapshot。进入 BuildPlan 后,所选 provider fact 排在描述符
-fallback 前。描述符 requirement/artifact 则由 resolver 分别用 requester/provider 的
-canonical PackageId 盖章,所以不同 namespace 下相同短名不会在任何环节碰撞。
+binding parser 只解析一次 `${subosdir}` 与相对的 artifact 路径，对这些事实
+排序，并把它们纳入 contract hash 与 cache snapshot。进入构建计划后，这些
+被选中的 provider 事实排在描述符声明的 fallback 之前。描述符的
+requirement 与 artifact 分别用各自解析出的 requester / provider 的规范
+PackageId 打上印记，因此不同 namespace 下相同的短名在全程都保持互不相同。
 
-所有权边界是刻意的:mcpp-index 表达通用 runtime requirement;xlings/xim 选择并诊断
-宿主图形/运行时栈;mcpp 只消费已选 provider/artifact fact 与通用 LinkIntent。
-mcpp 不含硬件、driver vendor、WSL 或 ICD 选择路径;源码 gate 会拒绝引入这类
-provider-specific 分支,也拒绝把相关词汇与外部 probe 启动耦合。
+这条所有权边界是刻意划定的：mcpp-index 表达的是通用的 runtime 需求；
+xlings/xim 负责选择并诊断宿主的图形 / 运行时栈；mcpp 只消费已选定的
+provider/artifact 事实，以及通用的 LinkIntent。mcpp 没有硬件、驱动厂商、
+WSL 或 ICD 的选择路径。它的源码 gate 拒绝引入这类 provider 专属分支，也
+拒绝把这些术语与某个被启动的探针耦合起来。
 
-`LinkIntent` 分开 `linkLibraryDirs`、`transitiveNeededDirs` 和
-`runtimeSearchDirs`;最后一类绝不渲染为 `-L`。ELF 只为 runtime 目录发 rpath,
-且仅为 transitive 类发 `-rpath-link`;Mach-O 发 rpath/framework;PE 发链接库路径并
-用显式 deploy-file copy edge。精确 RuntimeBinding、canonical identity、LinkIntent、
-搜索机制与链接后 verdict 写入 `resolution.json` schema 2。
-`mcpp why runtime` 只解释该存储文件;重新诊断由 `xlings doctor` 负责。
+`LinkIntent` 把 `linkLibraryDirs`、`transitiveNeededDirs` 与
+`runtimeSearchDirs` 分开维护。最后一类绝不会被渲染成 `-L`：ELF 只为
+transitive 这一类发出 rpath 加 `-rpath-link`，Mach-O 发出
+rpath/framework flag，PE 发出链接库路径外加显式的 deploy-file copy
+edge。精确的 RuntimeBinding、规范身份、link intent、搜索机制与链接后
+判决都持久化在 `resolution.json` schema 2 中。`mcpp why runtime` 只解释
+这份存储文件；重新诊断的职责属于 `xlings doctor`。
 
-### 2.3 运行期搜索闭包(`modules/platform/src/runtime_search.cppm`)
+### 2.3 运行期搜索闭包（`modules/platform/src/runtime_search.cppm`）
 
-mcpp 在**编译与链接**两条线上都发 `--sysroot=<subos>`,所以 subos 提供的库
-(`-lGL`、`-lX11`、`-lwayland-client`)零 flag 就能解析。运行期的搜索路径必须由
-**同一个决策**推导,否则就是「链得上、跑不起来」。
+mcpp 在编译**与**链接两条命令行上都传 `--sysroot=<subos>`，因此 SubOS
+提供的库 —— `-lGL`、`-lX11`、`-lwayland-client` —— 不需要用户加任何 flag
+就能解析。运行期搜索路径必须由同一个决策推导出来，否则链接会成功，而
+产物却无法启动。
 
-闭包是一张有序表,每条带来源:
+闭包是一张有序列表，每一条都标注了它的来源：
 
-| origin | 例子 | 可变性 | 可随产物分发 |
+| origin | 例子 | 可变性 | 可随产物再分发 |
 |---|---|---|---|
-| `payload` | `<store>/xim-x-glibc/2.39/lib64` | 否 —— 装一次不再动 | 否 |
-| `package` | 依赖描述符的 `[runtime]` 目录 | 否 | 否 |
-| `subos_farm` | `<subos>/lib` | **是** —— 每次 `xlings install` 重写 | 否 |
-| `host_default` | `/usr/lib/x86_64-linux-gnu` | 目标机自己的 | 不适用 |
-
-**次序 = 不可变性递减,farm 在最后。** 这是本模块唯一的不变式:载荷在前,
-`libc` / `libm` / `libstdc++` 永远从被 pin 的载荷解析,farm 只补没人提供的那些;
-farm 在前的话,一次 `xlings install` 就能在事后悄悄换掉一个**已经链接完成**的产物
-所加载的 libc。
-
-两条护栏决定 farm 是否适用:格式必须有搜索路径(ELF;Mach-O 与 PE 什么都不发,
-与加载器标签契约同一形状),且目标必须是本宿主的运行时 —— 交叉目标不发 farm,
-因为 farm 属于宿主 subos。
-
-`host_default` 只在产物**确实**跑在宿主加载器下时才进模型。hermetic 产物的
-`PT_INTERP` 指向私有加载器,它的内建默认路径不同;把 `/usr/lib` 算进去就是在模拟
-另一个加载器 —— 而开发机通常自带 `libGL.so.1`,于是「解析到了」会被报给一个
-退出 127 的产物。
-
-闭包记录在 `resolution.json` 的 `runtime.search.closure`,并由 `mcpp why runtime`
-打印。hermetic 产物上一个谁都提供不了的 `DT_NEEDED` 是**可证的**失败
-(`unresolvable`),不是「没查过」,它会让构建变红。`LD_DEBUG=libs` 实测:私有加载器的
-内建默认路径是 glibc 载荷**自己的构建期前缀**,该目录在本机并不存在 —— `/usr/lib`
-从不被查。
-
-有三件事收窄这个「可证」,每一件都是 mcpp 知道的比措辞暗示的少:
-
-- **产物的格式由产物决定,不由 binding 决定。** 交叉构建用的是本宿主的 binding,
-  产物却是 PE / Mach-O;无论 binding 怎么说,ELF 规则都不适用于它。
-- **只有「找不到的 SONAME」能证明什么。**「这个对象读不了」「我在 512 个之后停了」
-  都是关于**检查**的陈述;没能看的检查什么都没证明,故仍报 inconclusive。
-- **`[build] allow_host_libs` 同时退出两个阶段。** 它本就关掉链接期 hermeticity 检查;
-  既然解析责任已归用户,mcpp 就只报告不阻断 —— 他们可能用 `LD_LIBRARY_PATH` 跑,
-  或装在私有加载器确实会看的地方。
-
-mcpp 还会给它启动的每个进程声明 `XLINGS_SUBOS_LD_PATHS=0` —— 这是 xlings 链接器
-包装器路径注入的退出声明(openxlings/xlings#540):mcpp 要它的
-`--disable-new-dtags`,但必须拒绝它的 `-rpath "$XLINGS_SUBOS_LIB"`,因为那个变量
-指的是**当前 shell 的** subos,而 mcpp 有自己的 xlings home
-(`<mcpp home>/registry`),两者通常指向由**不同物理 glibc 载荷**支撑的不同 farm。
-mcpp 发的是自己从已选 binding 推导出来的那一条。
-
-出于同样的原因,mcpp 自己对 xlings 的调用不带 `XLINGS_ACTIVE_SUBOS`
-(2026.9.14.3+)。执行过 `xlings subos use <name>` 的 shell 会导出它,xlings 把它排在
-home 自身的 `activeSubos` 之前;被继承时,registry 会把 mcpp 的工具和工程的载荷装进
-同名的 subos,而 mcpp 读取的是 `subos/default`。
-
-## 3. 链接模型(`modules/toolchain-model/src/linkmodel.cppm`)
-
-`ToolchainLinkModel` 只回答一个问题——*如何对该工具链的 C 库编译与链接*——
-全部消费方从它派生 flags:
+| `payload` | `<store>/xim-x-glibc/2.39/lib64` | 否 —— 安装时写入一次 | 否 |
+| `package` | 依赖的 `[runtime]` 目录 | 否 | 否 |
+| `subos_farm` | `<subos>/lib` | **是** —— 每次 `xlings install` 都会重写 | 否 |
+| `host_default` | `/usr/lib/x86_64-linux-gnu` | 不适用 —— 属于目标机自身 | 不适用 |
+
+**次序按可变性递减排列，farm 排在最后。** 这就是全部的不变式：
+payload-first 让 `libc` / `libm` / `libstdc++` 始终从被 pin 住的 payload
+解析，只把没人提供的部分留给 farm 补齐。若 farm 排在前面，之后的一次
+`xlings install` 就能悄悄换掉一个**已经链接完成**的产物所加载的 libc。
+
+有两道护栏决定 farm 是否适用。格式必须拥有搜索路径（ELF 如此；Mach-O 与
+PE 什么都不获得，这与 loader 标签的约定一致），而且目标必须是本宿主的
+运行时 —— 交叉目标不会获得 farm，因为 farm 属于宿主 SubOS。
+
+`host_default` 只在产物确实会跑在宿主加载器之下时才进入模型。hermetic
+产物的 `PT_INTERP` 指名一个内建默认路径不同的私有加载器，把 `/usr/lib`
+算进去，就是在为错误的加载器建模 —— 而开发机通常自带一份 `libGL.so.1`，
+于是这样做会把「已解析」报给一个最终以 127 退出的二进制。
+
+闭包被记录在 `resolution.json` 的 `runtime.search.closure` 下，并由
+`mcpp why runtime` 打印。一个在 hermetic 产物的路径上找不到任何满足者的
+`DT_NEEDED`，是一次**已证明**的失败（`unresolvable`），而不是「没查
+清楚」，它会让构建失败。用 `LD_DEBUG=libs` 实测：私有加载器的内建默认
+路径是 glibc payload 自己的**构建期**前缀，这个目录在本机并不存在 ——
+`/usr/lib` 从不会被查询。
+
+有三点收窄了这一「证明」的范围，而每一点都是 mcpp 实际知道的比措辞暗示
+的要少：
+
+- **由产物的格式决定，而不是由 binding 决定。** 一次交叉构建使用的是本
+  宿主的 binding，产出的却是 PE 或 Mach-O。无论 binding 怎么说，ELF 规则
+  都不适用于这个产物。
+- **只有找不到的 SONAME 才能证明什么。**「这个对象我读不了」与「我在
+  512 个之后停下了」都是关于**检查本身**的陈述；一次没能看清楚的检查
+  什么都没证明，因此这些情形仍报告为 inconclusive。
+- **`[build] allow_host_libs` 会同时退出两个阶段。** 它本就关掉了链接期
+  的 hermeticity 检查；既然解析的责任已经转交给用户，mcpp 就只报告而不
+  阻断 —— 因为他们可能在 `LD_LIBRARY_PATH` 下运行，或者所在的机器上，
+  那个库恰好就在私有加载器会去查找的位置。
+
+mcpp 还会为它启动的每一个进程声明 `XLINGS_SUBOS_LD_PATHS=0`。这是对
+xlings 链接器包装器路径注入（openxlings/xlings#540）的退出声明：mcpp
+想要包装器的 `--disable-new-dtags`，但必须拒绝它的
+`-rpath "$XLINGS_SUBOS_LIB"`，因为那个变量指名的是**当前 shell** 的
+SubOS —— 而 mcpp 把自己的 xlings home 放在 `<mcpp home>/registry` 之下，
+两者通常指向由不同的物理 glibc payload 支撑的不同 farm。mcpp 发出的是它
+从自己实际选中的 binding 推导出的那一条 farm 记录。
+
+出于同样的原因，mcpp 自身对 xlings 的调用不携带 `XLINGS_ACTIVE_SUBOS`
+（2026.9.14.3 起）。执行过 `xlings subos use <name>` 的 shell 会导出这个
+变量，xlings 把它排在 home 自身的 `activeSubos` 之上；一旦被继承，就会让
+registry 把 mcpp 的工具与工程的 payload 都装进那个同名的 SubOS，而 mcpp
+读取的却是 `subos/default`。
+
+## 3. 链接模型（`modules/toolchain-model/src/linkmodel.cppm`）
+
+`ToolchainLinkModel` 只回答一个问题 —— *mcpp 如何针对这条工具链的 C 库
+编译与链接* —— 每一个消费方都从它派生出自己的 flag：
 
 ```
-CLibMode::PayloadFirst   找到 glibc/linux-headers xpkg(bundled LLVM 与
-                         无可用 sysroot 的 GCC 的常态)
-                           编译:-isystem(clang)/ -idirafter(gcc)payload 头
-                           链接:-B <glibcLib>   ← CRT 发现(Scrt1.o/crti.o/crtn.o;
-                                                    driver 从不查 -L 找它们)
-                                 -L <glibcLib> [clang 另加 -rpath 与 --dynamic-linker]
-CLibMode::Sysroot        可用的 --sysroot(GCC include-fixed 世界、自包含 musl
-                         sysroot、macOS SDK)
-CLibMode::None           无可用来源——落宿主默认;除非显式允许宿主库,否则由
-                         hermetic 校验(§6)拒绝该泄漏
+CLibMode::PayloadFirst   glibc/linux-headers xpkgs found (the normal bundled-LLVM
+                         and no-usable-sysroot GCC case)
+                           compile: -isystem (clang) / -idirafter (gcc) payload headers
+                           link:    -B <glibcLib>   ← CRT discovery (Scrt1.o/crti.o/crtn.o;
+                                                       the driver never consults -L for these)
+                                    -L <glibcLib> [+ -rpath + --dynamic-linker for clang]
+CLibMode::Sysroot        a usable --sysroot (GCC include-fixed world, self-contained
+                         musl sysroots, the macOS SDK)
+                           link:    --sysroot, plus --dynamic-linker and -L/-rpath
+                                    for the payload when one is known — the
+                                    sysroot says where headers live, not which
+                                    loader runs the result
+CLibMode::None           nothing usable — host defaults apply; the hermetic
+                         check (§6) rejects that leakage unless an explicit
+                         host-library exception is in effect
 ```
 
-`ClangDriverModel` 服务 bundled LLVM:mcpp 构建永远传 `--no-default-config`
-(绕过装机生成的 cfg 以保证可复现),并显式补上 libc++ 头/库与
+`ClangDriverModel` 是 bundled LLVM 的配套模型：mcpp 始终传入
+`--no-default-config`（绕开装机时生成的 cfg 以保证可复现），并显式重新
+提供 libc++ 头文件 / 库，以及
 `-fuse-ld=lld --rtlib=compiler-rt --unwindlib=libunwind`。
 
-**loader 解析**是数据驱动、无硬编码:先查按架构的 triple 映射表
-(x86_64 / aarch64 / riscv64 / loongarch64 / i686,glibc 与 musl 两种拼写),
-再对 payload 做 `ld-*.so*` glob 兜底(覆盖映射表未收录的架构)。曾实现过第三个
-来源——由安装器持久化的声明式元数据(`.xpkg-exports.json`)——经评估后**移除**:
-其唯一读者就是本解析器,而上述两级已覆盖全部真实 payload(0.0.83 的完整验证
-矩阵在该文件从未存在的情况下全绿),通用包管理器不应承载只有单一下游工具在读的
-机制。若将来出现"安装态元数据库"的真实需求,应以 xlings 自身为第一消费者来
-设计,届时 mcpp 再加回读取端即可。
+**loader 的解析**是数据驱动的，从不硬编码：先查一张按架构分列的 triple
+映射表（x86_64 / aarch64 / riscv64 / loongarch64 / i686，glibc 与 musl
+两种拼法），再对映射表未收录的架构，用 payload 上的 `ld-*.so*` glob 作为
+回退。曾经实现过第三种来源 —— 由安装器持久化的声明式元数据
+（`.xpkg-exports.json`）—— 评估之后**被移除**：它唯一的消费者本会是这个
+解析器，而上面两级来源已经覆盖了每一个真实 payload（整套 0.0.83 验证
+矩阵在这个文件从未存在的情况下全部通过），而一个通用包管理器不应该承载
+一套唯一读者只是某个下游工具的机制。如果将来真的出现「已安装状态元数据
+库」的需求，它必须以 xlings 自身作为第一消费者来设计，届时 mcpp 可以再
+加回一个读取端。
 
-## 4. 统一 post-install fixup 管线(`src/toolchain/post_install.cppm`)
+## 4. 统一的 post-install fixup 管线（`src/toolchain/post_install.cppm`）
 
-沙箱 payload 是预编译 ELF 树,其烙入的 `PT_INTERP`/`RUNPATH` 在打包期不可能预知,
-必须对齐到**本机沙箱**。
-`ensure_post_install_fixup(cfg, payloadRoot, pkg)` 是这次对齐的**唯一入口**,
-由三条入口路径(显式 install、默认 auto-install、manifest auto-install)共同
-调用。
+沙箱 payload 是预先构建好的 ELF 树，其中烙入的 `PT_INTERP`/`RUNPATH` 在
+打包期无从得知，必须对齐到**本机**沙箱。
+`ensure_post_install_fixup(cfg, payloadRoot, pkg)` 是完成这次对齐的
+**唯一入口**，由三条入口路径共同调用：显式 install、默认 auto-install、
+manifest auto-install。
 
-> 本管线曾同时重写 GCC 的 `specs` 文件,以便产物拿到 loader 和 rpath。现已不再
-> 这样做,原因见 §5。
+> 这条管线过去也会重写 GCC 的 `specs` 文件，以便产物获得 loader 与
+> rpath。现在不再这样做，原因见 §5。
 
-> 历史注记:0.0.83 之前各路径各自记得——或忘记——自己那份 fixup。manifest
-> 路径什么都不跑:刚 auto-install 的 llvm 因此保留着陈旧、随装机环境漂移的
-> cfg(issue #195);gcc 也曾因此产出找不到 `stdlib.h` 的沙箱。"用哪条命令装的"
-> 绝不能决定"工具链好不好用"。
+> 历史注记：0.0.83 之前，各条路径各自记得 —— 或者忘记 —— 自己那一部分。
+> manifest 路径**什么都不跑**，这正是一个刚刚自动安装的 llvm 会保留一份
+> 陈旧、随装机环境漂移的 cfg 的原因（issue #195），也是 gcc 曾经产出一个
+> 找不到 `stdlib.h` 的沙箱的原因。「用哪条命令装的」绝不能决定「这条工具
+> 链好不好用」。
 
-**触发语义——每次都问,只做一次:**
+**触发语义 —— 每次构建都询问，只执行一次：**
 
 ```
-每次构建 → ensure() → 读 <payload>/.mcpp-fixup.json
-                       marker == {schema, kind, rev, glibcLib}?  → return(毫秒级)
-                       失配 → 执行该 kind 的 fixup,写 marker
+every build → ensure() → read <payload>/.mcpp-fixup.json
+                          marker == {schema, kind, rev, glibcLib}?  → return   (ms-level)
+                          mismatch → run the fixup for this kind, write marker
 ```
 
-marker 是**内容指纹化的缓存**,不是事件标志:它编码了 fixup 代码版本与所对齐的
-glibc payload。"做"分支因此在每个 `(payload × fixup-rev × glibc 指纹)` 组合上
-恰好执行一次——首次使用,外加两类确需重写的重新收敛事件(`kFixupRev` 升级、
-glibc payload 被更换)。之所以每次构建都问:让 payload 失效的事件(xlings 换
-glibc、payload 从别的 home 继承而来)发生在 mcpp 视野之外,trust-but-verify
-是唯一可靠语义。
+marker 是一份**内容指纹化的缓存**，不是事件标志：它编码了 fixup 的版本，
+以及它对齐时所针对的那个 glibc payload。因此「执行」这一分支在每一个
+`(payload × fixup-rev × glibc 指纹)` 组合上恰好触发一次 —— 首次使用，外加
+两类确实需要重写的重新收敛事件（经 `kFixupRev` 升级的 fixup 逻辑，或者
+底层的 glibc payload 发生变化）。mcpp 之所以每次构建都要问一遍，是因为
+使 payload 失效的那些事件（xlings 换掉 glibc、payload 从另一个 home 继承
+而来）发生在 mcpp 的视野之外 —— trust-but-verify 是唯一可靠的语义。
 
-**分 kind 的动作:**
+**按 kind 划分的动作：**
 
-| kind | 动作 |
+| kind | actions |
 |---|---|
-| `gcc`(glibc)| 对 gcc payload **及共享的 binutils payload** 做 patchelf 遍历(PT_INTERP → 沙箱 loader,RUNPATH → glibc+gcc lib)——目的是让 *gcc 自己* 能跑起来。不往 `specs` 里写任何东西 |
-| `llvm` | 只遍历 `lib/`(运行库 `.so` 的 RUNPATH;`bin/` 不碰,保留 xlings 设置的 RUNPATH);确定性再生 cfg(§5)|
-| `musl-gcc` | 无——自包含 sysroot,静态世界 |
-
-**安全不变量**(每条都由真实事故换来):
-
-- **绝不就地写。** patchelf 作用于副本,再原子 `rename()` 换入:payload 里可能
-  有**当前进程**(自托管、动态链接的 mcpp)或并发构建正 mmap 着的库,就地重写
-  活映射的 backing file 会损坏运行中的进程(实测:退出时 `_dl_fini` 段错误)。
-  `rename` 让新内容拿新 inode,活进程保有旧 inode。
-- **所有权护栏。** 解析到本 home registry 之外的 payload(从别的 `MCPP_HOME`
-  symlink 继承)一律不碰——属主已收敛过,隔着 symlink 改写会毁掉属主的工具链。
-- 把内容感知扩展到 patchelf 遍历
-  (写前比对 `--print-interpreter`/`--print-rpath`,已对齐的 payload **零写入**
-  收敛)是已知的后续项。
-- 长期方向:全部写入由**安装器**(xlings)持有——装机时、以及 payload 进入
-  新 home 时——mcpp 退为只读 + 校验。本管线在那之前是兼容层,也是双向漂移的
-  自愈机制。
-
-## 5. 编译器是能力,不是配置
-
-一个 payload 交付两样可分离的东西:编译的**能力**,以及关于如何链接的**主张**。
-mcpp 要前者,后者自己给——链接行才是构建决策该待的地方,因为它是逐次构建而变的
-那一个。现在两个编译器都遵循这条规则,只是机制不同。
-
-**clang** —— mcpp 每次调用都带 `--no-default-config`。
-
-**gcc** —— 用生成的文件走 `-specs=`。`<compiler> -dumpspecs` 打印的是**内建**
-specs(不受磁盘上任何文件影响);mcpp 从中取出 `*link:` 的正文,删掉其中的 loader
-与 rpath 行,把结果写进构建目录。不带前导 `+` 的 `-specs=` 文件是**替换**它所命名的
-规则,于是 payload 自己的主张被覆盖,而 payload 本身分毫未动。两条推论值得写明:
-它是逐构建的,所以同机器上的另一个项目不受影响;它不需要对工具链的写权限,所以
-继承来的、或只读的 payload 都能用。
-
-删掉 gcc 烙入的 `*link:`,也就删掉了它提供的东西。因此 mcpp 在链接行上显式补齐
-`--dynamic-linker` 与每一条 rpath——loader、glibc lib 目录、以及 gcc 自己的
-`lib64`(libgcc_s)。这三条都是把 specs 拿掉后、看什么先坏掉而逐一找出来的。
-
-为什么不继续重写 `specs`?因为那个文件是共享的,而值是逐构建的。旧的重写用的是
-单路径的 needle 配双路径的 replacement,于是每个跑过它的 home 都会漏下一条:一台
-开发机产出的**每一个** gcc 产物里都带着 **68** 条陈旧 `RUNPATH`,全部指向已被删除的
-`mktemp` 目录。没有任何东西发现它们,因为一条死 RUNPATH 只多花一点搜索时间。e2e
-`201_gcc_no_specs_pollution.sh` 断言的是**产物**而不是 specs 文件——用户最终交付的
-是产物。
-
-### 5.1 clang cfg
-
-`bin/clang++.cfg` 的职责是:直接调用打包内 `clang++`(不经由 mcpp)时,
-获得可用且 hermetic 的编译器配置。
-fixup 管线从链接模型**确定性再生**它——同一 payload ⇒ 任何机器、任何安装路径
-产出字节一致的 cfg——而不是对装机产物做行级补丁。Linux 上内容为:CRT 发现
-(`-B`)、payload loader + rpath、lld/compiler-rt/libunwind、C++ 驱动附加
-bundled libc++;macOS 保持历史形态(`--sysroot=<SDK>` + payload libc++ 头,
-C++ 运行时的链接交由主构建的平台专属处理)。
-
-## 6. hermetic 链接校验(`src/build/hermetic.cppm`)
-
-在 Linux 上用沙箱工具链构建前,mcpp 以真实链接 flags 干跑 driver
-(`-### -x c++ /dev/null`),断言每个 CRT 对象与**生效的**动态链接器(取最后
-一次出现)都解析在允许的沙箱前缀之下。这把两种静默故障变成一个可行动的诊断:
-裸 CRT 名传给 lld(干净机器上的 #195 症状)与静默的宿主 CRT 污染(它曾让有
-宿主工具链机器上的绿色 CI 成为假信号)。判定按 flag 集缓存
-(`.mcpp-hermetic-ok`);逃生阀:`[build] allow_host_libs = true` 或
-`MCPP_ALLOW_HOST_LIBS=1`。系统/PATH 编译器豁免——显式选择宿主世界是用户的
-权利。
-
-CI 用一个**完全没有宿主工具链**的 job(`debian:stable-slim`,无 gcc、无宿主
-`Scrt1.o`)守住这一切——那是唯一能忠实复现干净机器故障模式的环境类;另有 e2e
-`86_llvm_hermetic_link.sh` 在任何机器上复核 `-###` 的解析结果。
-
-### 6.1 链接后的 Linux 运行时物理校验(`elf_runtime.cppm`)
-
-hermetic 校验回答的是链接前问题:driver 看起来会解析到什么。运行时物理校验回答更强的
-链接后问题:新 ELF 真正记录了什么,其闭包实际会加载什么。
-`[build] allow_host_libs = true` 会有意放宽前者,但不会屏蔽后者已经可证明的物理矛盾。
-
-对每个新链接的 Linux executable/shared object,mcpp 在进程内解析 ELF64 little-endian
-program/dynamic/GNU version 表;构建路径不启动 `readelf`、`patchelf` 或 `ldd`。读取内容包括
-`PT_INTERP`、`DT_RPATH`/`DT_RUNPATH`、`DT_NEEDED` 以及所需/导出的 `GLIBC_*` 版本。
-随后按产物搜索路径、所选 runtime/toolchain 目录和已知宿主库目录解析闭包,并执行:
-
-- **规则 B(同源):** `PT_INTERP` 和闭包中每个 `libc.so.6` 必须都来自
-  `RuntimeBinding` 选定的规范 payload。宿主 loader + 私有 libc,或两个私有 libc payload,
-  都是可证明的 pre-main 故障。
-- **规则 A(版本 floor):** 闭包请求的每个 `GLIBC_x.y` 都不得高于所选 libc 的 GNU
-  version definitions。满足条件时链接宿主 DSO 完全允许;mcpp 校验的是物理事实,不是
-  强加“禁止宿主库”策略。
-
-判定是类型化的:`Pass`、`ProvenMismatch`、`Inconclusive`。可证明的 A/B 冲突会 hard fail,
-诊断给出规范化 requester/provider/artifact 路径与可复制的 SubOS 修复步骤。无法取得
-loader cache/硬件闭包时明确报告 inconclusive,绝不伪装成绿色。macOS/Windows 复用同一
-类型接口但为 no-op,不会套用 ELF/glibc 规则。
-
-verdict 以 `.mcpp-runtime-verdicts.json` 存在 `build.ninja` 旁,键包含产物 stat 指纹与
-完整 runtime contract hash。热 no-op 必须已有当前 `pass` 记录,比较 Ninja 前后产物 stat,
-并执行零次 ELF 解析;若 Ninja 意外重链则先退回完整路径重新校验,之后才允许成功/运行。
-`mcpp self doctor` 复用同一存档 verdict,不会拿已经变化的当前宿主重新猜一次。
-
-装后 fixup 同样按精确身份收敛:`glibc@2.44` 只解析
-`<xpkgs>/xim-x-glibc/2.44/{lib64,lib}`。精确 payload 缺失/陈旧就是错误,其他已安装版本
-永远不是回退项。
-
-精确 payload 由 mcpp 在第一次需要它的 fixup 之前安装(`ensure_declared_runtime`,
-mcpp#660)。这一步只在 binding 找不到 payload、宿主为 Linux、提供者为 `glibc`,且工具链的
-fixup 需要 C 运行时(`gcc` 与 `llvm` payload)时执行;因此使用系统、musl 或 PE 工具链的构建
-不会下载任何东西。它通过 xlings 安装 `xim:glibc@<声明的版本>`,然后重新解析 binding。
-在这一步出现之前,payload 只有在 xlings 把它作为某个工具链的依赖安装时才存在;从 CI 缓存
-恢复的工具链不会重新安装,于是缓存中若是另一个 glibc 修订版,声明的 payload 就不存在。
-无法安装时(例如离线),fixup 的报错会写出需要预先提供的坐标 `xim:glibc@<版本>`。
-
-### 6.2 运行时搜索路径的允许位置(`runtime_env_contract.cppm`)
-
-告诉 loader「去哪找」有两条通道,差别不在便利性,而在**波及范围**:
-
-| | 波及到 | |
+| `gcc`（glibc） | 对 gcc payload **以及共享的 binutils payload** 做一次 patchelf 遍历（PT_INTERP → 沙箱 loader，RUNPATH → glibc + gcc 的 lib 目录）—— 目的是让 *gcc 自己* 能跑起来。不会往 `specs` 里写入任何东西 |
+| `llvm` | 只对 `lib/` 做 patchelf 遍历（运行期 `.so` 的 RUNPATH；`bin/` 不动，以保留 xlings 设置的 RUNPATH）；确定性地重新生成 cfg（见 §5） |
+| `musl-gcc` | 无操作 —— 自包含 sysroot，静态世界 |
+
+**安全不变量**（每一条都由一次真实事故换来）：
+
+- **绝不就地打补丁。** patchelf 作用于一份副本，随后原子地 `rename()`
+  换入：payload 中可能有库被**当前进程**（一个自托管、动态链接的 mcpp）
+  或某个并发构建 mmap 着，就地重写一个活映射的 backing file 会损坏正在
+  运行的进程（实测现象：退出时 `_dl_fini` 中的 SIGSEGV）。`rename` 让新
+  内容获得一个新 inode，活跃进程仍持有旧的那一个。
+- **所有权护栏。** 解析到本 home registry 之外的 payload（通过 symlink
+  从另一个 `MCPP_HOME` 继承而来）绝不会被打补丁 —— 它们的属主已经完成
+  过收敛，隔着 symlink 打补丁会毁掉属主自己的工具链。
+- 把内容感知能力扩展到 patchelf 遍历本身（写入前先比对
+  `--print-interpreter`/`--print-rpath`，使一个已经对齐的 payload 能以
+  **零写入**收敛）是一项已知的后续工作。
+- 长期方向是让**安装器**（xlings）拥有全部写入 —— 无论是在安装时，还是
+  在 payload 进入一个新 home 时 —— 让 mcpp 退化为只读加校验。在那之前，
+  这里的管线是兼容层，也是应对双向漂移的自愈机制。
+
+## 5. 编译器是一种能力，不是一份配置
+
+一个 payload 交付两样可分离的东西：编译的**能力**，以及关于如何链接的
+**主张**。mcpp 只要前者，后者自己提供 —— 链接行才是构建决策应该待的
+地方，因为它是随每次构建而变化的那部分。两个编译器现在都遵循这条规则，
+只是机制不同。
+
+**clang** —— mcpp 的每一次调用都带上 `--no-default-config`。
+
+**gcc** —— 用一份生成出来的文件走 `-specs=`。`<compiler> -dumpspecs`
+打印的是**内建**的 specs（不受磁盘上任何文件影响）；mcpp 从中取出
+`*link:` 的正文，删掉其中的 loader 与 rpath 行，把结果写入构建目录。一份
+不带前导 `+` 的 `-specs=` 文件会**替换**它所命名的那条规则，于是
+payload 自身的主张被覆盖，而 payload 本身不受触碰。这带来两条值得说明的
+推论：它是逐次构建的，因此同一机器上的另一个工程不受影响；它也不需要对
+工具链的写权限，因此继承来的、或只读的 payload 同样可用。
+
+删掉 gcc 烙入的 `*link:`，也就删掉了它原本提供的东西。因此 mcpp 在链接行
+上显式补上 `--dynamic-linker` 与每一条 rpath —— loader、glibc 的 lib
+目录，以及 gcc 自己的 `lib64`（libgcc_s）。这些都是把 specs 拿掉之后，
+逐一观察什么先坏掉而找出来的。
+
+为什么不继续重写 `specs`？因为这个文件是共享的，而它的值却是逐次构建才
+确定的。旧的重写方式用一条单路径的 needle 去做双路径的替换，于是每个跑
+过它的 home 都会留下一条残留：一台开发机产出的**每一个** gcc 产物里，
+都带着 **68** 条陈旧的 `RUNPATH`，全部指向已经被删除的 `mktemp` 目录。
+没有任何东西发现它们，因为一条失效的 RUNPATH 只多花一点搜索时间。e2e
+`201_gcc_no_specs_pollution.sh` 断言的是**产物**，而不是 specs 文件 ——
+用户最终交付的是产物。
+
+### 5.1 clang 的 cfg
+
+`bin/clang++.cfg` 的存在，是为了让直接调用打包内 `clang++`（不经由
+mcpp）的场景，也能得到一份可用、hermetic 的编译器配置。fixup 管线从
+链接模型**确定性地重新生成**它 —— 同一个 payload 在任何机器、任何安装
+路径上都产出字节相同的 cfg —— 而不是对某次安装产出的文件做行级修补。在
+Linux 上，它包含 CRT 发现（`-B`）、payload loader 加 rpath、
+lld/compiler-rt/libunwind，以及供 C++ 驱动使用的 bundled libc++；在
+macOS 上，它保留历史形态（`--sysroot=<SDK>` 加 payload 的 libc++ 头
+文件 —— C++ **运行时链接**仍由主构建中平台专属的
+`needs_explicit_libcxx` 处理）。
+
+## 6. hermetic 链接检查（`src/build/hermetic.cppm`）
+
+在 Linux 上用沙箱工具链开始构建之前，mcpp 会用真实的链接 flag 对 driver
+做一次干跑（`-### -x c++ /dev/null`），并断言每一个 CRT 对象，以及
+**生效的**动态链接器（以最后一次出现为准），都解析到允许的沙箱前缀之
+下。这把两种静默的故障模式变成了一条可以据以行动的诊断：lld 打不开的裸
+CRT 名字（干净机器上的 #195 症状），以及静默的宿主 CRT 污染（它曾让带有
+宿主工具链的机器上的绿色 CI 成为假信号）。判定结果按 flag 集合缓存
+（`.mcpp-hermetic-ok`）；逃生舱是 `[build] allow_host_libs = true` 或
+`MCPP_ALLOW_HOST_LIBS=1`。系统 / PATH 编译器豁免此项检查 —— 显式选择
+宿主世界是用户自己的决定。
+
+CI 用一个**完全没有宿主工具链**的 job（`debian:stable-slim`，没有 gcc，
+也没有宿主的 `Scrt1.o`）守住这一点 —— 它是唯一能忠实复现干净机器故障
+模式的环境类别，另外还有 e2e `86_llvm_hermetic_link.sh`，在任何机器上
+重新检查 `-###` 的解析结果。
+
+### 6.1 链接后的 Linux 运行时物理校验（`elf_runtime.cppm`）
+
+hermetic 检查回答的是一个链接前的问题：driver 看起来会解析到什么？运行
+时物理校验回答的是更强的链接后问题：新产出的 ELF 实际记录了什么，它的
+闭包将会加载什么？`[build] allow_host_libs = true` 有意放宽第一项检查，
+但不会压制第二项检查所证明的物理上的不可能。
+
+对每一个新链接的 Linux 可执行文件 / 共享对象，mcpp 在进程内部解析
+ELF64 小端序的 program/dynamic/GNU-version 表 —— 构建路径上不启动
+`readelf`、`patchelf` 或 `ldd` 子进程 —— 并记录 `PT_INTERP`、
+`DT_RPATH`/`DT_RUNPATH`、`DT_NEEDED`，以及所需 / 已定义的 `GLIBC_*`
+版本。它用产物的搜索路径、已选定的 runtime/toolchain 目录，以及已知的
+宿主库目录来解析声明的闭包，随后施加：
+
+- **规则 B（同源）：** `PT_INTERP` 与每一个被解析到的 `libc.so.6`，都
+  必须是 `RuntimeBinding` 选定的那份规范 payload。宿主 loader 配私有
+  libc，或者两份私有 libc payload，都是一次已证明的、在进入 `main` 之前
+  就会发生的故障。
+- **规则 A（版本下限）：** 闭包中对 `GLIBC_x.y` 的每一次请求，都不得新于
+  所选 libc 导出的 GNU version definitions。满足这一条时，链接一个宿主
+  DSO 是允许的；mcpp 校验的是物理事实，不是在强加一条「禁止宿主库」的
+  策略。
+
+判定结果是类型化的：`Pass`、`ProvenMismatch` 或 `Inconclusive`。已证明
+的 A/B 不匹配会使构建失败，并给出规范化的 requester/provider/artifact
+路径，以及一份可以直接复制执行的 SubOS 修复步骤。缺失 loader-cache 或
+硬件闭包数据时，会被报告为 inconclusive，绝不会被重新标记成绿色。macOS
+与 Windows 复用同一接口，但作为一个类型化的空操作，永远不会套用
+ELF/glibc 规则。
+
+判定结果以 `.mcpp-runtime-verdicts.json` 的形式存放在 `build.ninja`
+旁，键由产物的 stat 指纹加上完整的 runtime contract hash 组成。热的空
+操作构建要求已经存在一条当前的通过记录，比较 Ninja 前后的产物 stat，并
+执行零次 ELF 解析。一次意外的重新链接会先回落到完整路径，才允许成功或
+执行。`mcpp self doctor` 报告的是同一份存档判定，而不是针对可能已经
+变化的当前宿主重新探测一次。
+
+装后对齐遵循同一条身份规则：`glibc@2.44` 只解析
+`<xpkgs>/xim-x-glibc/2.44/{lib64,lib}`。精确 payload 缺失或陈旧是一个
+错误；另一个已安装的版本绝不会被当作回退。
+
+精确的 payload 由 mcpp 在第一次需要针对它打补丁的 fixup 之前安装
+（`ensure_declared_runtime`，mcpp#660）。这一步只在以下条件同时成立时
+执行：binding 找不到 payload、宿主是 Linux、provider 是 `glibc`，且该
+工具链的 fixup 需要消费一份 C 运行时（`gcc` 与 `llvm` 的 payload）——
+因此使用系统、musl 或 PE 工具链的构建不会下载任何东西。它通过 xlings
+安装 `xim:glibc@<声明的版本>`，然后重新解析 binding。在这一步存在之
+前，payload 只有在 xlings 把它当作某个工具链的依赖装上时才会出现；从
+CI 缓存恢复的工具链不会被重新安装，因此当缓存中是另一个 glibc 修订版
+时，声明的 payload 就会缺席。当安装不可能完成时（例如处于离线状态），
+fixup 的报错会写出需要预先提供的坐标 `xim:glibc@<版本>`。
+
+### 6.2 运行时搜索路径的允许位置（`runtime_env_contract.cppm`）
+
+告诉加载器该去哪里查找有两种方式，二者的区别不在于是否方便，而在于
+**波及范围**：
+
+| | 波及范围 | |
 | --- | --- | --- |
-| `DT_RUNPATH` | 携带它的那**一个**对象,及其 `dlopen()` | 逐二进制 |
-| `LD_LIBRARY_PATH` | 本进程**以及它派生的每一个进程** | 继承,且一直传下去 |
-
-第二行就是私有 libc 目录必须是 **binary 作用域**的原因。glibc 的 `libc.so.6` 与它的
-`ld.so` 通过 `GLIBC_PRIVATE` 版本锁死:2.44 的 libc 里 `__pointer_chk_guard` 是未定义
-引用,只有 2.44 自己的 loader 导出它。mcpp 构建出来的程序没事——`PT_INTERP` 指向私有
-loader;`/bin/sh` 有事:它的 `PT_INTERP` 指向**宿主** loader,而且任何环境变量都改不了,
-于是 `popen()`/`system()` 的子进程在重定位阶段就死掉,连 `main` 都进不去,也没有任何
-输出(#401;#291 是同一形状往内一跳,杀掉的是 mcpp 自己的嵌套宿主工具)。
-
-所以 mcpp 不会把私有 libc 目录发布到环境里。也不需要:只要存在 payload,link model
-就已经在 `--dynamic-linker` 旁发了 `-Wl,-rpath,<glibc>`,恰好覆盖这个目录存在的唯一
-理由——某个 `dlopen()` 的 `DT_NEEDED` 闭包看不到可执行文件的 RUNPATH。
-
-这是**作用域**,不是条件判断。「只在依赖可能 dlopen 时才导出」仍然是导出,而死掉的
-子进程不关心原因。普通依赖运行时目录保留环境作用域:它们没有 loader 耦合,宿主二进制
-撞上去最多是困惑,不会死。
-
-## 7. 扩充指南
-
-### 7.1 新增一个工具链(新编译器家族或发行版)
-
-1. **索引侧**(xim-pkgindex):包含 payload 资产的包,以及——关键——对所需
-   C 库 payload 的 `deps` 声明(`xim:glibc`、`xim:linux-headers`)。遵循
-   llvm/gcc 的打包 SOP,包括准入 gate(`verify-toolchain.sh`):缺件检查 +
-   hermetic CRT 解析 + 真实编译/链接/运行,通过才可发资产。
-2. **注册表**(`src/toolchain/registry.cppm`):让
-   `parse_toolchain_spec`/`to_xim_package` 认识 spec 写法、xim 包名与
-   `frontendCandidates`(哪个二进制是 C++ 驱动)。
-3. **能力**(`src/toolchain/provider.cppm`):stdlib 身份、BMI 特性及
-   `flags.cppm` 消费的特性开关。
-4. **fixup kind**(`post_install.cppm`):确定该 payload 需要哪种装后对齐——
-   gcc 式(patchelf + specs)、llvm 式(lib patchelf + cfg)或无(自包含),
-   接入 `ensure_post_install_fixup` 的分发。
-5. **e2e**:一个 `86_llvm_hermetic_link.sh` 风格的 hermetic 链接测试,并纳入
-   无宿主工具链 CI job。
-
-### 7.2 新增一个 CPU 架构(Linux)
-
-机制已按架构参数化,剩下的是数据:
-
-1. 在 `linkmodel.cppm::loader_filename` 的映射表中加入该架构的 glibc/musl
-   loader 名(加之前 glob 兜底也能工作);
-2. 为该架构发布 payload 资产(glibc、linux-headers、工具链本体)——
-   aarch64-linux-musl 交叉目标是现成先例(`[target.aarch64-linux-musl]`,
-   经 spec 的 `targetTriple` 解析交叉前端);
-3. 其余什么都不用做:`-B`/`-L`/loader 的发射、fixup 管线、hermetic 校验全部
-   与名字无关。
+| `DT_RUNPATH` | 携带它的那一个对象，以及该对象的 `dlopen()` | 逐二进制 |
+| `LD_LIBRARY_PATH` | 该进程，**及其派生的每一个进程** | 被继承，且永久继承 |
+
+第二行正是私有 libc payload 必须是**二进制作用域**的原因。一份 glibc 的
+`libc.so.6` 与它的 `ld.so` 通过 `GLIBC_PRIVATE` 版本锁定在一起：2.44 的
+libc 携带一个未定义的 `__pointer_chk_guard`，只有 2.44 自己的 loader 才
+导出它。mcpp 构建出的程序没有问题 —— 它的 `PT_INTERP` 指名的正是这个
+私有 loader。`/bin/sh` 则不然：它的 `PT_INTERP` 指名的是**宿主**的
+loader，任何环境变量都无法覆盖它，因此一个 `popen()`/`system()` 的子
+进程会在重定位期间、还没进入 `main` 之前就死掉，且没有任何输出
+（mcpp#401；mcpp#291 是形状相同的问题往内靠近了一跳，杀掉的是 mcpp
+自己嵌套的宿主工具）。
+
+因此 mcpp 从不通过环境变量发布私有 libc 目录。它也不需要这样做：只要
+存在一份 payload，链接模型就已经在 `--dynamic-linker` 旁边发出了
+`-Wl,-rpath,<glibc>`，这已经覆盖了这个目录存在的唯一理由 —— 某个
+`dlopen()` 自身的 `DT_NEEDED` 闭包不会去查阅可执行文件的 RUNPATH。
+
+这是一个**作用域**问题，不是条件判断。「只在某个依赖可能 `dlopen()`
+时才导出它」仍然是导出，而那个死掉的子进程并不在乎原因。普通依赖的
+运行时目录保持自己的环境作用域：它们与 loader 没有耦合，因此一个偶然
+撞上它们的宿主二进制，最坏也只是感到困惑。
+
+## 7. 扩展这套机制
+
+### 7.1 新增一个工具链（新的编译器家族或发行版）
+
+1. **索引侧**（xim-pkgindex）：一个携带 payload 资产的包，并且 —— 这一
+   点至关重要 —— 声明对它所需的 C 库 payload 的 `deps`（`xim:glibc`、
+   `xim:linux-headers`）。遵循 llvm/gcc 的打包 SOP，包括准入 gate
+   （`verify-toolchain.sh`）：完整性 + hermetic CRT 解析 + 一次真实的
+   编译/链接/运行，通过之后资产才能发布。
+2. **词汇表 + 注册表**：先把目标行加入 `triple.cppm` 的
+   `kKnownTargets`（档位/pin/defaultStatic），再让 `to_xim_package`
+   （`src/toolchain/registry.cppm`）认识 *(family, target, host)* 到
+   xim 包行的映射，以及它的 `frontendCandidates`（哪个二进制是 C++
+   驱动）。若有旧拼法，一律只放进 `compat.cppm`。
+3. **能力**（`src/toolchain/provider.cppm`）：stdlib 身份、BMI 特性，
+   以及 `flags.cppm` 消费的 feature 开关。
+4. **fixup kind**（`post_install.cppm`）：确定这个 payload 需要哪种
+   装后对齐 —— gcc 式（patchelf + specs）、llvm 式（lib patchelf +
+   cfg），或者不需要（自包含）。把它接入 `ensure_post_install_fixup`
+   的分发逻辑。
+5. **e2e**：按 `86_llvm_hermetic_link.sh` 的思路写一个 hermetic 链接
+   测试，并纳入无宿主工具链的 CI job。
+
+### 7.2 新增一个 CPU 架构（Linux）
+
+这套机制已经按架构参数化；剩下的工作只是数据：
+
+1. 把该架构的 glibc/musl loader 名字加进
+   `linkmodel.cppm::loader_filename` 的 triple 映射表（在此之前，glob
+   回退一直有效）；
+2. 为该架构发布 payload 资产（glibc、linux-headers、工具链本体）——
+   aarch64-linux-musl 交叉目标是现成的先例（`[target.aarch64-linux-musl]`，
+   交叉前端经由 spec 的 `targetTriple` 解析）；
+3. 其余什么都不用做：`-B`/`-L`/loader 的发出、fixup 管线，以及
+   hermetic 检查全都与具体名字无关。
 
 ### 7.3 嵌入式与裸机工具链
 
-`riscv64-none-elf` 与 `riscv32-none-elf` 已实现,面向用户的说明见
-[40 — 裸机与 freestanding 目标](40-baremetal.md)。本节记录由此得到的形态与
-上文 hosted 模型之间的关系。
-
-本节早先的三条预测成立:
-
-- **无动态链接器。** `loader` 保持为空,这一点每个渲染器本来就允许;部署路径是
-  烧录而不是 ELF interp。
-- **目标侧不需要 fixup。** 宿主运行的编译器二进制仍需要 PT_INTERP/RUNPATH 对齐,
-  与今天的 gcc kind 完全相同。
-- **MCU flags、链接脚本处理与运行路径确实需要新设计。** 三者都已落地,且如预测
-  那样位于本文档之上的层次:ISA 参数来自 `src/freestanding/target.cppm` 中每个
-  目标一行的表,链接脚本经 `link-script` 构建指令到达,执行方式经 `runner` 到达。
-
-有一条预测是错的,而这条更正正是整个设计的承重部分。C 库**不在**工具链载荷内,
-因此这并不是换了一个 sysroot 的 `CLibMode::Sysroot`。picolibc 是一份独立载荷,
-由目标自己的表行指名(`modules/toolchain-model/src/triple.cppm` 中的
-`sysroot = xim:picolibc-riscv@1.8.12`),与该行的编译器 `pin` 处于同一地位。
-从目标而非从工具链解析它,正是裸机**包**不必指名一份 libc 的原因,如同 hosted
-包从不指名 glibc。
-
-freestanding 链接行同样是被**替换**而不是被追加 —— 见
-`src/freestanding/linkline.cppm` —— 因为在那里每一条 hosted 链接 flag 都是错的,
-而不只是多余的。管线更早处追加到普通 ldflags 上的内容会被丢弃,这也是目标 sysroot
-的 `-L` 发在该行上而不是与通用 flag 一起发出的原因。
+`riscv64-none-elf` 与 `riscv32-none-elf` 已经实现，面向用户的说明见
+[40 —— 裸机与 freestanding 目标](40-baremetal.md)。本节记录由此得到的
+形态，与上文 hosted 模型之间的关系。
+
+本节早先做出的三条预测都成立：
+
+- **没有动态链接器。** `loader` 保持为空，每个渲染器本来就允许这一点；
+  部署方式是烧录，而不是 ELF interp。
+- **目标侧不需要 fixup。** 宿主上运行的编译器二进制仍然需要
+  PT_INTERP/RUNPATH 对齐，与今天的 gcc kind 完全相同。
+- **MCU flag、linker script 处理与运行方式确实需要全新设计。** 三者均
+  已落地，而且都如预测那样位于本文档所述层次之上：ISA flag 来自
+  `src/freestanding/target.cppm` 中每个目标一行的表，linker script 经
+  `link-script` 构建指令到达，执行方式经 `runner` 到达。
+
+有一条预测是错的，而这次纠正正是整个设计中承重的那一部分。C 库**不**
+存在于工具链 payload 之内，因此这并不是换了一个 sysroot 的
+`CLibMode::Sysroot`。picolibc 是一份独立的 payload，由目标自己的表行
+指名（`modules/toolchain-model/src/triple.cppm` 中的
+`sysroot = xim:picolibc-riscv@1.8.12`），与该行的编译器 `pin` 处于
+同一地位。从目标而不是从工具链解析它，正是裸机**包**不必指名一份
+libc 的原因，如同 hosted 包从不指名 glibc。
+
+freestanding 的链接行同样是被**替换**而不是被扩展 —— 见
+`src/freestanding/linkline.cppm` —— 因为在那里，每一条 hosted 链接
+flag 都是错的，而不只是多余的。管线更早处追加到普通 ldflags 上的任何
+内容都会被丢弃，这也是目标 sysroot 的 `-L` 在这一行单独发出、而不与
+通用 flag 一起发出的原因。
 
 ### 7.4 非 ELF 平台
 
-macOS(Mach-O)与 Windows(PE)有意绕开本文大部分内容:macOS 从 SDK 解析
-C 世界(`CLibMode::Sysroot`)并有自己的 libc++ 链接处理;Windows 没有 rpath——
-mcpp 把运行时 DLL 部署到产物 exe 旁,这正是该平台对 §3–§4 所做一切的原生
-等价物。
+macOS（Mach-O）与 Windows（PE）有意绕开本文档的大部分内容：macOS 从
+SDK 解析它的 C 世界（`CLibMode::Sysroot`），并有自己的 libc++ 链接
+处理方式；Windows 没有 rpath —— mcpp 把运行时 DLL 部署到产出的 exe
+旁边，这正是该平台上，与 §3–§4 对 ELF 所做的一切等价的原生方式。
 
-**工程自己产出的共享库**(`kind = "shared"`)确实按格式而不同,而这个差别不是
-flag 的拼法 —— 它是产物记录下的关于它自己的东西:
+**工程自己产出的共享库**（`kind = "shared"`）确实按格式而有所不同，
+而这个差别不在于 flag 的拼法 —— 而在于产物记录了关于自己的什么：
 
-| 格式 | 生产方的产出 | 消费方链接的对象 |
+| 格式 | 生产方的产出 | 消费方链接时的输入 |
 |---|---|---|
-| ELF | 声明了 soname 时发 `-Wl,-soname,<n>` | `-L` + `-l`、`-Wl,-rpath,$ORIGIN` |
-| Mach-O | **总是**发 `-Wl,-install_name,@rpath/<file>` | `-L` + `-l`、`-Wl,-rpath,@loader_path` |
-| PE / MinGW | `-Wl,--out-implib,<lib>` | **导入库**,且 `-Wl,-Bdynamic` 在前 |
-| PE / MSVC | 拒绝(不做自动导出;见 docs/12) | —— |
-
-其中三行是新增的:在此之前,除 ELF 之外一律被拒绝,原生与交叉都是。要让它们
-可用而不只是被允许,有两处细节必须改。Mach-O 的 install name 默认取该库被**链接**
-时的路径,因此「仅在声明了 `soname` 时才发出」会让其余每个 `.dylib` 都记下一个构建
-目录 —— 在构建它的那台机器上没问题,换任何一台就是 `image not found`。而这个选择
-原先由宿主上的 `#if defined(__APPLE__)` 做出,那只在原生 macOS 构建上碰巧正确,
-对任何交叉链接都是错的;它现在由目标决定,正如 `target_output` 早已如此。
-
-**服务不了的目标会被拒绝**,而不是悄悄按宿主构建:Linux 上的
-`--target x86_64-windows-msvc` 从前会解析到原生 `g++`、写进
-`target/x86_64-linux-gnu/` 并报告成功。词汇表的档位说的是「mcpp 支持这个目标」;
-`host_can_serve`(`registry.cppm`)回答的是另一个问题「这台机器能不能产出它」,
-而 `prepare.cppm` 现在会问它 —— 显式的 `[target.X] toolchain = "…"` 是作者自备
-交叉工具链时的出口。
+| ELF | 声明了 soname 时发出 `-Wl,-soname,<n>` | `-L` + `-l`、`-Wl,-rpath,$ORIGIN` |
+| Mach-O | **始终**发出 `-Wl,-install_name,@rpath/<file>` | `-L` + `-l`、`-Wl,-rpath,@loader_path` |
+| PE / MinGW | `-Wl,--out-implib,<lib>` | **导入库**，且 `-Wl,-Bdynamic` 在前 |
+| PE / MSVC | 拒绝（不做自动导出；见 docs/12） | —— |
+
+其中三行是新增的：此前除 ELF 之外全部被拒绝，无论原生还是交叉。要让
+它们可用而不只是被允许，有两处细节必须改变。Mach-O 的 install name
+默认取该库被**链接**时所在的路径，因此「只在声明了 `soname` 时才发出
+它」会让其余每一个 `.dylib` 都记下一个构建目录 —— 在构建它的那台机器
+上没问题，换到任何其他机器就是 `image not found`。而这个选择原本是在
+**宿主**上用 `#if defined(__APPLE__)` 做出的，这只在原生 macOS 构建上
+碰巧是对的，对任何交叉链接都是错的；现在它改由目标决定，如同
+`target_output` 早已如此。
+
+**无法服务的目标会被拒绝**，而不是悄悄按宿主构建：在 Linux 上，
+`--target x86_64-windows-msvc` 过去会解析到原生的 `g++`，写进
+`target/x86_64-linux-gnu/`，并报告成功。词汇表的档位说的是「mcpp 支持
+这个目标」；`host_can_serve`（`registry.cppm`）回答的是另一个问题 ——
+「这台机器能不能产出它」，而 `prepare.cppm` 现在会去问这个问题 —— 作者
+可以用显式的 `[target.X] toolchain = "…"` 作为提供自备交叉工具链时的
+出口。
 
 ### 7.5 决定一个 flag 的轴
 
-2026.8.18 那一轮改了四个 flag,每一个此前都挂在错误的轴上。而这类错误的表现
-永远相同:**在恰好一个平台上莫名其妙地失败**,报错既不点名那个 flag,
-也不点名它背后的决定。
+2026.8.18 那一轮改动涉及四个 flag，每一个此前都被挂在了错误的轴上。这些
+错误全都以同一种方式暴露：在恰好一个平台上出现无法解释的失败，而报错既
+不点名那个 flag，也不点名它背后的决定。
 
-一共三根轴,而在它们之间做选择的问题是:**这个 flag 最终被谁读到。**
+一共存在三根轴，在它们之间做选择的问题是：**这个 flag 最终由谁读取。**
 
-| 轴 | 问题 | 例子 | 提问方式 |
+| 轴 | 要问的问题 | 例子 | 查询方式 |
 |---|---|---|---|
-| **目标格式** | 产出的是哪种映像 | `-fPIC`(PE 代码本就位置无关;clang 直接拒绝这个 flag) | `triple::parse(...)->is_pe()`,宿主兜底 |
-| **目标 ABI** | 哪个链接器会消费它 | `--out-implib` vs `/IMPLIB:`、`/DEF:`、SONAME / install-name 的形式 | `is_msvc_target(tc)`、`triple->is_msvc_env()` |
-| **方言** | mcpp 直接调用的是哪个程序 | `-L` vs `/LIBPATH:`、`-I` vs `/I`、归档命令 | `dialect_for(tc)`、`LinkStyle::SeparateLinker` |
+| **目标格式** | 产出的是哪一种镜像 | `-fPIC`（PE 代码按设计就是位置无关的；clang 直接拒绝这个 flag） | `triple::parse(...)->is_pe()`，宿主兜底 |
+| **目标 ABI** | 哪个链接器会消费它 | `--out-implib` 与 `/IMPLIB:`、`/DEF:`，SONAME / install-name 的形式 | `is_msvc_target(tc)`、`triple->is_msvc_env()` |
+| **dialect** | mcpp 调用的是哪个程序 | `-L` 与 `/LIBPATH:`、`-I` 与 `/I`，归档命令 | `dialect_for(tc)`、`LinkStyle::SeparateLinker` |
 
-**面向 MSVC ABI 的 clang 是同时区分这三根轴的那个反例。** 它说 GNU 方言、
-产出 MSVC ABI 的对象、生成 PE 映像。问错了轴就会:
+**面向 MSVC ABI 的 clang，是同时区分这三根轴的那个例子。** 它说 GNU
+dialect、产出 MSVC-ABI 的对象、生成 PE 镜像。问错轴的后果是：
 
-- 按**方言**判 ⇒ 拿到 `-Wl,--out-implib`,lld-link 回
-  `ignoring unknown argument`,随后是「文件不存在」;
-- 按**ABI** 判 ⇒ 拿到 `/LIBPATH:`,而编译器驱动不认;
-- 按**编译器二进制**判 ⇒ 拿到 `-fPIC`,直接拒绝运行。
+- 按 dialect 判定，它会拿到 `-Wl,--out-implib`，lld-link 报出
+  `ignoring unknown argument`，紧接着是文件缺失；
+- 按 ABI 判定，它会拿到 `/LIBPATH:`，而编译器驱动不接受这个写法；
+- 按编译器二进制判定，它会拿到 `-fPIC`，直接拒绝运行。
 
-失败形状总是同一个:flag 按邻近平台的拼法发出去,而报错来自离那个决定三步远的
-另一个程序。面向链接器的答案集中在 `ninja_backend` 的 `pe_link_flag`;
-方言表在原来那个条目的位置写明了为什么它答不了这些问题。
+故障的形状总是相同的：flag 按相邻平台的拼法发出，而诊断信息来自一个与
+那次决定相隔三步的程序。链接器侧的答案集中在 `ninja_backend` 的
+`pe_link_flag` 里；dialect 表在它原来那个条目所在的位置，写明了自己
+为什么答不了这些问题。
 
 ## 8. 源码地图
 
 | 关注点 | 文件 |
 |---|---|
 | spec → xim 包、前端 | `src/toolchain/registry.cppm` |
-| detect/probe(triple、sysroot、payload)| `src/toolchain/detect.cppm`、`probe.cppm` |
+| detect/probe（triple、sysroot、payload） | `src/toolchain/detect.cppm`、`probe.cppm` |
 | 链接模型 + loader 解析 | `modules/toolchain-model/src/linkmodel.cppm` |
-| 统一 fixup 管线(patchelf/specs/cfg、marker)| `src/toolchain/post_install.cppm` |
-| install/lifecycle 入口 | `src/toolchain/lifecycle.cppm`;auto-install 入口在 `src/build/prepare.cppm` |
-| root runtime 选择/binding | `src/xlings/runtime_selection.cppm`、`src/runtime/binding.cppm`、`src/xlings/subos_info.cppm` |
+| 统一 fixup 管线（patchelf/specs/cfg、marker） | `src/toolchain/post_install.cppm` |
+| install/lifecycle 入口 | `src/toolchain/lifecycle.cppm`；auto-install 入口在 `src/build/prepare.cppm` |
+| root runtime 选择 / binding | `src/xlings/runtime_selection.cppm`、`src/runtime/binding.cppm`、`src/xlings/subos_info.cppm` |
 | 通用 runtime contract + LinkIntent | `modules/manifest/src/types.cppm`、`src/build/plan.cppm`、`src/build/flags.cppm` |
-| 存储 resolution 解释 | `src/build/prepare.cppm`、`src/build/runtime_validation.cppm`、`src/doctor.cppm` |
-| flag 组装(主构建)| `src/build/flags.cppm` |
+| 已存储的 resolution 解释 | `src/build/prepare.cppm`、`src/build/runtime_validation.cppm`、`src/doctor.cppm` |
+| flag 组装（主构建） | `src/build/flags.cppm` |
 | `import std;` 预编译 | `src/toolchain/stdmod.cppm` |
-| build.mcpp 宿主 flags | `src/build/build_program.cppm` |
-| hermetic 链接校验 | `src/build/hermetic.cppm` |
-| 回归fence | `tests/e2e/86_llvm_hermetic_link.sh`、单测 `test_linkmodel.cpp`、`test_post_install.cpp`;`ci-linux-e2e.yml` 的无宿主工具链 CI job |
-
+| build.mcpp 宿主 flag | `src/build/build_program.cppm` |
+| hermetic 链接检查 | `src/build/hermetic.cppm` |
+| 回归护栏 | `tests/e2e/86_llvm_hermetic_link.sh`、单元测试 `test_linkmodel.cpp`、`test_post_install.cpp`；`ci-linux-e2e.yml` 中的无宿主工具链 CI job |
diff --git a/docs/zh/92-release.md b/docs/zh/92-release.md
index 76736b5e8..5005e0501 100644
--- a/docs/zh/92-release.md
+++ b/docs/zh/92-release.md
@@ -1,18 +1,19 @@
 # 92 —— 发布 mcpp
 
-**读者:**正在切一次 mcpp 自身发布的维护者。
+**读者：** 正在切一次 mcpp 自身发布的维护者。
 
-**本章回答的那一个问题:**从一个提交到用户可安装的发布版本要走哪些步骤,以及每一步
-怎样被核验。
+**本章回答的那一个问题：** 从一个提交到用户可安装的发布版本要走哪些步骤，
+以及每一步怎样被核验。
 
-**不在这里:**把一个包发布到索引,那是 [11 —— 发布一个库](11-publishing-a-library.md);
-以及版本之间什么可以变,那是 [51](51-supported-versions.md)。
+**不在这里：** 把一个包发布到索引，那是
+[11 —— 发布一个库](11-publishing-a-library.md)；以及版本之间什么可以变，
+那是 [51](51-supported-versions.md)。
 
-**mcpp 自身**的发布如何到达用户手上。本章面向维护者;打包**自有项目**见
-[10 — 打包发布](10-pack-and-release.md)。
+**mcpp 自身**的发布如何到达用户手上。本章面向维护者；打包**普通工程**见
+[10 —— 发布打包](10-pack-and-release.md)。
 
-在此之前这套流程只活在 commit message 和 workflow 注释里，其中一条 commit message
-里的诊断是错的，已在 §5 更正。
+在此之前，这套流程只活在 commit message 与 workflow 注释里，其中一条
+commit message 里的诊断是错的，已在 §5 更正。
 
 ## 1. 三处持久化版本号，加一个运行时推导的 CI 值
 
@@ -20,8 +21,8 @@
 |---|---|---|
 | `mcpp.toml` `[package].version` | **正在构建的** | 开始做新版本时 |
 | `modules/versioning/src/version.cppm` `MCPP_VERSION` | **正在构建的** | 与上一行同一个 commit（编译进二进制的副本） |
-| `.xlings.json` `[workspace].mcpp` | **自举起点** | 单独地、在某个版本**已可安装之后** |
-| `ci-fresh-install.yml` `MCPP_PIN` | **被测版本** | **不变 —— 运行时推导**（§5） |
+| `.xlings.json` `[workspace].mcpp` | **自举起点** | 单独地，在某个版本**已可安装之后** |
+| `ci-fresh-install.yml` `MCPP_PIN` | **被测版本** | **不变——运行时推导**（§5） |
 
 `.github/tools/check_version_pins.sh` 机器校验剩下的关系：两处"正在构建的"
 必须相等，自举 pin 永远不得**新于**正在构建的版本。
@@ -31,7 +32,7 @@ bash .github/tools/check_version_pins.sh
 ```
 
 必须用 **bash** 跑，不能用 `sh`。脚本用了进程替换（`done < <(...)`），
-POSIX `sh`/dash 解析不了 —— `sh check_version_pins.sh` 会在第 95 行附近报
+POSIX `sh`/dash 解析不了——`sh check_version_pins.sh` 会在第 95 行附近报
 `Syntax error: redirection unexpected`。那是**调用它的 shell** 的问题，
 不是脚本的缺陷：它的 shebang 是 `#!/usr/bin/env bash`，CI 也是用 `bash` 调的。
 
@@ -40,7 +41,8 @@ POSIX `sh`/dash 解析不了 —— `sh check_version_pins.sh` 会在第 95 行
 
 ## 2. 发布管线
 
-`release.yml`（推 tag，或 `workflow_dispatch` 不带输入时从 `mcpp.toml` 推导 tag）会做完这些：
+`release.yml`（推 tag，或 `workflow_dispatch` 不带输入时从 `mcpp.toml`
+推导 tag）会做完这些：
 
 ```
 四平台构建（linux x86_64 / linux aarch64 / macOS ARM64 / Windows x64）
@@ -53,64 +55,69 @@ POSIX `sh`/dash 解析不了 —— `sh check_version_pins.sh` 会在第 95 行
 
 ### 2.1 不可变 release manifest
 
-`release-manifest` 会等待四个平台上传 job 全部结束，然后下载最终的非 draft、
-非 prerelease GitHub Release，重新计算每个带版本平台载荷的 SHA256，校验对应的
-`.sha256` 边车文件，并发布 schema 1 的 `mcpp-release.json`：
+`release-manifest` 会等待四个平台上传 job 全部结束，然后下载最终的非
+draft、非 prerelease GitHub Release，重新计算每个带版本平台载荷的
+SHA256，校验对应的 `.sha256` 边车文件，并发布 schema 1 的
+`mcpp-release.json`：
 
 ```json
 {
   "schema": 1,
   "version": "<version>",
   "tag": "v<version>",
-  "commit": "<tag-所指完整-commit>",
+  "commit": "<full-tag-commit>",
   "assets": [
     {
       "platform": "linux",
       "arch": "x86_64",
       "name": "mcpp-<version>-linux-x86_64.tar.gz",
-      "sha256": "<重新计算的-sha256>"
+      "sha256": "<recomputed-sha256>"
     }
   ]
 }
 ```
 
 数组按平台、架构、名称排序，包含所有带版本的平台载荷；其中 Linux x86_64、
-Linux aarch64、macOS ARM64、Windows x86_64 四项是硬性要求。无版本别名和源码包
-刻意不进入 desired-state 行。
+Linux aarch64、macOS ARM64、Windows x86_64 四项是硬性要求。无版本别名与
+源码包刻意不进入 desired-state 行。
 
-workflow 随后会再次下载公开 release、重新生成 manifest，并要求逐字节一致。
-重跑 workflow 时，已有 manifest 只有在字节完全相同时才会被接受；同一 tag 下
-绝不以不同内容覆盖。下游发布消费者（尤其 `mcpp-bin` AUR reconciler）必须消费
-该 manifest，不能从会变化的工作区或部分 release 资产猜测发布是否完整。
+workflow 随后会再次下载公开 release、重新生成 manifest，并要求逐字节
+一致。重跑 workflow 时，已有 manifest 只在字节完全相同时才会被接受；同一
+tag 下绝不以不同内容覆盖。下游发布消费者（尤其 `mcpp-bin` AUR
+reconciler 与 `scripts/pypi/` 中的 `mcpp-bin` PyPI wheel 构建脚本）必须消费该 manifest，不能从会变化的工作区或部分 release
+资产猜测发布是否完整。
 
 两步**没有**自动化：
 
-- **合并 xim-pkgindex 的 bump PR** —— 由维护者完成。在它落地之前，发布出来的版本
-  可以下载，但无法通过 `xlings install` 安装。
-- **bump `.xlings.json`** —— 见 §4。
+- **合并 xim-pkgindex 的 bump PR**——由维护者完成。在它落地之前，发布出来
+  的版本可以下载，但无法通过 `xlings install` 安装。
+- **bump `.xlings.json`**——见 §4。
 
 bump PR 是机器生成的：分支 `bump/mcpp-<version>`，提交者 `xlings-ci
-<ci@xlings.dev>`，diff 恒为 +22/-3。承重的是那三行删除 —— 生成器对每个平台表是
-**替换** `["latest"]` 那一行，而不是新增一行。手写一个索引 PR 并不是等价的捷径；
-在 bot 的 PR 之外另开一个，代价有两份，2026-09-05 的 `xim-pkgindex#764` 两份都付了：
-
-- 手写的 diff 把 `["latest"] = { ref = "<新版>" }` **追加**在原有那行上面而不是替换
-  它，于是每个平台表里留下两个 `["latest"]` 键。Lua 的表构造器以最后一次赋值为准，
-  `latest` 因此解析回上一个发布。精确版本条目存在且正确，所以每个按精确版本 pin 的
-  消费者都是绿的 —— mcpp 自己的 CI 正是精确 pin，完全看不见这件事。只有不带版本的
-  `xlings install mcpp` 会拿到过期的二进制。
+<ci@xlings.dev>`，diff 恒为 +22/-3。承重的是那三行删除——生成器对每个
+平台表是**替换** `["latest"]` 那一行，而不是新增一行。手写一个索引 PR
+并不是等价的捷径；在 bot 的 PR 之外另开一个，代价有两份，2026-09-05 的
+`xim-pkgindex#764` 两份都付了：
+
+- 手写的 diff 把 `["latest"] = { ref = "<新版>" }` **追加**在原有那行上面
+  而不是替换它，于是每个平台表里留下两个 `["latest"]` 键。Lua 的表构造器
+  以最后一次赋值为准，`latest` 因此解析回上一个发布。精确版本条目存在且
+  正确，所以每个按精确版本 pin 的消费者都是绿的——mcpp 自己的 CI 正是
+  精确 pin，完全看不见这件事。只有不带版本的 `xlings install mcpp` 会
+  拿到过期的二进制。
 - 它先于 bot 的 PR 落地，使那个 PR 变成冲突。解法是取 bot 分支那一侧的
   `pkgs/m/mcpp.lua`；它与手写后的 `main` 只差那几行陈旧的 `["latest"]`。
 
-因此，bump PR 合入的判据是 `latest` **解析成什么**，而不是文件里别处出现了版本字符串：
+因此，bump PR 合入的判据是 `latest` **解析成什么**，而不是文件里别处出现
+了版本字符串：
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/openxlings/xim-pkgindex/main/pkgs/m/mcpp.lua \
   | grep -n '\["latest"\]'
 ```
 
-恰好回来三行，每个平台表一行，且都指向刚发布的版本。出现第四行，或某一行指向上一个
-发布，就是上述的重复键缺陷。
+恰好回来三行，每个平台表一行，且都指向刚发布的版本。出现第四行，或某一行
+指向上一个发布，就是上述的重复键缺陷。
 
 ## 3. 验证一次发布
 
@@ -118,16 +125,16 @@ curl -fsSL https://raw.githubusercontent.com/openxlings/xim-pkgindex/main/pkgs/m
 
 ```bash
 V=<version>
-# 双端都服务全部四个平台，字节数一致
+# both hosts serve every platform, byte-exact
 for a in linux-x86_64.tar.gz linux-aarch64.tar.gz macosx-arm64.tar.gz windows-x86_64.zip; do
   for h in github.com gitcode.com; do
     curl -fsSL -o /dev/null -w "$h $a %{http_code} %{size_download}\n" \
       "https://$h/xlings-res/mcpp/releases/download/$V/mcpp-$V-$a"
   done
 done
-# 索引里的 sha256 与载荷相符（**重新计算**，不要读边车文件）
+# the index's sha256 values match the payloads (recompute; do not read the sidecar)
 curl -fsSL -o /tmp/p.tgz "https://github.com/xlings-res/mcpp/releases/download/$V/mcpp-$V-linux-x86_64.tar.gz"
-sha256sum /tmp/p.tgz   # 与 xim-pkgindex 的 pkgs/m/mcpp.lua 对照
+sha256sum /tmp/p.tgz   # compare against pkgs/m/mcpp.lua in xim-pkgindex
 ```
 
 要在本地针对 GitHub 公开资产重放 release gate：
@@ -149,10 +156,11 @@ python3 scripts/release/generate_manifest.py \
 cmp "$AUDIT/assets/mcpp-release.json" "$AUDIT/expected.json"
 ```
 
-这个命令会重新计算载荷哈希，不会从已发布 manifest 抄哈希，也不会盲信边车文件。
+这个命令会重新计算载荷哈希，不会从已发布 manifest 里抄哈希，也不会盲信
+边车文件。
 
-然后在 **clean-room `XLINGS_HOME`** 里真装一次 —— 绝不要用本机的 `~/.xlings`，
-它的缓存状态会把一个坏掉的索引掩盖过去：
+然后在 **clean-room `XLINGS_HOME`** 里真装一次——绝不要用本机的
+`~/.xlings`，它的缓存状态会把一个坏掉的索引掩盖过去：
 
 ```bash
 export XLINGS_HOME=$(mktemp -d)
@@ -161,83 +169,103 @@ xlings install mcpp@$V -y
 $(find "$XLINGS_HOME" -name mcpp -type f -path '*/bin/*' | head -1) --version
 ```
 
-**索引传播不是即时的。** `xim-pkgindex` 是以 CDN artifact 而非 git clone 的形式
-到达客户端的，所以刚合并的 bump 会有一段时间不可见（2026-07-30 实测 ~5 分钟，
-记录在案的上限约 40 分钟）。clean-room 里仍然报旧的 `latest` 不是失败，是**还没追上**。
-`ci-fresh-install` 的 `wait-index` job 正是把这件事编码成了 15 分钟有界等待。
+**索引传播不是即时的。** `xim-pkgindex` 是以 CDN artifact 而非 git clone
+的形式到达客户端的，所以刚合并的 bump 会有一段时间不可见（2026-07-30 实测
+约 5 分钟，记录在案的上限约 40 分钟）。clean-room 里仍然报旧的 `latest`
+不是失败，是**还没追上**。`ci-fresh-install` 的 `wait-index` job 正是把
+这件事编码成了 15 分钟有界等待。
 
 ## 4. 自举 pin 的定义与更新条件
 
-`.xlings.json` 的 `[workspace].mcpp` 是**自举的起点** —— 那个由
-`xlings install mcpp` 装进 workspace、供 CI 从源码构建 mcpp 的已发布 mcpp。
-它唯一的要求是：能构建**当前**这棵源码树。
+`.xlings.json` 的 `[workspace].mcpp` 是**自举的起点**——那个由
+`xlings install mcpp` 装进 workspace、供 CI 从源码构建 mcpp 的已发布
+mcpp。它唯一的要求是：能构建**当前**这棵源码树。
 
-**它不必每次发布都跟着动。** 索引保留每一个已发布版本（撰写时 105 个条目，
-一直回溯到 0.0.x 系列），旧 pin 可以无限期继续解析 —— 这一点用「在当前索引下安装
-一个隔了两个版本的旧版」实测验证过。
+**它不必每次发布都跟着动。** 索引保留每一个已发布版本（撰写时 105 个
+条目，一直回溯到 0.0.x 系列），旧 pin 可以无限期继续解析——这一点用
+「在当前索引下安装一个隔了两个版本的旧版」实测验证过。
 
-跟着 bump 仍然是合理的，也是本仓库的实际做法：bump 后 CI 一轮全绿，直接证明了
-新发布能在每个平台上构建 mcpp 自己。把它当作**一项有用的检查**，而不是前置条件。
+跟着 bump 仍然是合理的，也是本仓库的实际做法：bump 后 CI 一轮全绿，直接
+证明了新发布能在每个平台上构建 mcpp 自己。把它当作**一项有用的检查**，
+而不是前置条件。
 
-**唯一的硬约束是方向**：pin 绝不能指向一个尚不可安装的版本。只在发布已完成、
-已镜像、**且已合入 xim-pkgindex 之后**再 bump —— 否则所有 CI 会以
-`package 'mcpp@<unreleased>' not found` 失败。待其语法问题修复后，
-`check_version_pins.sh` 能卡住较弱的「不得新于正在构建的版本」；索引那个条件需要人工把关。
+**唯一的硬约束是方向**：pin 绝不能指向一个尚不可安装的版本。只在发布
+已完成、已镜像、**且已合入 xim-pkgindex 之后**再 bump——否则所有 CI 会
+以 `package 'mcpp@<unreleased>' not found` 失败。待其语法问题修复后，
+`check_version_pins.sh` 能卡住较弱的「不得新于正在构建的版本」；索引那个
+条件需要人工把关。
 
-「已合入 xim-pkgindex」是必要条件而非充分条件：客户端读的是 CDN 上的 artifact，不是
-git 树。2026-09-05 那次，pin 的 commit 比索引 PR 的合入早到 `main` 19 秒，而它触发的
-CI 作业在新指针资产被替换**之后** 51 秒才去解析索引 —— 拿到的仍然是上一份 artifact。
-九条 workflow 全部死在 bootstrap，没有一条编译过一行。可观测的条件是指针本身：
+「已合入 xim-pkgindex」是必要条件而非充分条件：客户端读的是 CDN 上的
+artifact，不是 git 树。2026-09-05 那次，pin 的 commit 比索引 PR 的合入
+早到 `main` 19 秒，而它触发的 CI 作业在新指针资产被替换**之后** 51 秒才
+去解析索引——拿到的仍然是上一份 artifact。九条 workflow 全部死在
+bootstrap，没有一条编译过一行。可观测的条件是指针本身：
 
 ```bash
 curl -fsSL https://github.com/xlings-res/xim-index/releases/download/latest/xim-index-latest.json \
   | grep -E '"(index_version|source_commit)"'
 ```
 
-推 pin 之前，`index_version` 必须等于 xim-pkgindex `main` 的短 SHA。没有任何东西强制
-这一点，而在作业日志里，由此产生的失败与「版本名真的写错了」无法区分。
+推 pin 之前，`index_version` 必须等于 xim-pkgindex `main` 的短 SHA。没有
+任何东西强制这一点，而在作业日志里，由此产生的失败与「版本名真的写错了」
+无法区分。
 
 ## 5. `MCPP_PIN` 改为推导，以及由此产生的结果
 
-`ci-fresh-install.yml` 过去带着 pin 的第二份手工副本。它们从来就不是一回事：
-`MCPP_PIN` 是**被测版本** —— 永远是最新的已发布版本；而 `.xlings.json` 是
-**自举来源**。
+`ci-fresh-install.yml` 过去带着 pin 的第二份手工副本。它们从来就不是
+一回事：`MCPP_PIN` 是**被测版本**——永远是最新的已发布版本；而
+`.xlings.json` 是**自举来源**。
 
-现在它由 `wait-index` job 从 releases API 推导一次，所有安装 job 消费同一个输出。
-有两条性质必须成立，而写死的字面量只买到了第一条：
+现在它由 `wait-index` job 从 releases API 推导一次，所有安装 job 消费
+同一个输出。有两条性质必须成立，而写死的字面量只买到了第一条：
 
-1. **版本必须是显式的。** 裸 `xlings install mcpp` 解析的是「runner 自己那份索引副本里
-   的最新」，于是副本落后的 runner 会**悄悄测一个旧二进制然后报绿**。写明版本能让落后的
-   索引以 `version not found` 响亮失败。推导出来的字符串与字面量一样显式。
-2. **守卫等的版本必须就是 job 装的版本。** 2026-07-21 它们不是：索引守卫报
-   「index tracks 0.0.102」，10 秒后 job 装的是 0.0.100，撞上 floor 为 0.0.101 的索引（#265）。
-   守卫本来就推导出了正确答案，然后把它扔掉了。让两者吃同一个值，
-   使这种不一致在结构上不可能发生。
+1. **版本必须是显式的。** 裸 `xlings install mcpp` 解析的是「runner 自己
+   那份索引副本里的最新」，于是副本落后的 runner 会**悄悄测一个旧二进制
+   然后报绿**。写明版本能让落后的索引以 `version not found` 响亮失败。
+   推导出来的字符串与字面量一样显式。
+2. **守卫与作业必须名指同一个版本。** 2026-07-21 它们不是：索引守卫报
+   「index tracks 0.0.102」，10 秒后 job 装的是 0.0.100，撞上 floor 为
+   0.0.101 的索引（#265）。守卫本来就推导出了正确答案，然后把它扔掉了。
+   让两者吃同一个值，使这种不一致在结构上不可能发生。
 
-`check_version_pins.sh` 会在字面量 `MCPP_PIN:` 重新出现时报错。不要重新引入字面量，
-否则索引守卫与实际安装版本又会发生漂移。
+`check_version_pins.sh` 会在字面量 `MCPP_PIN:` 重新出现时报错。不要重新
+引入字面量，否则索引守卫与实际安装版本又会发生漂移。
 
 > **更正。** commit `3b1cb6b`（"bootstrap pin -> 2026.7.29.2"）写着
-> *"the index no longer serves .1"* 并引用了 `version '2026.7.29.1' not found`。
-> **这个诊断是错的**：`2026.7.29.1` 在当前索引下能正常安装。真正的原因是
-> **本地索引副本陈旧** —— 就是 §3 描述的那个传播滞后，只是从另一侧看到的。
-> 发布不会移除任何旧版本，任何推理都不该建立在「会移除」这个前提上。
+> *"the index no longer serves .1"* 并引用了
+> `version '2026.7.29.1' not found`。**这个诊断是错的**：`2026.7.29.1`
+> 在当前索引下能正常安装。真正的原因是**本地索引副本陈旧**——就是 §3
+> 描述的那个传播滞后，只是从另一侧看到的。发布不会移除任何旧版本，任何
+> 推理都不该建立在「会移除」这个前提上。
+
+> **同一种误诊，再度发生（2026-08-06）。** `ci-aarch64-fresh-install`
+> 失败并报出 `xlings: version '2026.8.5.3' not found for 'mcpp' —
+> available: 2026.8.6.1`，修复该问题的 commit 再次声称索引丢掉了那个
+> 版本。事实并非如此：`openxlings/xim-pkgindex` 与 `d2learn/xim-pkgindex`
+> 都列出了 63 个 mcpp 版本，包含 `2026.8.5.3`。注意 `available:` 实际
+> 枚举出的东西——只有一个版本，正是那次作业刚装上的那个——这是**已安装
+> 版本**视图的形状，不是索引列表的形状。那一步解析的是 `.xlings.json`
+> 的 **workspace** pin，而 workspace 作用域的解析正是已有记录在案的
+> 作用域陷阱。
+>
+> 这次 bump 本身没有问题（§4 认可它，它也确实解除了该作业的阻塞）。
+> 教训更窄，而且一再被重新学到一遍：**在下结论「索引丢了它」之前，先读
+> 索引。** 对 `pkgs/m/mcpp.lua` 执行一次 `curl` 就能定案。
 
 ## 6. 检查清单
 
 ```
-[ ] mcpp.toml + fingerprint.cppm 版本号已 bump（同一个 commit）
-[ ] CHANGELOG 条目
-[ ] `bash .github/tools/check_version_pins.sh` 通过（校验 `mcpp.toml` = `MCPP_VERSION`，且 `.xlings.json` 未领先）
-[ ] 合入 main，CI 全绿
+[ ] version bumped in mcpp.toml + fingerprint.cppm (one commit)
+[ ] CHANGELOG entry
+[ ] `bash .github/tools/check_version_pins.sh` passes (verifies `mcpp.toml` = `MCPP_VERSION`, and `.xlings.json` is not newer)
+[ ] merge to main, CI green
 [ ] gh workflow run release.yml --ref main
-[ ] release.yml 全绿（4 个构建 + 不可变 manifest + publish-ecosystem）
-[ ] 下载的 mcpp-release.json 能从公开资产逐字节重新生成
-[ ] 双端都服务四个平台，sha256 重新算过
-[ ] 合并 xim-pkgindex 的 bump PR
-[ ] 索引的 `latest` 在三个平台表里都解析到新版本
-[ ] xim-index-latest.json 的 `index_version` 等于 xim-pkgindex `main`
-[ ] clean-room XLINGS_HOME：xlings install mcpp@<version> 成功
-[ ] （可选）bump .xlings.json —— 只在此刻，绝不提前
+[ ] release.yml green (4 builds + immutable manifest + publish-ecosystem)
+[ ] downloaded mcpp-release.json regenerates byte-identically from public assets
+[ ] mirrors serve all four platforms on BOTH hosts, sha256 recomputed
+[ ] merge the xim-pkgindex bump PR
+[ ] index `latest` resolves to the new version in all three platform tables
+[ ] xim-index-latest.json's `index_version` equals xim-pkgindex `main`
+[ ] clean-room XLINGS_HOME: xlings install mcpp@<version> succeeds
+[ ] (optional) bump .xlings.json — only now, never earlier
 ```
-
diff --git a/docs/zh/README.md b/docs/zh/README.md
index 9835cfa16..ec880757c 100644
--- a/docs/zh/README.md
+++ b/docs/zh/README.md
@@ -3,20 +3,20 @@
 [English](../README.md) | **简体中文**
 
 这棵树是 **mcpp 已实现功能的使用手册**。每一章陈述一个能力做什么、怎么写、
-当前边界在哪里。设计理由、被否掉的替代方案、以及尚未发布的规划,**不写在这里**
-—— 它们属于设计记录,而设计记录不是用户文档。
+当前边界在哪里。设计理由、被否掉的替代方案，以及尚未发布的规划，刻意不写
+在这里——它们属于设计记录，而设计记录不是用户文档。
 
 ## 文档的归属
 
 | 树 | 读者 | 内容 |
 |---|---|---|
 | `docs/**` | 手上有任务的人 | mcpp 已实现的东西怎么用 |
-| [`docs/specs/**`](../specs/README.md) | 对着机制做实现的人:索引作者、下游工具、贡献者 | 语义、约束与匹配规则,每条标注实现状态 |
-| `.agents/docs/**` | 做过某次改动的人,以及以后问「为什么是这样」的人 | 推理、实测,以及什么被推翻了 |
+| [`docs/specs/**`](../specs/README.md) | 对着机制做实现的人：索引作者、下游工具、贡献者 | 语义、约束与匹配规则，每条标注实现状态 |
+| `.agents/docs/**` | 做过某次改动的人，以及以后问「为什么是这样」的人 | 推理、实测，以及什么被推翻了 |
 | `.agents/skills/**` | 照流程执行的贡献者或 agent | 带判据的步骤 |
 
-章节引用规范以取得精确语义,但**不引用设计记录**:记录描述的是一个时刻,不带
-稳定性承诺,因此读者需要的东西一律写在本树或规范里。
+章节引用规范以取得精确语义，但不引用设计记录：设计记录描述的是一个时刻，
+不带稳定性承诺，因此读者需要的东西一律写在本树或规范里。
 
 ## 从这里开始
 
@@ -26,19 +26,19 @@
 | 写一个供他人 import 的库 | [11](11-publishing-a-library.md)、[06](06-features-and-capabilities.md)、[04](04-mcpp-toml.md) §2.4 | [`04-workspace`](../../examples/04-workspace/)、[`11-features`](../../examples/11-features/) |
 | 发布它 | [10](10-pack-and-release.md)、[11](11-publishing-a-library.md)、[12](12-binary-distribution.md) | [`03-pack-static`](../../examples/03-pack-static/)、[`05-lib-distribution`](../../examples/05-lib-distribution/) |
 | 为另一台机器构建 | [21](21-the-target-triple.md)、[24](24-openkal-cross.md)、[40](40-baremetal.md) | [`06-openkal-cross`](../../examples/06-openkal-cross/)、`mcpp new … --template riscv-virt-rt` |
-| 使用 GPU 或加速器 | [42](42-heterogeneous-builds.md)、[41](41-devices.md) | [`09-heterogeneous`](../../examples/09-heterogeneous/),从 [`boundary/`](../../examples/09-heterogeneous/boundary/) 开始 |
+| 使用 GPU 或加速器 | [42](42-heterogeneous-builds.md)、[41](41-devices.md) | [`09-heterogeneous`](../../examples/09-heterogeneous/)，从 [`boundary/`](../../examples/09-heterogeneous/boundary/) 开始 |
 | 增加一条规则、一种语言或一个生成器 | [31](31-authoring-a-rule-package.md)、[30](30-build-mcpp.md) | [`08-build-rules`](../../examples/08-build-rules/)、[`12-a-new-device-language`](../../examples/12-a-new-device-language/) |
-| 向索引添加一个包 | [11](11-publishing-a-library.md)、[SPEC-001](../specs/package-identity.md) | [09](09-commands-by-scenario.md) —— 发布相关场景 |
+| 向索引添加一个包 | [11](11-publishing-a-library.md)、[SPEC-001](../specs/package-identity.md) | [09](09-commands-by-scenario.md)——发布相关场景 |
 | 为别人打包一个工具、一个驱动或一块板子 | [32](32-authoring-a-payload.md)、[33](33-authoring-an-adapter.md)、[34](34-authoring-a-bsp.md) | `xim-pkgindex` 与 `mcpp-index` 里的描述符 |
 | 修改 mcpp 本身 | [90](90-build-from-source.md)、[92](92-release.md)、[51](51-supported-versions.md) | — |
 
-课程也可以以**项目模板**的形式到达:模板由包提供,`mcpp new --template` 实例化
-它。今天有文档的两个是 `riscv-virt-rt`(裸机)与 `ocornut.imgui`(图形应用),
-用到它的章节会点名。
+课程也可以以**项目模板**的形式到达：模板由包提供，`mcpp new --template`
+实例化它。今天有文档的两个是 `riscv-virt-rt`（裸机）与 `ocornut.imgui`
+（图形应用），用到它的章节会点名。
 
 ## 章节
 
-首位数字就是部分,所以编号本身说明一章属于哪里:
+首位数字就是部分，所以编号本身说明一章属于哪里：
 
 | | |
 |---|---|
@@ -50,20 +50,20 @@
 | `5x` | 程序可以解析的契约 |
 | `9x` | mcpp 自身 |
 
-同一部分内部的排列是阅读顺序,不是字母序。
+同一部分内部的排列是阅读顺序，不是字母序。
 
 ### 0x —— 基础
 
-- [00 —— mcpp 是什么](00-what-mcpp-is.md) —— 它是什么、它做什么,以及一段真的跑过的会话
-- [01 —— 快速开始](01-getting-started.md) —— 安装、创建、构建、运行
-- [02 —— 场景](02-scenarios.md) —— mcpp 被用来做什么,以及每一类工作会用到它的哪些功能
-- [03 —— 示例项目](03-examples.md) —— 哪个示例教什么
-- [04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md) —— manifest 可以说什么
-- [05 —— 依赖与解析](05-dependencies.md) —— 依赖从哪里来,以及哪个版本胜出
-- [06 —— Feature 与能力](06-features-and-capabilities.md) —— 让包的一部分成为可选
-- [07 —— 工作空间](07-workspace.md) —— 多个包,一次构建
-- [08 —— 测试](08-testing.md) —— 包括在本机跑不了的那些
-- [09 —— 按场景选命令](09-commands-by-scenario.md) —— 认识名词之后的查阅入口
+- [00 —— mcpp 是什么](00-what-mcpp-is.md)——它是什么、它做什么，以及一段真的跑过的会话
+- [01 —— 快速开始](01-getting-started.md)——安装、创建、构建、运行
+- [02 —— 场景](02-scenarios.md)——mcpp 被用来做什么，以及每一类工作会用到它的哪些功能
+- [03 —— 示例项目](03-examples.md)——哪个示例教什么
+- [04 —— mcpp.toml 工程文件指南](04-mcpp-toml.md)——manifest 可以说什么
+- [05 —— 依赖与解析](05-dependencies.md)——依赖从哪里来，以及哪个版本胜出
+- [06 —— Feature 与能力](06-features-and-capabilities.md)——让包的一部分成为可选
+- [07 —— 工作空间](07-workspace.md)——多个包，一次构建
+- [08 —— 测试](08-testing.md)——包括在本机跑不了的那些
+- [09 —— 按场景选命令](09-commands-by-scenario.md)——认识名词之后的查阅入口
 
 ### 1x —— 发布
 
@@ -81,16 +81,16 @@
 
 ### 3x —— 扩展 mcpp 与它的生态
 
-- [30 —— 构建程序:`build.mcpp`](30-build-mcpp.md) —— 工程需要一步 mcpp 没有规则的工作
-- [31 —— 编写规则包](31-authoring-a-rule-package.md) —— 把那一步打包给别的工程用
-- [32 —— 编写一个载荷](32-authoring-a-payload.md) —— 由 mcpp 安装的工具或预编译库
-- [33 —— 编写运行时适配包](33-authoring-an-adapter.md) —— 够到宿主提供的库
-- [34 —— 编写板级支持包](34-authoring-a-bsp.md) —— 一块板子,以及抵达它的方式
+- [30 —— 构建程序：`build.mcpp`](30-build-mcpp.md)——工程需要一步 mcpp 没有规则的工作
+- [31 —— 编写规则包](31-authoring-a-rule-package.md)——把那一步打包给别的工程用
+- [32 —— 编写一个载荷](32-authoring-a-payload.md)——由 mcpp 安装的工具或预编译库
+- [33 —— 编写运行时适配包](33-authoring-an-adapter.md)——够到宿主提供的库
+- [34 —— 编写板级支持包](34-authoring-a-bsp.md)——一块板子，以及抵达它的方式
 
 ### 4x —— 设备与加速器
 
 - [40 —— 裸机与 freestanding 目标](40-baremetal.md)
-- [41 —— 抵达一台设备](41-devices.md)
+- [41 —— 在设备上运行](41-devices.md)
 - [42 —— 异构硬件构建](42-heterogeneous-builds.md)
 
 ### 5x —— 面向程序的契约
@@ -106,8 +106,8 @@
 
 ## 反查
 
-上面的章节表是**阅读顺序**。这里是另一种索引:从读者眼前的一个记号,查到拥有它的
-那一章。
+上面的章节表是**阅读顺序**。这里是另一种索引：从读者眼前的一个记号，查到
+拥有它的那一章。
 
 **manifest 的表与键**
 
@@ -123,7 +123,7 @@
 | `runner`、`[target.<t>.runners]` | [41](41-devices.md) | `rule_module` | [31](31-authoring-a-rule-package.md) |
 | `min_api_level` | [04](04-mcpp-toml.md) | `macos_deployment_target` | [04](04-mcpp-toml.md) |
 | `[target.<sel>.targets.<n>] kind` | [22](22-target-side.md) | `config.toml` 中的 `[index.repos.<name>]` | [32](32-authoring-a-payload.md) |
-| `[test] discover` | [04](04-mcpp-toml.md), [08](08-testing.md) | `MCPP_RUNTIME_FILES` | [41](41-devices.md) |
+| `[test] discover` | [04](04-mcpp-toml.md)、[08](08-testing.md) | `MCPP_RUNTIME_FILES` | [41](41-devices.md) |
 
 **命令**
 
@@ -138,7 +138,7 @@
 
 | | 章节 | | 章节 |
 |---|---|---|---|
-| mcpp 是什么,以及那条保证 | [00](00-what-mcpp-is.md) | `import std`、模块接口、BMI | [20](20-toolchains.md)、[30](30-build-mcpp.md) |
+| mcpp 是什么，以及那条保证 | [00](00-what-mcpp-is.md) | `import std`、模块接口、BMI | [20](20-toolchains.md)、[30](30-build-mcpp.md) |
 | `mcpp::action`、构建程序 | [30](30-build-mcpp.md) | 规则包 | [31](31-authoring-a-rule-package.md) |
 | 目标三元组、支持矩阵 | [21](21-the-target-triple.md) | runner、具名 runner | [41](41-devices.md) |
 | 岛、接缝、`accel`、`MCPP_EXPORT_C` | [42](42-heterogeneous-builds.md) | 描述符、索引 | [11](11-publishing-a-library.md) |
@@ -147,12 +147,12 @@
 
 ## 规范文档
 
-规范性文档 —— 语义、约束与匹配规则,每条规则标注其实现状态。
-面向索引作者、贡献者与下游工具。
+规范性文档——语义、约束与匹配规则，每条规则标注其实现状态。面向索引作者、
+贡献者与下游工具。
 
-- [specs/](../specs/README.md) —— 全部规范的索引
+- [specs/](../specs/README.md)——全部规范的索引
   - [SPEC-001 —— 包身份、`[dependencies]` 选择器与匹配](../specs/package-identity.md)
-  - [SPEC-002 —— 目标侧模型:保留命名空间、五层、三条规则](../specs/target-side.md)
+  - [SPEC-002 —— 目标侧模型：保留命名空间、五层、三条规则](../specs/target-side.md)
   - [SPEC-003 —— 退出码契约](../specs/exit-codes.md)
   - [SPEC-004 —— `mcpp.toml` 的平面划分、条件化形状、解析轴与命名规约](../specs/manifest-semantics.md)
   - [SPEC-005 —— `mcpp emit build-database` 输出的构建数据库](../specs/build-database.md)
diff --git a/scripts/pypi/README.md b/scripts/pypi/README.md
new file mode 100644
index 000000000..e880e6840
--- /dev/null
+++ b/scripts/pypi/README.md
@@ -0,0 +1,99 @@
+# PyPI packaging (`mcpp-bin`)
+
+`pip install mcpp-bin` installs the prebuilt release binary and puts the `mcpp`
+command on the environment's `PATH`. The PyPI name is `mcpp-bin` because `mcpp`
+on PyPI is an unrelated project, which is the same situation as on the AUR and
+Homebrew.
+
+## Wheels
+
+One wheel per payload in the release's `mcpp-release.json`:
+
+| Payload | Wheel platform tag |
+| --- | --- |
+| `linux-x86_64` | `manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64` |
+| `linux-aarch64` | `manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64` |
+| `macosx-arm64` | `macosx_14_0_arm64` |
+| `windows-x86_64` | `win_amd64` |
+
+The Linux payloads are fully static musl binaries, so one wheel carries both
+the glibc and the musl tag. The macOS floor is the one the Homebrew formula
+states. There is no sdist; on any other platform, pip reports that no
+distribution matches.
+
+Each wheel holds the same two binaries the AUR package ships, plus a launcher:
+
+| Path in site-packages | Contents |
+| --- | --- |
+| `mcpp_bin/bin/mcpp[.exe]` | the release binary |
+| `mcpp_bin/registry/bin/xlings[.exe]` | the bundled xlings |
+| `mcpp_bin/__init__.py` | the launcher behind the `mcpp` console script |
+
+## The launcher
+
+mcpp writes its registry sandbox, caches and toolchains into `MCPP_HOME`, and
+it resolves that home from the real path of its binary. Resolved from
+site-packages, the home would sit inside the Python environment, which may be
+shared or read-only and is removed by `pip uninstall`. The launcher therefore
+sets `MCPP_HOME=~/.mcpp` (`%USERPROFILE%\.mcpp` on Windows) and
+`MCPP_VENDORED_XLINGS=<site-packages>/mcpp_bin/registry/bin/xlings`, the same
+two variables `scripts/aur/mcpp-bin/mcpp.sh` sets. A value the user already
+exported is kept. On POSIX the launcher `exec`s the binary; on Windows it runs
+the binary as a child process and exits with its status.
+
+## Publishing
+
+[`.github/workflows/pypi-publish.yml`](../../.github/workflows/pypi-publish.yml):
+
+1. runs [`tests/scripts/test_pypi_wheels.py`](../../tests/scripts/test_pypi_wheels.py);
+2. builds the four wheels with [`build_wheels.py`](build_wheels.py) from the
+   release manifest, checking each payload's sha256 against it;
+3. runs `twine check --strict`;
+4. installs from the directory of all four wheels on Linux x86_64, Linux
+   aarch64, macOS arm64 and Windows x86_64, so pip picks the wheel. It then
+   checks the version, that `MCPP_HOME` is outside the Python environment, and,
+   on POSIX, that the bundled xlings was seeded into the home;
+5. uploads to PyPI through Trusted Publishing, when publishing is enabled.
+
+| Trigger | Publishes |
+| --- | --- |
+| `release` completed | only if the repository variable `PYPI_AUTOPUBLISH` is `true` |
+| `workflow_dispatch` | only if its `publish` input is checked |
+| `pull_request` touching the packaging | never; builds and installs the latest release |
+
+A version already on PyPI is never uploaded again. PyPI refuses to replace a
+file, so such a run reports "already on PyPI" and succeeds.
+
+To build locally without uploading:
+
+```bash
+python3 scripts/pypi/build_wheels.py --tag v2026.9.21.3 --out dist/
+python3 -m venv /tmp/v && /tmp/v/bin/pip install --no-index --find-links dist mcpp-bin
+```
+
+## One-time setup
+
+No token or secret is stored in the repository.
+
+1. **PyPI.** Signed in to PyPI, open
+   <https://pypi.org/manage/account/publishing/> and add a *pending publisher*:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI Project Name | `mcpp-bin` |
+   | Owner | `mcpp-community` |
+   | Repository name | `mcpp` |
+   | Workflow name | `pypi-publish.yml` |
+   | Environment name | `pypi` |
+
+   The first successful upload creates the project, and the pending publisher
+   becomes its trusted publisher.
+2. **GitHub.** In the repository's *Settings → Environments*, create an
+   environment named `pypi`. Required reviewers are optional; with them, each
+   upload waits for an approval.
+3. **First publish.** Run the workflow by hand with `publish` checked (*Actions →
+   pypi-publish → Run workflow*), and confirm that
+   <https://pypi.org/project/mcpp-bin/> shows the version.
+4. **Arming.** Set the repository variable `PYPI_AUTOPUBLISH` to `true`
+   (*Settings → Secrets and variables → Actions → Variables*). From then on,
+   every completed release publishes its wheels.
diff --git a/scripts/pypi/README.pypi.md b/scripts/pypi/README.pypi.md
new file mode 100644
index 000000000..56afb95f2
--- /dev/null
+++ b/scripts/pypi/README.pypi.md
@@ -0,0 +1,27 @@
+# mcpp-bin
+
+The prebuilt [mcpp](https://github.com/mcpp-community/mcpp) {version} release
+binary, packaged for `pip`. mcpp is a module-first build tool for modern C++:
+`import std`, module interface units and partitions, a package index,
+toolchain management and cross-compilation from one command.
+
+```bash
+pip install mcpp-bin
+mcpp new hello && cd hello && mcpp build && mcpp run
+```
+
+The package installs the `mcpp` command. The PyPI name is `mcpp-bin` because
+`mcpp` belongs to an unrelated project.
+
+Wheels are published for Linux x86_64 and aarch64 (fully static, glibc or
+musl), macOS 14+ on Apple silicon, and Windows x86_64. Each wheel carries the
+same release payload as `install.sh`, Homebrew and the AUR `mcpp-bin` package.
+
+mcpp keeps its registry sandbox, caches and downloaded toolchains in
+`~/.mcpp` (`%USERPROFILE%\.mcpp` on Windows), not in the Python environment.
+Set `MCPP_HOME` to use another directory. The first `mcpp build` initialises
+that directory and fetches a toolchain, which takes a while once per user.
+`pip uninstall mcpp-bin` removes the command; delete `~/.mcpp` to remove the
+per-user data as well.
+
+Documentation: <https://github.com/mcpp-community/mcpp/tree/main/docs>
diff --git a/scripts/pypi/build_wheels.py b/scripts/pypi/build_wheels.py
new file mode 100644
index 000000000..f27aa7dad
--- /dev/null
+++ b/scripts/pypi/build_wheels.py
@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Build the `mcpp-bin` PyPI wheels from one published mcpp release.
+
+Each wheel carries the prebuilt release payload for one platform, the same
+bytes `install.sh`, Homebrew and the AUR `mcpp-bin` package install:
+
+    mcpp_bin/__init__.py            launcher (the `mcpp` console script)
+    mcpp_bin/bin/mcpp[.exe]         the release binary
+    mcpp_bin/registry/bin/xlings    the bundled xlings
+
+The launcher pins MCPP_HOME to the per-user home and MCPP_VENDORED_XLINGS to
+the bundled xlings, for the reason scripts/aur/README.md gives: mcpp resolves
+its home from the real path of its binary, and site-packages is not a place a
+per-user sandbox may be written into.
+
+INPUT IS THE RELEASE MANIFEST, NOT THE ASSET LISTING. `mcpp-release.json` is
+the release workflow's statement of which payloads are complete (docs/92). A
+wheel is built only for a row it names, and only from bytes whose sha256
+matches the row.
+
+The wheels are written by hand with the standard library. A wheel is a zip
+with three metadata files, and a build backend would add a dependency without
+adding anything this script needs.
+
+Usage:
+  build_wheels.py --tag v2026.9.21.3 --out dist/
+  build_wheels.py --release-dir DIR --out dist/     # offline, from local files
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import io
+import json
+import shutil
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+REPO = "mcpp-community/mcpp"
+DIST_NAME = "mcpp-bin"
+WHEEL_NAME = "mcpp_bin"
+SUMMARY = "Modern C++ module-first build tool (prebuilt mcpp binary)"
+
+# (platform, arch) from mcpp-release.json -> wheel platform tag.
+#
+# The Linux payloads are fully static musl binaries, so one wheel serves both
+# glibc and musl installers. The glibc floor is the lowest manylinux tag pip
+# on the target arch accepts; the binary itself needs none.
+PLATFORM_TAGS = {
+    ("linux", "x86_64"):
+        "manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64",
+    ("linux", "aarch64"):
+        "manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64",
+    # The Homebrew formula states the same floor: Apple silicon + macOS 14.
+    ("macos", "arm64"): "macosx_14_0_arm64",
+    ("windows", "x86_64"): "win_amd64",
+}
+
+LAUNCHER = '''\
+"""mcpp launcher installed by the `mcpp-bin` PyPI package.
+
+mcpp writes its registry sandbox, caches and downloaded toolchains into
+MCPP_HOME. The package directory is shared and may be read-only, so the
+launcher pins the per-user home that install.sh uses, and points mcpp at the
+bundled xlings, which mcpp copies into that home on first run. A value the
+user already exported is kept.
+"""
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+__version__ = "{version}"
+
+_HERE = Path(__file__).resolve().parent
+_EXE = ".exe" if os.name == "nt" else ""
+
+
+def binary() -> Path:
+    return _HERE / "bin" / ("mcpp" + _EXE)
+
+
+def main() -> None:
+    exe = binary()
+    xlings = _HERE / "registry" / "bin" / ("xlings" + _EXE)
+    env = os.environ
+    env.setdefault("MCPP_HOME", str(Path.home() / ".mcpp"))
+    env.setdefault("MCPP_VENDORED_XLINGS", str(xlings))
+    argv = [str(exe), *sys.argv[1:]]
+    if os.name == "nt":
+        # No exec on Windows: wait for the child and forward its status.
+        # Ctrl+C reaches the child through the shared console; the launcher
+        # only has to outlive it.
+        try:
+            rc = subprocess.call(argv)
+        except KeyboardInterrupt:
+            rc = 130
+        sys.exit(rc)
+    os.execv(str(exe), argv)
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+MAIN = "from mcpp_bin import main\n\nmain()\n"
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def fetch(url: str, dest: Path) -> None:
+    for attempt in range(4):
+        try:
+            with urllib.request.urlopen(url, timeout=120) as r, dest.open("wb") as f:
+                shutil.copyfileobj(r, f)
+            return
+        except OSError as e:
+            if attempt == 3:
+                raise
+            print(f"retry {attempt + 1}: {url}: {e}", file=sys.stderr)
+
+
+def payload_members(archive: Path) -> dict[str, tuple[bytes, bool]]:
+    """Return {relative path: (bytes, executable)} for the files a wheel carries.
+
+    Only bin/mcpp, registry/bin/xlings and LICENSE are taken, matching the AUR
+    package: the bundle's root `mcpp` / `mcpp.bat` convenience entry and its
+    README are not part of the runtime.
+    """
+    wanted = {
+        "bin/mcpp", "bin/mcpp.exe",
+        "registry/bin/xlings", "registry/bin/xlings.exe",
+        "LICENSE",
+    }
+    out: dict[str, tuple[bytes, bool]] = {}
+    if archive.name.endswith(".zip"):
+        with zipfile.ZipFile(archive) as z:
+            for info in z.infolist():
+                rel = info.filename.split("/", 1)[-1] if "/" in info.filename else ""
+                if rel in wanted:
+                    out[rel] = (z.read(info), rel.endswith(".exe"))
+    else:
+        with tarfile.open(archive, "r:gz") as t:
+            for m in t.getmembers():
+                rel = m.name.split("/", 1)[-1] if "/" in m.name else ""
+                if rel in wanted and m.isfile():
+                    data = t.extractfile(m).read()
+                    out[rel] = (data, bool(m.mode & 0o111))
+    exe = ".exe" if archive.name.endswith(".zip") else ""
+    for need in (f"bin/mcpp{exe}", f"registry/bin/xlings{exe}", "LICENSE"):
+        if need not in out:
+            raise SystemExit(f"{archive.name}: payload has no {need}")
+    return out
+
+
+def record_hash(data: bytes) -> str:
+    digest = hashlib.sha256(data).digest()
+    return "sha256=" + base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+
+
+def metadata(version: str, readme: str) -> str:
+    return "\n".join([
+        "Metadata-Version: 2.1",
+        f"Name: {DIST_NAME}",
+        f"Version: {version}",
+        f"Summary: {SUMMARY}",
+        f"Home-page: https://github.com/{REPO}",
+        "License: Apache-2.0",
+        f"Project-URL: Source, https://github.com/{REPO}",
+        f"Project-URL: Documentation, https://github.com/{REPO}/tree/main/docs",
+        f"Project-URL: Changelog, https://github.com/{REPO}/blob/main/CHANGELOG.md",
+        "Classifier: License :: OSI Approved :: Apache Software License",
+        "Classifier: Programming Language :: C++",
+        "Classifier: Topic :: Software Development :: Build Tools",
+        "Classifier: Operating System :: POSIX :: Linux",
+        "Classifier: Operating System :: MacOS",
+        "Classifier: Operating System :: Microsoft :: Windows",
+        "Requires-Python: >=3.8",
+        "Description-Content-Type: text/markdown",
+        "",
+        readme,
+    ])
+
+
+def build_wheel(version: str, platform_tag: str, members: dict[str, tuple[bytes, bool]],
+                readme: str, out_dir: Path) -> Path:
+    tag = f"py3-none-{platform_tag}"
+    dist_info = f"{WHEEL_NAME}-{version}.dist-info"
+    files: list[tuple[str, bytes, bool]] = [
+        (f"{WHEEL_NAME}/__init__.py", LAUNCHER.format(version=version).encode(), False),
+        (f"{WHEEL_NAME}/__main__.py", MAIN.encode(), False),
+    ]
+    for rel, (data, _) in sorted(members.items()):
+        if rel == "LICENSE":
+            files.append((f"{dist_info}/LICENSE", data, False))
+        else:
+            files.append((f"{WHEEL_NAME}/{rel}", data, True))
+    files += [
+        (f"{dist_info}/METADATA", metadata(version, readme).encode(), False),
+        (f"{dist_info}/WHEEL", (
+            "Wheel-Version: 1.0\n"
+            "Generator: mcpp scripts/pypi/build_wheels.py\n"
+            "Root-Is-Purelib: false\n"
+            + "".join(f"Tag: py3-none-{p}\n" for p in platform_tag.split("."))
+        ).encode(), False),
+        (f"{dist_info}/entry_points.txt",
+         b"[console_scripts]\nmcpp = mcpp_bin:main\n", False),
+    ]
+    record_name = f"{dist_info}/RECORD"
+    record = io.StringIO()
+    for name, data, _ in files:
+        record.write(f"{name},{record_hash(data)},{len(data)}\n")
+    record.write(f"{record_name},,\n")
+    files.append((record_name, record.getvalue().encode(), False))
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / f"{WHEEL_NAME}-{version}-{tag}.whl"
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
+        for name, data, is_exec in files:
+            info = zipfile.ZipInfo(name, date_time=(2020, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_DEFLATED
+            # pip applies the executable bits it finds in the entry's mode.
+            info.external_attr = ((0o755 if is_exec else 0o644) | 0o100000) << 16
+            z.writestr(info, data)
+    return path
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    src = ap.add_mutually_exclusive_group(required=True)
+    src.add_argument("--tag", help="release tag, e.g. v2026.9.21.3")
+    src.add_argument("--release-dir", type=Path,
+                     help="directory holding mcpp-release.json and its payloads")
+    ap.add_argument("--out", type=Path, required=True)
+    ap.add_argument("--readme", type=Path,
+                    default=Path(__file__).with_name("README.pypi.md"))
+    args = ap.parse_args(argv)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        rel_dir = args.release_dir or Path(tmp)
+        base = f"https://github.com/{REPO}/releases/download/{args.tag}"
+        manifest_path = rel_dir / "mcpp-release.json"
+        if args.tag:
+            fetch(f"{base}/mcpp-release.json", manifest_path)
+        manifest = json.loads(manifest_path.read_text())
+        version = manifest["version"]
+        if args.tag and manifest.get("tag") != args.tag:
+            raise SystemExit(f"manifest names {manifest.get('tag')}, expected {args.tag}")
+        readme = args.readme.read_text().replace("{version}", version)
+
+        built = []
+        for row in manifest["assets"]:
+            key = (row["platform"], row["arch"])
+            if key not in PLATFORM_TAGS:
+                print(f"skip {row['name']}: no wheel platform for {key}")
+                continue
+            archive = rel_dir / row["name"]
+            if args.tag:
+                fetch(f"{base}/{row['name']}", archive)
+            got = sha256_file(archive)
+            if got != row["sha256"]:
+                raise SystemExit(f"{row['name']}: sha256 {got} != manifest {row['sha256']}")
+            wheel = build_wheel(version, PLATFORM_TAGS[key], payload_members(archive),
+                                readme, args.out)
+            built.append(wheel)
+            print(f"built {wheel.name} ({wheel.stat().st_size} bytes)")
+
+        missing = set(PLATFORM_TAGS) - {(r["platform"], r["arch"]) for r in manifest["assets"]}
+        if missing:
+            raise SystemExit(f"manifest has no payload for {sorted(missing)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/scripts/test_pypi_wheels.py b/tests/scripts/test_pypi_wheels.py
new file mode 100644
index 000000000..89f22f992
--- /dev/null
+++ b/tests/scripts/test_pypi_wheels.py
@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Contract tests for scripts/pypi/build_wheels.py.
+
+Offline: a synthetic release (manifest + four payloads with the real archive
+layout) is built into wheels, and each wheel is read back the way pip reads it.
+"""
+import base64
+import hashlib
+import io
+import json
+import subprocess
+import sys
+import tarfile
+import tempfile
+import unittest
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+BUILDER = ROOT / "scripts" / "pypi" / "build_wheels.py"
+VERSION = "2026.1.2.3"
+
+ROWS = [
+    ("linux", "aarch64", f"mcpp-{VERSION}-linux-aarch64.tar.gz"),
+    ("linux", "x86_64", f"mcpp-{VERSION}-linux-x86_64.tar.gz"),
+    ("macos", "arm64", f"mcpp-{VERSION}-macosx-arm64.tar.gz"),
+    ("windows", "x86_64", f"mcpp-{VERSION}-windows-x86_64.zip"),
+]
+
+
+def make_payload(path: Path) -> None:
+    root = path.name.removesuffix(".tar.gz").removesuffix(".zip")
+    exe = ".exe" if path.name.endswith(".zip") else ""
+    files = {
+        f"{root}/bin/mcpp{exe}": (b"MCPP-" + path.name.encode(), 0o755),
+        f"{root}/registry/bin/xlings{exe}": (b"XLINGS", 0o755),
+        f"{root}/LICENSE": (b"Apache-2.0", 0o644),
+        f"{root}/README.md": (b"readme", 0o644),
+        f"{root}/mcpp": (b"#!/bin/sh\n", 0o755),
+    }
+    if exe:
+        with zipfile.ZipFile(path, "w") as z:
+            for name, (data, _) in files.items():
+                z.writestr(name, data)
+    else:
+        with tarfile.open(path, "w:gz") as t:
+            for name, (data, mode) in files.items():
+                info = tarfile.TarInfo(name)
+                info.size, info.mode = len(data), mode
+                t.addfile(info, io.BytesIO(data))
+
+
+def make_release(d: Path, corrupt: str | None = None) -> None:
+    assets = []
+    for platform, arch, name in ROWS:
+        make_payload(d / name)
+        digest = hashlib.sha256((d / name).read_bytes()).hexdigest()
+        if name == corrupt:
+            digest = "0" * 64
+        assets.append({"platform": platform, "arch": arch, "name": name, "sha256": digest})
+    (d / "mcpp-release.json").write_text(json.dumps(
+        {"schema": 1, "version": VERSION, "tag": f"v{VERSION}", "assets": assets}))
+
+
+def build(rel: Path, out: Path) -> subprocess.CompletedProcess:
+    return subprocess.run([sys.executable, str(BUILDER), "--release-dir", str(rel),
+                           "--out", str(out)], capture_output=True, text=True)
+
+
+class WheelContract(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.rel = Path(self.tmp.name) / "rel"
+        self.out = Path(self.tmp.name) / "dist"
+        self.rel.mkdir()
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_one_wheel_per_manifest_row_with_its_platform_tag(self):
+        make_release(self.rel)
+        r = build(self.rel, self.out)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        tags = sorted(p.name.split("-", 2)[2].removesuffix(".whl") for p in self.out.glob("*.whl"))
+        self.assertEqual(tags, sorted([
+            "py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64",
+            "py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_1_x86_64",
+            "py3-none-macosx_14_0_arm64",
+            "py3-none-win_amd64",
+        ]))
+
+    def test_wheel_contents_record_and_modes(self):
+        make_release(self.rel)
+        self.assertEqual(build(self.rel, self.out).returncode, 0)
+        for whl in self.out.glob("*.whl"):
+            exe = ".exe" if "win_amd64" in whl.name else ""
+            with zipfile.ZipFile(whl) as z:
+                names = set(z.namelist())
+                di = f"mcpp_bin-{VERSION}.dist-info"
+                self.assertEqual(names, {
+                    "mcpp_bin/__init__.py", "mcpp_bin/__main__.py",
+                    f"mcpp_bin/bin/mcpp{exe}", f"mcpp_bin/registry/bin/xlings{exe}",
+                    f"{di}/LICENSE", f"{di}/METADATA", f"{di}/WHEEL",
+                    f"{di}/entry_points.txt", f"{di}/RECORD",
+                }, whl.name)
+                # The payload's bytes, not the bundle's root convenience script.
+                self.assertTrue(z.read(f"mcpp_bin/bin/mcpp{exe}").startswith(b"MCPP-"))
+                mode = z.getinfo(f"mcpp_bin/bin/mcpp{exe}").external_attr >> 16
+                self.assertTrue(mode & 0o111, f"{whl.name}: binary is not executable")
+                self.assertIn("mcpp = mcpp_bin:main", z.read(f"{di}/entry_points.txt").decode())
+                meta = z.read(f"{di}/METADATA").decode()
+                self.assertIn("Name: mcpp-bin\n", meta)
+                self.assertIn(f"Version: {VERSION}\n", meta)
+                for line in z.read(f"{di}/RECORD").decode().splitlines():
+                    name, digest, size = line.split(",")
+                    if name.endswith("RECORD"):
+                        continue
+                    data = z.read(name)
+                    want = "sha256=" + base64.urlsafe_b64encode(
+                        hashlib.sha256(data).digest()).rstrip(b"=").decode()
+                    self.assertEqual((digest, int(size)), (want, len(data)), name)
+
+    def test_payload_whose_hash_disagrees_with_the_manifest_is_refused(self):
+        make_release(self.rel, corrupt=ROWS[1][2])
+        r = build(self.rel, self.out)
+        self.assertNotEqual(r.returncode, 0)
+        self.assertIn("sha256", r.stderr)
+
+    def test_manifest_missing_a_platform_is_refused(self):
+        make_release(self.rel)
+        m = json.loads((self.rel / "mcpp-release.json").read_text())
+        m["assets"] = [a for a in m["assets"] if a["platform"] != "windows"]
+        (self.rel / "mcpp-release.json").write_text(json.dumps(m))
+        r = build(self.rel, self.out)
+        self.assertNotEqual(r.returncode, 0)
+        self.assertIn("windows", r.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()