docs: chapter 00 earns its definition, and the install section recommends one way

Two corrections from review, and both are about what a reader meets first.

CHAPTER 00 IS RESTRUCTURED. It opened with a metadata block -- reader, question,
exclusions -- which is a reference-chapter device and reads as machinery on the
front door. And it stated what mcpp is before saying what problem that answers.

It now runs background -> who pays -> what mcpp is -> the guarantee -> the
smallest example that shows it:

  C++20 gave the language modules, and adopting them turned out to be a
  build-system problem: scan for `import`, order the compiles, cache and
  invalidate the interfaces, with a compiler new enough to have the feature --
  and `import std` needs the standard library's own module built first. The gap
  is concrete: this machine's g++ is 13.3.0 and cannot compile it.

  A person pays an afternoon per machine. An agent pays context, in three places
  before it writes a line: reading the build system, reconstructing the
  environment it assumes, and following a header through its transitive includes
  to find what is declared. Modules remove the third; mcpp removes the other two.

Rule 11 exempts `00` by name, with that reason in the script: it has no "not
here" to declare because everything else IS elsewhere, which its closing
paragraph says in a sentence.

THE INSTALL SECTION FOLLOWS R5. `xlings install mcpp -y` is the recommended way
and is the only one in the body. The standalone curl script and the per-host
default-toolchain table fold into a `<details>` -- they were offered at equal
weight, which asks a first-time reader to choose between two installs before
they have any basis to.

Author: speak-agent

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

@@ -475,7 +475,10 @@ The design failed two of its own rules to get there:
 - **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:
+`00 — What mcpp Is` replaces it, and its shape came from the review too:
+**background → who pays → what mcpp is → the guarantee → the smallest example
+that shows it.** A first chapter earns the definition by first stating the
+problem, and only then shows it solved.
 
 1. **The definition**, in the form the reviewer gave: mcpp = build system +
    build plugins + package manager + toolchain management + the environment and
@@ -508,3 +511,9 @@ 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.
+
+**And the opening block came off.** Every other chapter opens with reader,
+question and exclusions; on the front door that block reads as machinery. `00`
+has no "not here" to declare because everything else *is* elsewhere, which its
+closing paragraph says in a sentence instead. Rule 11 exempts `00` by name, with
+that reason in the script.

.github/tools/check_docs_structure.sh

@@ -211,8 +211,12 @@ PYPARITY
 # half -- they are the gate that stops a chapter re-absorbing a topic another
 # chapter owns. Five of 24 chapters had this before the design; a rule nothing
 # checks is a rule that decays back to five.
+# Chapter 00 is exempt: it is the book's front door, and a metadata block is a
+# reference-chapter device. It has no "not here" to declare, because everything
+# else IS elsewhere -- which is what its closing paragraph says instead.
 for f in docs/[0-9]*.md docs/zh/[0-9]*.md; do
   [ -f "$f" ] || continue
+  case "$(basename "$f")" in 00-*) continue ;; esac
   head -18 "$f" | grep -qE '^\*\*(Reader|读者)' \
     || bad "$f: no designed opening — the first lines must name the reader"
   head -18 "$f" | grep -qE '(question this chapter answers|本章回答的那一个问题)' \

docs/00-what-mcpp-is.md

@@ -1,15 +1,46 @@
 # 00 — What mcpp Is
 
-**Reader:** anyone, before anything else.
+## The background: modules arrived, and the tooling did not
 
-**The question this chapter answers:** what is mcpp, what does it do for a
-project, and what does it cost to try.
+C++20 gave the language modules. They change what a translation unit costs: an
+interface is declared once and imported, instead of being re-parsed out of
+headers by every file that needs it, and what a consumer sees is what the author
+exported rather than everything the header happened to include.
 
-**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.
+Adopting them turned out to be a build-system problem rather than a language
+one. A build has to scan sources for `import`, order the compiles accordingly,
+cache the compiled interfaces and invalidate them correctly — with a compiler
+new enough to have the feature at all. `import std` adds one more: the standard
+library's own module has to be built before anything can use it.
 
-## Five things in one program
+The gap is concrete rather than theoretical. On the machine this chapter was
+written on:
+
+```console
+$ g++ --version
+g++ (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
+```
+
+That compiler cannot compile `import std`. Nothing about the project is wrong;
+the machine is simply not the machine the project needs.
+
+## Who pays for that gap
+
+**A person pays an afternoon**, once per machine and once per new contributor:
+install a newer compiler, work out which build-system flags turn modules on,
+find the dependencies, and then work out which of the three broke when it does
+not link.
+
+**An agent pays context**, in three places before it writes a line of code:
+reading the build system to learn what it does, reconstructing the environment
+it assumes, and following a header through its transitive includes to find out
+what is actually declared.
+
+Modules remove the third — an interface is explicit, and `import` says exactly
+what is used. mcpp exists to remove the other two, and to make the first work
+without the afternoon.
+
+## What mcpp is
 
 ```
 mcpp = build system
@@ -20,9 +51,9 @@ mcpp = build system
 ```
 
 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.
+them are where the afternoon goes: 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.
 
@@ -38,36 +69,30 @@ For a reader who already has tools for these jobs, the parts land roughly here:
 
 **The closest single-tool analogues are Cargo and Zig**, and for different
 halves of the same idea. Cargo is one program that is the build, the packages,
-the lock file and the test runner, so a Rust project is cloned and built without
-a preliminary step — that is the guarantee below, in another language. Zig ships
-its toolchain with the tool and cross-compiles by default, so the compiler is
-not something the machine has to already have — that is the toolchain row.
+the lock file and the test runner, so a Rust project is cloned and built with no
+preliminary step. Zig ships its toolchain with the tool and cross-compiles by
+default, so the compiler is not something the machine must already have.
 
 mcpp is that shape for C++, with one part neither of them has: the environment
 layer, which is why a project can also declare the *non-compiler* tools its
 build needs.
 
 **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.
+depth should use it.
 
 ## 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
+## The smallest example that shows it
 
-Run on a machine whose only C++ compiler is GCC 13, which cannot compile
-`import std`.
+On the same machine, whose only C++ compiler is the GCC 13 above.
 
 ```console
 $ mcpp new hello
@@ -77,14 +102,6 @@ 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"
@@ -93,8 +110,9 @@ 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:
+**No compiler, no language standard and no dependency is declared** — that is
+the whole of what a reader has to understand before changing this project. The
+source uses the feature the machine's compiler does not have:
 
 ```cpp
 import std;
@@ -115,21 +133,16 @@ 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:
+1.25 seconds of wall clock, first run included. The compiler that did it:
 
 ```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.
+colleague — or an agent — cloning this project gets the same compiler rather
+than the one their machine happens to ship.
 
 **A dependency is one line and needs no other step:**
 
@@ -164,3 +177,7 @@ that wants one of them does not leave the tool to get it.
 | 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) |
+
+Everything after this chapter is reference: what a manifest may say, how
+dependencies resolve, how a target is named. This one states no field and no
+flag on purpose.

docs/01-getting-started.md

@@ -14,27 +14,43 @@ than repeats — and every field a manifest may hold, which is
 
 ## Installation
 
-Supported hosts are Linux x86_64 / aarch64, macOS ARM64, and Windows x86_64. You do not need to install GCC, xlings, or any other build dependency beforehand.
-On its first run, mcpp installs a default toolchain into an isolated sandbox (`~/.mcpp/`). The choice is host-aware: Linux x86_64 uses `gcc@16.1.0`; other Linux architectures use `gcc@15.1.0-musl`; macOS uses `llvm@20.1.7`; Windows uses `llvm@20.1.7` when usable MSVC is available and otherwise uses `gcc@16.1.0` for `x86_64-windows-gnu`.
+Supported hosts are Linux x86_64 / aarch64, macOS ARM64, and Windows x86_64.
+GCC, xlings and every other build dependency are installed by mcpp; none of them
+has to be there first.
 
-We recommend installing via [xlings](https://xlings.d2learn.org), which keeps mcpp isolated from your system environment:
+**The recommended way is [xlings](https://xlings.d2learn.org)**, which keeps
+mcpp isolated from the system environment:
 
 ```bash
 xlings install mcpp -y
 ```
 
-Alternatively, on Linux x86_64/aarch64 or macOS ARM64, use the one-line
-installer script (xlings is bundled, and everything is installed under
-`~/.mcpp/`):
+<details>
+<summary>Other ways: the standalone script, and what the first run installs</summary>
+
+On Linux x86_64/aarch64 or macOS ARM64 a one-line installer bundles xlings and
+puts everything under `~/.mcpp/`. It does not support Windows, where the
+PowerShell xlings command in the README is the way in.
 
 ```bash
 curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
 ```
 
-The script does not support Windows; install through the PowerShell xlings
-command in the README instead.
+On its first run mcpp installs a default toolchain into `~/.mcpp/`, chosen for
+the host:
+
+| host | default |
+|---|---|
+| Linux x86_64 | `gcc@16.1.0` |
+| other Linux architectures | `gcc@15.1.0-musl` |
+| macOS | `llvm@20.1.7` |
+| Windows with usable MSVC | `llvm@20.1.7` |
+| Windows without it | `gcc@16.1.0` for `x86_64-windows-gnu` |
+
+Full installation instructions, including Windows, are in the
+["Installation" section of the README](../README.md#install).
 
-For full installation instructions (including xlings install commands, Windows support, and more), see the ["Installation" section of the README](../README.md#install).
+</details>
 
 Once installation is complete, start a new shell session, then verify: