docs: a scenario chapter, a lookup index, and the rules that make a book also a reference

Three things the reader-facing side was missing, and the rules for each are in
the style skill so they outlive this batch.

02 — SCENARIOS. The tree had an index by example (03) and an index by command
(09) and none by the work in front of a developer. Nine scenarios -- a CLI tool,
a library, a workspace, a graphical application, cross-compiling, bare metal,
GPU compute, graphics, a build step -- each stating the situation, what mcpp
contributes to it, the path through the chapters, one project to run, and the
one thing that surprises people. Every scenario is backed by a runnable project
or a published template; a path with nothing to run is a claim rather than a
scenario, and the chapter says so.

A LOOKUP INDEX. The chapter list is a reading order and cannot answer "I have
`[feature-deps]` in front of me". docs/README.md gains the other index: manifest
tables and keys, commands, and concepts, each to the chapter that owns it. The
two properties -- a book that is read in order and a reference that is looked
up -- are carried by two indexes rather than by one table pretending to do both.

THE RULES. R7: an advantage is shown by the artifact, not by an adjective --
six lines of manifest, `Finished dev in 0.06s`, `counters` 0 times without the
feature and 2 with it. The criterion is that deleting every adjective leaves the
advantage visible. R8: a complex feature is introduced as shortest-runnable →
common shape → full surface → edges, one axis at a time; the criterion is how
many screens before the reader has something running. Plus the two-index rule
above. The review rubric is fourteen dimensions now.

Author: speak-agent

.agents/skills/mcpp-docs-style/SKILL.md

@@ -362,6 +362,59 @@ mcpp 在很多场景支持不止一种做法,但它有自己的设计风格与
 (`2026.9.6.5+`),不写在章节顶部,也不写成「从前是 X,后来变成 Y」的叙述 ——
 后者是设计记录的句子(第一节)。
 
+### 书与工具书:两种属性,两种索引
+
+一套文档同时要能被**从头读**和被**反查**。这两件事不能由同一张表兼任 —— 一张按
+阅读顺序排的目录,回答不了「我手上有 `[feature-deps]`,该看哪一章」;一张按字母排
+的索引,读者从头读会不知道先读哪个。
+
+所以是两种索引,各司其职:
+
+| 属性 | 承担它的东西 | 判据 |
+|---|---|---|
+| **书** | 章节的段位与部分内顺序(第九节的梯度) | 一个从头读的人不需要跳级 |
+| **工具书** | **反查索引**:manifest 键 / 命令 / 概念 → 章节;以及每章开头的「不在这里」 | 一个拿着一个记号来的人,一步到位 |
+
+反查索引的**分母取自代码树**(第十节):参考章节里出现的每一个键,反查表里都要有
+一行。少一行,读者就会认为那个键没有文档。
+
+### 优势由产物自己说明,不靠形容词
+
+用户文档与示例要让读者**明显感到** mcpp 的长处,而做到这一点的方式不是形容词。
+「简洁」「好用」「强大」本身不携带信息,读者读到的是一个主张。
+
+写成可验证的三样东西之一:
+
+| 不采用 | 采用 |
+|---|---|
+| 打包非常简单 | 六行 manifest,一条 `mcpp pack`,产出一个静态二进制 |
+| 增量构建很快 | `Finished dev in 0.06s` |
+| 不带加速器时开销很小 | 不点名加速器的构建**一个字节都不下载** |
+| 依赖是可选的 | `counters` 不带 feature 出现 **0 次**,带 feature **2 次** |
+
+**判据:把所有形容词删掉,读者还能不能看出优势?** 能 → 对。删掉之后只剩机制
+描述 → 那份「感受」本来就只在形容词里。
+
+**不要在用户文档里与别的工具比较。** 对照属于设计记录(第一节)。用户文档展示的是
+**这一件事在这里要写多少、跑出什么**,读者自己会比较。
+
+### 渐进式叙事:最短可跑 → 常见形状 → 完整表面 → 边角
+
+复杂或小众的特性不从机制讲起。四段,顺序固定:
+
+| 段 | 内容 | 读者在这一段结束时 |
+|---|---|---|
+| 最短可跑 | 能跑的最小形态,连同它的真实输出 | 手上有一个跑起来的东西 |
+| 常见形状 | 绝大多数工程实际会写的那一种 | 能照着改成自己的 |
+| 完整表面 | 字段、旗标、取值 | 查得到 |
+| 边角 | 平台差异、限制、失败形态 | 知道什么时候会撞墙 |
+
+**判据:读者读到第几屏时手上有一个能跑的东西?** 第一屏之后还没有,就是把机制讲在
+了可跑之前。
+
+一次只加一条轴。`examples/09-heterogeneous/boundary` 是这条规则的形状:它先只讲
+边界(不需要设备),`cuda` 再加设备编译器,`multi-backend` 再加第二个后端。
+
 ### 两个视角都要设计
 
 - **全局**:入口的角色索引、部分的划分、编号所在的段位、章节之间的顺序。
@@ -414,6 +467,9 @@ bash .github/tools/check_docs_style.sh
 | **一条推荐路径** | 只读正文、不展开任何 `<details>`,读者能不能不做选择就把事情做对(第十二节) |
 | **增量标注** | 每个后加的键/旗标/行为,版本下界写在它自己旁边,而不是章节顶部或历史叙述 |
 | **章节规格** | 第二节那张表能不能填满 —— 读者、那一个问题、包含、排除、位置与理由、前后、判据 |
+| **冲击力** | 把形容词删掉,优势还看得出来吗 —— 有没有最短可跑的产物、真实输出、可数的数字 |
+| **渐进性(局部)** | 读者读到第几屏手上有一个能跑的东西;是不是一次只加一条轴 |
+| **可查阅** | 拿着一个 manifest 键 / 命令 / 概念,能不能一步查到章节;反查索引有没有漏行 |
 
 **用户文档额外一条,优先级高于以上八条**:逐段问「删掉它读者还能不能正确地用」
 (第一节)。设计理由、被否掉的替代、路线图,一律不在用户文档里。
@@ -433,6 +489,8 @@ bash .github/tools/check_docs_style.sh
 [ ] 「当前边界」是事实清单,不是说理
 [ ] 有多种做法时,正文只写推荐那一条,其余在 `<details>` 里
 [ ] 后加的键/旗标带版本下界,且标在它自己旁边
+[ ] 优势由最短可跑产物 / 真实输出 / 数字说明,不由形容词说明
+[ ] 复杂特性按「最短可跑 → 常见形状 → 完整表面 → 边角」推进
 [ ] 第二节的章节规格七格都能填出来
 [ ] 没有 docs/** → .agents/** 的引用
 [ ] 开头点明了它在梯度里的哪一级,且只链接相邻级

.github/tools/check_docs_style.sh

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

CHANGELOG.md

@@ -596,7 +596,7 @@ e2e 616 是双向的,而单向的那一半不值得跑:「列出的路径都存
 通过,「盘上的示例都被列出」在一份把一半链接指错地方的文档上通过。两条合起来才是那条性质。
 
 它当场抓到一个既有缺口:`examples/04-workspace`、`05-lib-distribution`、
-`06-openkal-cross`、`07-project-subos` 都在盘上,而中英两份 `docs/02-examples.md`
+`06-openkal-cross`、`07-project-subos` 都在盘上,而中英两份 `docs/03-examples.md`
 一个都没列。现在列上了。
 
 这是结构判据,它自己也这么说:它不构建任何东西,所以回答不了「这个示例还能不能跑」。
@@ -4317,7 +4317,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 ### 文档
 
-- `docs/03-mcpp-toml.md` 的示例此前写的是 `import mcpp.rules.protobuf;`,**做不到**:mcpp 用依赖的裸 `package.name` 注册 host 模块,而 SPEC-001 要求 `name` 是单一原子段。随之澄清一条会咬人的约束:规则包的名字必须是**合法 C++ 模块名**(`grpcgen` 可以,`grpc-rules` 不行),否则报的是 `module 'grpc_rules' not found`,不会提示你名字有问题。
+- `docs/04-mcpp-toml.md` 的示例此前写的是 `import mcpp.rules.protobuf;`,**做不到**:mcpp 用依赖的裸 `package.name` 注册 host 模块,而 SPEC-001 要求 `name` 是单一原子段。随之澄清一条会咬人的约束:规则包的名字必须是**合法 C++ 模块名**(`grpcgen` 可以,`grpc-rules` 不行),否则报的是 `module 'grpc_rules' not found`,不会提示你名字有问题。
 
 ## [2026.8.5.1] — 2026-08-05
 
@@ -4516,7 +4516,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 ### 修复
 
-- **`[build] static_stdlib = false` 对测试二进制静默失效(#336)。** #124 在 0.0.52 明确写下这个 opt-out,`docs/03-mcpp-toml.md` 至今也还这么写;但 #202(0.0.86)把测试二进制改成与分发目标相同的静态 `-load_hidden` libc++ 时,新增的那条推导**没有带上 `staticStdlib` 门**。结果是约一年时间里 macOS 上的 `mcpp test` 没有任何办法回到动态 libc++,而文档一直在承诺它可以。
+- **`[build] static_stdlib = false` 对测试二进制静默失效(#336)。** #124 在 0.0.52 明确写下这个 opt-out,`docs/04-mcpp-toml.md` 至今也还这么写;但 #202(0.0.86)把测试二进制改成与分发目标相同的静态 `-load_hidden` libc++ 时,新增的那条推导**没有带上 `staticStdlib` 门**。结果是约一年时间里 macOS 上的 `mcpp test` 没有任何办法回到动态 libc++,而文档一直在承诺它可以。
 
 - **macOS 上全局对象在静态初始化期访问 `std::cout` 必崩(#336)。** Mach-O 没有按优先级排序的初始化段(`init_priority` 只在单个 TU 内有效),归档成员的初始化器按链接顺序排在最后;而 libc++ 的 `<iostream>` 不像 libstdc++ / MSVC STL 那样自带 `ios_base::Init` 守卫,流的构造只存在于库内对象里。两件事叠起来的后果是:默认配置下,任何在构造函数里碰 `std::cout` 的全局对象都会读到 vptr 为零的流,进程启动即 SIGSEGV —— 而且**包侧无法修复**,因为 `std::ios_base::Init` 在 libc++ 的头文件里只有前向声明(`ios:70`),标准为静态初始化次序提供的官方解药在 libc++ 上用户根本写不出来。
 
@@ -4550,7 +4550,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 ### 修复
 
-- **`--offline` 不再拒绝本地 git 远端。** `docs/03-mcpp-toml.md` 写明 `--offline` 的语义是「完全不碰网络……已安装的东西照常构建」,`prepare.cppm` 里依赖下载闸的注释也把线画在同一处:「这条线以上全是本地操作,一个依赖齐备的离线构建必须成功」。但 `git = "../sibling-repo"` 这种指向本地目录的远端,`ls-remote`/`clone` 都只是文件系统读取,拒绝它买不到任何隔离性。现在按远端形态判定——`file://`、以及不带 scheme 也不是 `git@host:path` 的存在路径,算本地(Windows 盘符 `C:\repo` 含冒号但不含 `@`,因此仍归本地)。
+- **`--offline` 不再拒绝本地 git 远端。** `docs/04-mcpp-toml.md` 写明 `--offline` 的语义是「完全不碰网络……已安装的东西照常构建」,`prepare.cppm` 里依赖下载闸的注释也把线画在同一处:「这条线以上全是本地操作,一个依赖齐备的离线构建必须成功」。但 `git = "../sibling-repo"` 这种指向本地目录的远端,`ls-remote`/`clone` 都只是文件系统读取,拒绝它买不到任何隔离性。现在按远端形态判定——`file://`、以及不带 scheme 也不是 `git@host:path` 的存在路径,算本地(Windows 盘符 `C:\repo` 含冒号但不含 `@`,因此仍归本地)。
 
 - **克隆被中途杀掉后不再永久提供错误的 commit。** 缓存目录以 commit 命名,但内容是 `git clone` 之后再 `git checkout` 两步做出来的;进程死在两步之间,目录名和 HEAD 就对不上了,而后续构建只检查目录存不存在。现在分支依赖会比对 `git rev-parse HEAD`,不符即删除重克隆(tag/rev 以 ref 名为身份,无可比之物)。
 
@@ -4633,7 +4633,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
   **最危险的一条判据**(`SuppressedInconclusive`):「本地查不到」单独不能推出「需要刷新」。xim 描述符不写 `namespace`,`(xim, x)` 永远匹配不上身份门 —— 把这种 miss 当真,任何带 xim 依赖的工程会**每次构建都刷**,比被删掉的 TTL 更糟。判据复用 `IndexRoute::authoritative_for`(#307),单测 + e2e 双闸锁住。
 
-  语义变化:`^1.2` 对**本地索引已知的版本**求解。上游新发的 1.3.0 需要 `mcpp index update` 或 `mcpp update` 才可见 —— 这正是那两个命令存在的意义,已写进 `docs/03-mcpp-toml.md`。
+  语义变化:`^1.2` 对**本地索引已知的版本**求解。上游新发的 1.3.0 需要 `mcpp index update` 或 `mcpp update` 才可见 —— 这正是那两个命令存在的意义,已写进 `docs/04-mcpp-toml.md`。
 
 - **`mcpp update` 不再是空操作。** 它此前只删 mcpp.lock 条目、然后叫用户去跑 `mcpp build` —— 而构建路径**从不读 mcpp.lock**(`prepare` 只写不读),所以删了等于没删,行为影响为零。它现在先强制刷新索引(显式意图 ⇒ 不看 TTL、不看去抖),并报告索引 rev 的变化;工程里没有任何走共享 registry 的依赖时跳过(刷了也没用)。
 
@@ -5629,7 +5629,7 @@ xlings 作为运行时底座:subos 环境到达程序,以及 self-contained 的
 
 - `[targets.<name>]` 下的不支持键不再被静默丢弃,而是产生 warning(`--strict` 下为 error),
   并指引到正确的机制(workspace / features / profile)。
-- 文档 `docs/03-mcpp-toml.md`(及 `docs/zh`)新增"构建配置该放哪"的决策指引。
+- 文档 `docs/04-mcpp-toml.md`(及 `docs/zh`)新增"构建配置该放哪"的决策指引。
   设计记录见 `.agents/docs/2026-06-18-per-target-build-config-design.md`。
 
 ## [0.0.54] — 2026-06-10

README.md

@@ -9,7 +9,7 @@
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
 
-| [Documentation](docs/) · [Getting Started](docs/01-getting-started.md) · [mcpp.toml Guide](docs/03-mcpp-toml.md) · [Examples](docs/02-examples.md) · [Toolchains](docs/20-toolchains.md) |
+| [Documentation](docs/) · [Getting Started](docs/01-getting-started.md) · [mcpp.toml Guide](docs/04-mcpp-toml.md) · [Examples](docs/03-examples.md) · [Toolchains](docs/20-toolchains.md) |
 |:---:|
 | [Package index mcpp-index](https://mcpplibs.github.io/mcpp-index/) · [Module libraries mcpplibs](https://github.com/mcpplibs) · [Community Forum](https://forum.d2learn.org/category/20) · [Issues](https://github.com/mcpp-community/mcpp/issues) · [Releases](https://github.com/mcpp-community/mcpp/releases) |
 | [![ci-linux](https://github.com/mcpp-community/mcpp/actions/workflows/ci-linux.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp/actions/workflows/ci-linux.yml) [![ci-macos](https://github.com/mcpp-community/mcpp/actions/workflows/ci-macos.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp/actions/workflows/ci-macos.yml) [![ci-windows](https://github.com/mcpp-community/mcpp/actions/workflows/ci-windows.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp/actions/workflows/ci-windows.yml) |
@@ -224,7 +224,7 @@ Then `import` it directly in your code:
 import mcpplibs.cmdline;
 ```
 
-> For more dependency options (version constraints, namespaces, Git references, local paths, etc.), see the [mcpp.toml guide — dependency management](docs/03-mcpp-toml.md).
+> For more dependency options (version constraints, namespaces, Git references, local paths, etc.), see the [mcpp.toml guide — dependency management](docs/04-mcpp-toml.md).
 
 ## Feature Overview
 
@@ -418,12 +418,12 @@ verified — CI builds **and executes** the artifact end-to-end (qemu/wine inclu
 ## Documentation
 
 - [Getting Started](docs/01-getting-started.md) — install → new → build → run in 5 minutes
-- [Examples](docs/02-examples.md)
+- [Examples](docs/03-examples.md)
 - [Packaging & Release](docs/10-pack-and-release.md)
 - [Toolchain Management](docs/20-toolchains.md)
 - [Building from Source](docs/90-build-from-source.md)
-- [mcpp.toml Guide](docs/03-mcpp-toml.md)
-- [Workspaces](docs/06-workspace.md)
+- [mcpp.toml Guide](docs/04-mcpp-toml.md)
+- [Workspaces](docs/07-workspace.md)
 
 Full options for any command are available via `mcpp <cmd> --help`.
 

README.zh-CN.md

@@ -9,7 +9,7 @@
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
 
-| [文档](docs/zh/) · [快速开始](docs/zh/01-getting-started.md) · [mcpp.toml 指南](docs/zh/03-mcpp-toml.md) · [示例项目](docs/zh/02-examples.md) · [工具链管理](docs/zh/20-toolchains.md) |
+| [文档](docs/zh/) · [快速开始](docs/zh/01-getting-started.md) · [mcpp.toml 指南](docs/zh/04-mcpp-toml.md) · [示例项目](docs/zh/03-examples.md) · [工具链管理](docs/zh/20-toolchains.md) |
 |:---:|
 | [包索引 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) |
@@ -221,7 +221,7 @@ cmdline = "0.0.2"
 import mcpplibs.cmdline;
 ```
 
-> 更多依赖配置方式（版本约束、命名空间、Git 引用、本地路径等）参见 [mcpp.toml 指南 — 依赖管理](docs/zh/03-mcpp-toml.md)。
+> 更多依赖配置方式（版本约束、命名空间、Git 引用、本地路径等）参见 [mcpp.toml 指南 — 依赖管理](docs/zh/04-mcpp-toml.md)。
 
 ## 功能概览
 
@@ -388,12 +388,12 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family 
 ## 文档
 
 - [快速开始](docs/zh/01-getting-started.md) — 5 分钟完成 install → new → build → run
-- [示例项目](docs/zh/02-examples.md)
+- [示例项目](docs/zh/03-examples.md)
 - [发布打包](docs/zh/10-pack-and-release.md)
 - [工具链管理](docs/zh/20-toolchains.md)
 - [从源码构建](docs/zh/90-build-from-source.md)
-- [mcpp.toml 指南](docs/zh/03-mcpp-toml.md)
-- [工作空间](docs/zh/06-workspace.md)
+- [mcpp.toml 指南](docs/zh/04-mcpp-toml.md)
+- [工作空间](docs/zh/07-workspace.md)
 
 任意命令的完整选项可通过 `mcpp <cmd> --help` 查阅。
 

docs/00-how-mcpp-works.md

@@ -31,7 +31,7 @@ its directory, and not its file name — which is why two packages called
 A package is also the unit of everything else: the unit that is published, that
 is cached, that declares features, and that a build program belongs to.
 
-Reference: [03 — The mcpp.toml Manifest](03-mcpp-toml.md).
+Reference: [04 — The mcpp.toml Manifest](04-mcpp-toml.md).
 
 ### graph
 
@@ -123,7 +123,7 @@ noun names the chapter.
 
 | a message about | the noun | where to look |
 |---|---|---|
-| a package name, a version, or "no candidate" | index | [11](11-publishing-a-library.md), [04](04-dependencies.md) |
+| a package name, a version, or "no candidate" | index | [11](11-publishing-a-library.md), [05](05-dependencies.md) |
 | a download, a payload, or a version floor | toolchain | [20](20-toolchains.md), [23](23-the-project-environment.md) |
 | a triple, or "unsupported target" | target | [21](21-the-target-triple.md) |
 | a module that cannot be read or is not provided | graph | [30](30-build-mcpp.md) |

docs/01-getting-started.md

@@ -8,7 +8,7 @@ running, from an empty machine.
 **Not here:** what mcpp's parts are — that is
 [00 — How mcpp Works](00-how-mcpp-works.md), which this chapter assumes rather
 than repeats — and every field a manifest may hold, which is
-[03 — The mcpp.toml Manifest](03-mcpp-toml.md). After: [02 — Examples](02-examples.md).
+[04 — The mcpp.toml Manifest](04-mcpp-toml.md). After: [03 — Examples](03-examples.md).
 
 > Go from install → new → build → run → pack in 5 minutes.
 
@@ -178,7 +178,7 @@ Declare dependencies in `mcpp.toml`:
 `mcpp build` automatically resolves SemVer constraints against the
 [mcpp-index](https://github.com/mcpplibs/mcpp-index), fetches the source,
 and adds it to the build graph. For a complete example, see `02-with-deps` in
-[02 — Examples](02-examples.md).
+[03 — Examples](03-examples.md).
 
 ## Producing a Release Package
 
@@ -195,7 +195,7 @@ For the differences between the four modes and their artifact layouts, see [10 
 
 ## Further Reading
 
-- [02 — Examples](02-examples.md) — a collection of ready-to-run minimal projects
+- [03 — Examples](03-examples.md) — a collection of ready-to-run minimal projects
 - [10 — Packaging and Release](10-pack-and-release.md) — building distributable artifacts
 - [20 — Toolchain Management](20-toolchains.md) — switching compilers and managing multiple versions
 - The full set of options for any command is available via `mcpp <cmd> --help`