docs: chapter 00 is what mcpp is, not how it works

The review's verdict on the previous 00 was that it scored zero, and it was
right. `How mcpp Works` was accurate and was the wrong chapter: a general user
does not care about the operating principle. It failed two of the design's own
rules -- R2, because "understand the machinery" is a maintainer's task and
already has chapters in 9x; and R7, because a model chapter explains how an
advantage is produced and never demonstrates it.

`00 — What mcpp Is` replaces it with what a first reader actually wants:

  the definition   mcpp = build system + build plugins + package manager +
                   toolchain management + the environment and runtime (xlings)

  an analogy       CMake, xmake rules, Conan, GCC/LLVM/MSVC, Nix/conda -- so a
                   reader with existing tools can place each part, with the
                   disclaimer that places rather than equates

  the guarantee    clone any mcpp project and `mcpp build` works, without
                   installing a compiler, configuring an environment or hunting
                   dependencies -- and the two boundaries that make it credible

  a real session   a five-line manifest with no compiler and no standard
                   declared, `import std` compiling on a machine whose own g++
                   is 13.3.0 and cannot, `mcpp self env` showing the GCC 16 mcpp
                   installed, 1.25s wall clock including the first run

  what it is for   modules and the newest features, and the ecosystems that
                   follow: embedded, heterogeneous and GPU, graphics, kernel

The one part of the old chapter a user wanted -- the table from a message's
shape to the stage that produced it -- moves to 09 beside the other diagnosis
scenarios. The rest is deleted.

The style skill gains the distinction this needed: an ANALOGY places a part
against a tool the reader knows and is admissible in user documentation; a
COMPARISON claims mcpp is better on some axis and belongs to a design record.
An analogy carries a disclaimer, or the placement is read as equivalence.

Author: speak-agent

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

@@ -455,3 +455,51 @@ preference**, and that is the sentence a reader of scenario 10 leaves with.
 31 now, and the reason is that the tool is four things rather than three: a
 build system, a package manager, a toolchain provisioner, **and an ecosystem
 other people publish into**. The fourth had no chapters at all.
+
+---
+
+## 13. Chapter 00 was designed wrong, and the review said so
+
+§4.1 specified `00 — How mcpp Works`: five nouns, three seams, where state lives
+on disk. It was written, it was accurate, and it was the wrong chapter.
+
+**The review's verdict was that a general user does not care about the operating
+principle.** What a reader opening the first chapter wants is what mcpp is, what
+it can do, what its advantage is, and one example they can actually run.
+
+The design failed two of its own rules to get there:
+
+- **R2** — a chapter exists for a reader with a task. "Understand the machinery"
+  is not a task a first-time reader has; it is a task a maintainer has, and it
+  already has chapters in `9x`.
+- **R7** — an advantage is shown by the artifact, not by the mechanism. A model
+  chapter explains how the advantage is produced and never demonstrates it.
+
+`00 — What mcpp Is` replaces it:
+
+1. **The definition**, in the form the reviewer gave: mcpp = build system +
+   build plugins + package manager + toolchain management + the environment and
+   runtime (xlings), in one program.
+2. **An analogy table** — CMake, xmake rules, Conan, GCC/LLVM/MSVC, Nix/conda —
+   so a reader with existing tools can place each part. With the disclaimer that
+   places rather than equates.
+3. **The guarantee, stated once**: clone any mcpp project and `mcpp build`
+   works, without installing a compiler, configuring an environment, or hunting
+   dependencies. Plus the two boundaries that make it trustworthy.
+4. **A session that was run**, with its real output: a five-line manifest, no
+   declared compiler or standard, `import std` compiling on a machine whose own
+   `g++` is 13.3.0 and cannot, and `mcpp self env` showing the GCC 16 mcpp
+   installed. 1.25 s of wall clock including the first run.
+5. **What mcpp is for**: modules and the newest language features, and the
+   ecosystems that follow — embedded, heterogeneous and GPU, graphics, kernel
+   work.
+
+The one part of the old chapter a *user* wanted — the table from a message's
+shape to the stage that produced it — moved to `09`, beside the other
+diagnosis scenarios. The rest is deleted rather than relocated.
+
+**What this says about the method.** The seven-cell spec was filled for the old
+chapter and it still produced the wrong chapter, because the cell that decides
+everything — the reader — was answered with "anyone" and then served as if that
+meant "someone who wants the model". A reader cell that names no task is not
+filled in.

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

@@ -408,8 +408,18 @@ mcpp 在很多场景支持不止一种做法,但它有自己的设计风格与
 **判据:把所有形容词删掉,读者还能不能看出优势?** 能 → 对。删掉之后只剩机制
 描述 → 那份「感受」本来就只在形容词里。
 
-**不要在用户文档里与别的工具比较。** 对照属于设计记录(第一节)。用户文档展示的是
-**这一件事在这里要写多少、跑出什么**,读者自己会比较。
+**类比可以,对照不可以 —— 两者的区别是它服务谁。**
+
+| | 目的 | 归属 |
+|---|---|---|
+| **类比** | 让读者把新概念挂到已有认知上 | 用户文档,**可以** |
+| **对照** | 主张 mcpp 在某个维度上更好 | 设计记录,用户文档**不可以** |
+
+「工具链管理大致相当于 rustup 在 Rust 里的角色」是类比 —— 它给一个部分定位,不作
+评价。「比 CMake 简洁」是对照 —— 它是一个主张,而用户文档不是提出主张的地方。
+
+类比要**带一句免责**:上面每个工具在它自己的领域里做的都比 mcpp 多。少了这一句,
+定位会被读成等价。
 
 ### 渐进式叙事:最短可跑 → 常见形状 → 完整表面 → 边角
 

docs/00-how-mcpp-works.md

@@ -0,0 +1,155 @@
+# 00 — What mcpp Is
+
+**Reader:** anyone, before anything else.
+
+**The question this chapter answers:** what is mcpp, what does it do for a
+project, and what does it cost to try.
+
+**Not here:** how any of it works internally, and every field and flag. This
+chapter ends with a session that has been run; the chapters after it are the
+reference.
+
+## Five things in one program
+
+```
+mcpp = build system
+     + build plugins
+     + package manager
+     + toolchain management
+     + the environment and runtime (xlings)
+```
+
+Most C++ projects assemble those five from separate tools, and the seams between
+them are where a new contributor loses an afternoon: the build file assumes a
+compiler the machine does not have, the package manager assumes a build file it
+did not write, and the environment is a paragraph in a README.
+
+mcpp is one program, so there are no seams to assemble.
+
+For a reader who already has tools for these jobs, the parts land roughly here:
+
+| the part | in mcpp | roughly the job of |
+|---|---|---|
+| build system | `mcpp.toml`, the module graph, the ninja backend | CMake, Meson |
+| build plugins | `build.mcpp`, rule packages | xmake rules |
+| package manager | `[dependencies]`, `mcpp.lock`, the index | Conan, vcpkg |
+| toolchain management | the compiler as an installed, pinned payload | installing GCC / LLVM / MSVC by hand, or rustup's role in Rust |
+| environment and runtime | `[xlings]`, payloads, the runtime search path | Nix, conda |
+
+**The table places the parts; it does not claim equivalence.** Each of those
+tools does more in its own area than mcpp does, and a project that needs that
+depth should use it. What the row is saying is which familiar job the part
+corresponds to, so the rest of this documentation has somewhere to attach.
+
+## The guarantee
+
+> **Clone any mcpp project and `mcpp build` works** — without installing a
+> compiler, configuring an environment, or hunting down dependencies.
+
+That is the whole claim, and everything below is it being demonstrated rather
+than repeated.
+
+Two boundaries, stated here so the claim can be trusted: a project that targets
+a device still downloads that device's toolkit the first time, and a target this
+machine cannot serve is refused by name rather than built wrongly.
+
+## A first session, end to end
+
+Run on a machine whose only C++ compiler is GCC 13, which cannot compile
+`import std`.
+
+```console
+$ mcpp new hello
+Created bin package 'hello' at /tmp/zero-demo/hello
+Next: cd hello && mcpp build && mcpp run  (or `mcpp test`)
+```
+
+Four files, and the manifest is five lines:
+
+```
+hello/
+├── mcpp.toml
+├── src/main.cpp
+├── tests/test_smoke.cpp
+└── .gitignore
+```
+
+```toml
+[package]
+name        = "hello"
+version     = "0.1.0"
+description = "A modular C++23 package"
+license     = "Apache-2.0"
+```
+
+**No compiler, no language standard and no dependency is declared**, and the
+source uses a feature the machine's own compiler does not have:
+
+```cpp
+import std;
+
+int main() {
+    std::println("Hello from hello!");
+}
+```
+
+```console
+$ mcpp run
+    Inferred target hello (bin from src/main.cpp)
+   Compiling hello v0.1.0 (.)
+    Finished dev [unoptimized + debuginfo] in 0.64s
+     Running `target/x86_64-linux-gnu/0946988e9e4b52ba/bin/hello`
+
+Hello from hello!
+Built with import std + std::println on modular C++23.
+```
+
+1.25 seconds of wall clock, first run included.
+
+The compiler that did it is not the one on the machine:
+
+```console
+$ g++ --version
+g++ (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
+
+$ mcpp self env
+default toolchain   = gcc@16.1.0
+```
+
+mcpp installed GCC 16 and used it. Nothing on the host was changed, and a
+colleague who clones this project gets the same compiler rather than the one
+their distribution happens to ship.
+
+**A dependency is one line and needs no other step:**
+
+```toml
+[dependencies]
+"mcpplibs.cmdline" = "^0.0.1"
+```
+
+`mcpp build` resolves it, fetches it, builds it and links it.
+
+## What mcpp is for
+
+mcpp is built around **C++20/23 modules and the newest language features**, and
+the ecosystem it maintains follows from that rather than from a general
+ambition:
+
+| | |
+|---|---|
+| modular C++ | `import std` with no configuration, module scanning, a cross-project BMI cache |
+| embedded and bare metal | freestanding targets, board-support packages, one command from source to a running image |
+| heterogeneous computing and GPUs | CUDA, HIP, SYCL, Vulkan/SPIR-V and Ascend C, each a rule package rather than an engine feature |
+| graphics | shaders compiled as part of the build and reached as modules |
+| kernel and low-level work | zero-libc tiers, an explicit link model, no hidden host dependency |
+
+A project that wants none of those still gets the guarantee above; a project
+that wants one of them does not leave the tool to get it.
+
+## Where to go next
+
+| | |
+|---|---|
+| put a program on the screen | [01 — Getting Started](01-getting-started.md) |
+| decide whether mcpp fits the work at hand | [02 — Scenarios](02-scenarios.md) |
+| read a project of the same shape | [03 — Examples](03-examples.md) |

docs/00-what-mcpp-is.md

@@ -6,7 +6,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
+[00 — What mcpp Is](00-what-mcpp-is.md), which this chapter assumes rather
 than repeats — and every field a manifest may hold, which is
 [04 — The mcpp.toml Manifest](04-mcpp-toml.md). After: [03 — Examples](03-examples.md).
 

docs/01-getting-started.md

@@ -41,7 +41,7 @@ command produces a binary that carries what it needs.
 
 **The path.**
 
-1. [00 — How mcpp Works](00-how-mcpp-works.md) — the five nouns.
+1. [00 — What mcpp Is](00-what-mcpp-is.md) — the five nouns.
 2. [01 — Getting Started](01-getting-started.md) — a program on the screen.
 3. [05 — Dependencies and Resolution](05-dependencies.md) — `[dependencies]`,
    the lock file.