@@ -33,9 +33,9 @@ still use what other languages have already built.
 
 ## Features
 
-- **Small and quick to start** — one static binary of about 7.8 MB with the
-  Wasm JIT engine included (for scale: babashka's native binary is ~71 MB;
-  [measured comparison](docs/works/binary_size.md)), starting in ~5 ms, which
+- **Small and quick to start** — one static binary of about 7.4 MB with the
+  Wasm JIT engine included (for scale: babashka's native binary is ~71 MB <!--size:other-->;
+  [measured comparison](docs/works/binary_size.md)), starting in ~6 ms, which
   suits short-lived, start-and-stop workloads (CLI tools, serverless, scripts).
 - **A lot of everyday Clojure runs** — `clojure.core` plus a growing set of
   standard-library namespaces (`clojure.string` / `set` / `walk` / `zip` /
 
@@ -13,38 +13,56 @@ bash bench/release_metrics.sh
 
 ## Locked figure
 
-| Build (`-Dwasm` — the SHIPPED config, embedded zwasm JIT engine included) | On-disk (build-stripped)      | CLI-strip floor |
-|---------------------------------------------------------------------------|-------------------------------|------------------|
-| **ReleaseSafe** — the release build                                      | **6.97 MB** (6,974,584 bytes) | 7.01 MB (CLI strip is a no-op here) |
-| ReleaseSmall — the size floor (safety checks off; NOT shipped)           | 3.55 MB (3,547,336 bytes)     | 3.21 MB (3,213,360 bytes) |
-
-Measured with Zig 0.16.0 for `aarch64-macos` (re-measured **2026-07-16**, after
-the ADR-0172 binary-size campaign: 9,469,816 → 6,974,584 bytes, −26.3% in one
-campaign — unwind-table strip O-052, envelope-v7 constant pool + flate
-regions/sources ADR-0173, zwasm v2.2.1 thunk collapse, sort dedup O-053; the
-per-component budget + `size_claims` gate now govern growth). The pre-campaign
-2026-06-11 row (no `-Dwasm`, 3.24 MB) predates the always-embedded Wasm engine
-and is superseded — the `-Dwasm` build IS the artifact users download. **As of
-O-008, `build.zig` strips the symbol table from every non-Debug build**
+There is exactly **one** shipped configuration, and it is the one users
+download: `-Dwasm -Doptimize=ReleaseSafe`, with the zwasm JIT engine embedded.
+
+| Build                                                               | On-disk (build-stripped)      |
+|---------------------------------------------------------------------|-------------------------------|
+| **ReleaseSafe `-Dwasm`** — the release build, the shipped artifact | **7.37 MB** (7,368,808 bytes) |
+
+Measured with Zig 0.16.0 for `aarch64-macos`, re-measured **2026-08-04**.
+
+Every `<N> MB` figure in this file, in `README.md`, and in `docs/landscape.md`
+is checked against the freshly built binary by the `size_claims` gate
+(`scripts/binary_size_report.sh --check`, wired into `test/run_all.sh`). A
+figure that is deliberately *not* the shipped size carries an inline
+`<!--size:other-->` marker so the exemption is explicit rather than silent.
+This is the structural answer to the rot this file itself carried until
+2026-08-04, when the table said 6,974,584 bytes while the prose two paragraphs
+below still quoted 3,240,000 and 3,820,664 from a pre-campaign build.
+
+**As of O-008, `build.zig` strips the symbol table from every non-Debug build**
 (`.strip = optimize != .Debug`) — so the *installed* `zig-out/bin/cljw` is the
-"shipped" column directly, with no separate packaging step (cljw renders error
+shipped artifact directly, with no separate packaging step. cljw renders error
 traces from its own runtime stack, not native symbols, so stripping costs no
-diagnostics; Debug stays unstripped for `lldb`). **ReleaseSafe is the
-recommended release build** (optimised *with* runtime safety checks), so 3.24 MB
-is the honest "what you download" number. For the absolute size floor, a
-post-build `strip zig-out/bin/cljw` shaves ReleaseSmall a further ~175 KB to
-1.63 MB (Zig's link-time strip is less aggressive than the CLI `strip` for the
-ReleaseSmall layout; for ReleaseSafe the link-strip is already minimal). Sizes
-are for the default `cljw`; with the optional WebAssembly FFI engine (`-Dwasm`)
-the ReleaseSafe build is about **3.64 MB** (3,820,664 bytes — still a single
-binary, under 4 MB).
+diagnostics; Debug stays unstripped for `lldb`.
+
+**ReleaseSafe is the release build** — optimised *with* runtime safety checks
+retained. `ReleaseSmall` builds smaller but turns safety checks off and is not
+shipped; it is a size-floor reference only, and its figures are not gated
+because they are not what anyone downloads. <!--size:other-->
+
+### Growth history
+
+| Date       | Bytes     | Note                                                        |
+|------------|-----------|-------------------------------------------------------------|
+| 2026-07-16 | 9,469,816 | before the ADR-0172 binary-size campaign                    |
+| 2026-07-16 | 6,974,584 | after the campaign (−26.3% in one pass)                     |
+| 2026-08-04 | 7,368,808 | current — +5.6% since the campaign, well under the ceiling |
+
+The ADR-0172 campaign levers were: unwind-table strip (O-052), envelope-v7
+constant pool + flate regions/sources (ADR-0173), zwasm v2.2.1 thunk collapse,
+and sort dedup (O-053). The per-component budget plus this gate now govern
+growth; the ADR-0172 derived ceiling is 8,800,000 bytes, and crossing it
+requires a conscious budget amendment, not a silenced check.
 
 What sits inside that binary: a full Clojure numeric tower (Long→BigInt
 promotion, Ratio, BigDecimal), MVCC software transactional memory, agents,
 futures/promises/delays, lazy + chunked sequences, transducers,
-protocols/records/multimethods, namespaces, a CIDER-compatible nREPL, and ~24
-bundled `clojure.*` standard namespaces — plus both a tree-walking interpreter
-and a bytecode VM.
+protocols/records/multimethods, namespaces, a CIDER-compatible nREPL, ~24
+bundled `clojure.*` standard namespaces, both a tree-walking interpreter and a
+bytecode VM — and the embedded zwasm engine (interpreter + JIT), which is
+roughly 3 MB of that total on its own. <!--size:other-->
 
 ## Cold start (secondary, machine-dependent)
 
@@ -62,9 +80,16 @@ cross-machine number — reproduce it on your own hardware with the script above
 
 ## Honesty note
 
-These figures supersede earlier rougher estimates (~600 KB / ~2.5 ms). The
-binary grew as the numeric tower, STM, agents, nREPL, protocols, and the bundled
-`clojure.*` namespaces landed; ~3.4 MB (ReleaseSafe) is the honest current size
-for the full runtime, ~1.6 MB if built purely for size. The point is not a size
-record — it is that a from-scratch Clojure runtime with this much of the
-language ships as a single small binary that starts in a few milliseconds.
+These figures supersede earlier, rougher estimates. The binary grew as the
+numeric tower, STM, agents, nREPL, protocols, the bundled `clojure.*`
+namespaces, and finally the always-embedded Wasm engine landed. The point was
+never a size record — it is that a from-scratch Clojure runtime with this much
+of the language, plus a spec-complete WebAssembly engine, ships as a single
+binary that starts in a few milliseconds.
+
+What the honesty note used to say, and why it is worth recording: it claimed
+"~3.4 MB (ReleaseSafe) is the honest current size" <!--size:other-->, a figure
+from before the Wasm engine was embedded by default. A number that no gate
+checks will drift from the truth and then be quoted as if it were measured.
+That is why the `size_claims` gate now reads this file too — and why it caught
+this very sentence on its first run.
@@ -5,14 +5,14 @@ different job and is excellent at it. This page is a map of where they sit, not
 a ranking — ClojureWasm is one young entry exploring the WebAssembly
 corner, and the only numbers it claims are its own measured ones.
 
-| Runtime            | Host / where it shines                                                                                                | Distribution                             |
-|--------------------|-----------------------------------------------------------------------------------------------------------------------|------------------------------------------|
-| **Clojure (JVM)**  | The JVM. Mature, complete, an enormous ecosystem.                                                                     | Runs on a JVM.                           |
-| **Babashka / SCI** | GraalVM native / JS. Fast-starting scripting, glue.                                                                   | Self-contained binary.                   |
-| **ClojureScript**  | JavaScript. Front-end and the Node ecosystem.                                                                         | JS host.                                 |
-| **jank**           | LLVM / C++. Native code and seamless C++ interop.                                                                     | Native.                                  |
-| **ClojureDart**    | Dart / Flutter. Mobile and cross-platform UI.                                                                         | App bundles.                             |
-| **ClojureWasm**    | Zig. Embeds a Wasm engine so Clojure calls modules from Rust/Go/C (polyglot FFI), and compiles to WebAssembly itself. | ~3 MB native binary, starts in a few ms. |
+| Runtime            | Host / where it shines                                                            | Distribution                            |
+|--------------------|-----------------------------------------------------------------------------------|-----------------------------------------|
+| **Clojure (JVM)**  | The JVM. Mature, complete, an enormous ecosystem.                                 | Runs on a JVM.                          |
+| **Babashka / SCI** | GraalVM native / JS. Fast-starting scripting, glue.                               | Self-contained binary.                  |
+| **ClojureScript**  | JavaScript. Front-end and the Node ecosystem.                                     | JS host.                                |
+| **jank**           | LLVM / C++. Native code and seamless C++ interop.                                 | Native.                                 |
+| **ClojureDart**    | Dart / Flutter. Mobile and cross-platform UI.                                     | App bundles.                            |
+| **ClojureWasm**    | Zig. Embeds a Wasm engine so Clojure calls modules from Rust/Go/C (polyglot FFI). | ~7.4 MB native binary, starts in ~6 ms. |
 
 The other rows are respectful summaries of what each runtime is known for, not
 evaluations. The ClojureWasm row lists only its own
@@ -21,19 +21,25 @@ anything.
 
 ## What "the WebAssembly corner" means here
 
-Two things, which are easy to conflate:
+Two things, which are easy to conflate — and only the first one is shipped:
 
-1. **ClojureWasm compiles to WebAssembly** — the runtime is plain Zig, so a
-   WebAssembly build is a natural target (a browser-only playground, a small
-   Wasm function).
-2. **ClojureWasm embeds a WebAssembly engine** — so a Clojure program can load a
+1. **ClojureWasm embeds a WebAssembly engine.** A Clojure program can load a
    sandboxed module compiled from Rust, Go, Zig, or C and call it like a
    namespace. WebAssembly becomes an FFI: other languages' libraries become
    callable from Clojure, in-process and sandboxed. (See
-   [`docs/examples/wasm/`](../docs/examples/wasm/).)
-
-That second point is the part that does not have an obvious equivalent in the
-other runtimes, and it is the angle ClojureWasm is exploring.
+   [`docs/examples/wasm/`](../docs/examples/wasm/).) This is the angle
+   ClojureWasm is exploring, and it has no obvious equivalent in the other
+   runtimes.
+2. **ClojureWasm does not compile *itself* to WebAssembly.** There is no
+   `wasm32` build of the runtime, and `cljw build` produces a native binary
+   with an embedded bytecode payload — not a `.wasm`. The runtime is plain
+   Zig, so the target is reachable in principle, but the value representation
+   and garbage collector are designed for linear memory, so such a build would
+   not interoperate with WasmGC-based languages. It is tracked as future
+   research, not a feature.
+
+Compiling *Clojure source* into a WebAssembly component is a separate project:
+[ClojureWit](https://github.com/clojurewasm/ClojureWit), in the same org.
 
 ## A note on respect
 
 
@@ -10,14 +10,23 @@
 #
 # Gate mode:
 #   bash scripts/binary_size_report.sh --check [BIN]
-#     Compares README.md's headline size claim (the FIRST "<N> MB" match
-#     in the file — keep the claim the first MB figure in README) against
-#     BIN's measured size. Fails (exit 1) when the drift exceeds 10%.
-#     This is the structural fix for the 2026-07 rot incident where
-#     README said "about 3.8 MB" while the shipped binary was 9.5 MB.
+#     Checks EVERY "<N> MB" figure in every file listed in SIZE_CLAIM_FILES
+#     against BIN's measured size. Fails (exit 1) when any of them drifts
+#     more than 10%. A figure that is deliberately NOT the shipped size
+#     (babashka's binary, the ReleaseSmall floor, a historical row) must
+#     carry an inline `<!--size:other-->` marker on the same line — so the
+#     exemption is explicit and greppable, never silent.
 #     Wired into test/run_all.sh as the `size_claims` step (full gate;
 #     runs right after build_cljw so the binary is fresh).
 #
+#     History: the check originally read ONLY README.md's first MB figure.
+#     The 2026-08-04 audit found that docs/landscape.md ("~3 MB", 2.4x
+#     under) and bench/RELEASE_METRICS.md (a table saying 6.97 MB with
+#     prose two paragraphs below still claiming 3.24 MB) had both rotted
+#     precisely because nothing checked them — the same shape as zwasm's
+#     2026-08-03 `ungated-negative-doc-claim-rotted-into-a-lie` lesson.
+#     Every public size claim is gated now.
+#
 # Reference platform for ADR-0172 numbers: macOS arm64, ReleaseSafe,
 # -Dwasm, stripped (= the brew artifact config). MB here is decimal
 # (10^6 bytes), matching what brew/GitHub display to users.
@@ -48,27 +57,64 @@ else
 fi
 ACTUAL_MB=$(awk "BEGIN{printf \"%.2f\", $ACTUAL/1000000}")
 
+# Every public document that states the shipped binary's size. Overridable so a
+# new doc can be added without editing the script body.
+SIZE_CLAIM_FILES="${SIZE_CLAIM_FILES:-README.md docs/landscape.md bench/RELEASE_METRICS.md}"
+
+# A line carrying this marker is exempt: the figure on it is deliberately not
+# the shipped size (another project's binary, the ReleaseSmall floor, a dated
+# historical row). Exemptions are visible in the source and greppable.
+SIZE_EXEMPT_MARKER='<!--size:other-->'
+
 if [[ "$MODE" == "check" ]]; then
-    CLAIM=$(grep -m1 -oE '[0-9]+(\.[0-9]+)? MB' README.md | head -1 | grep -oE '[0-9]+(\.[0-9]+)?' || true)
-    if [[ -z "$CLAIM" ]]; then
-        echo "size_claims: no '<N> MB' size claim found in README.md — add one (ADR-0172)" >&2
-        exit 1
-    fi
     if [[ "$ACTUAL" -gt "$BUDGET_CEILING_BYTES" ]]; then
         echo "size_claims: built binary ${ACTUAL_MB} MB (${ACTUAL} B) exceeds the ADR-0172 derived ceiling ($BUDGET_CEILING_BYTES B)." >&2
         echo "  Attribute with 'bash scripts/binary_size_report.sh' (-Dprofile build for symbols), then land a lever" >&2
         echo "  or consciously amend the budget table in .dev/decisions/0172_binary_size_budget_and_ledger.md." >&2
         exit 1
     fi
-    DRIFT=$(awk "BEGIN{c=$CLAIM*1000000; d=($ACTUAL-c)/c; if(d<0)d=-d; printf \"%.3f\", d}")
-    OK=$(awk "BEGIN{print ($DRIFT <= 0.10) ? 1 : 0}")
-    if [[ "$OK" == "1" ]]; then
-        echo "    size_claims: README claims ${CLAIM} MB, measured ${ACTUAL_MB} MB (${ACTUAL} B) — within 10%"
-        exit 0
+
+    checked=0
+    exempt=0
+    failed=0
+    for f in $SIZE_CLAIM_FILES; do
+        if [[ ! -f "$f" ]]; then
+            echo "size_claims: listed file not found: $f (fix SIZE_CLAIM_FILES in scripts/binary_size_report.sh)" >&2
+            exit 1
+        fi
+        while IFS=: read -r lineno line; do
+            [[ -z "$lineno" ]] && continue
+            if [[ "$line" == *"$SIZE_EXEMPT_MARKER"* ]]; then
+                exempt=$((exempt + 1))
+                continue
+            fi
+            # A line may carry more than one figure; check each.
+            while read -r claim; do
+                [[ -z "$claim" ]] && continue
+                checked=$((checked + 1))
+                DRIFT=$(awk "BEGIN{c=$claim*1000000; d=($ACTUAL-c)/c; if(d<0)d=-d; printf \"%.3f\", d}")
+                OK=$(awk "BEGIN{print ($DRIFT <= 0.10) ? 1 : 0}")
+                if [[ "$OK" != "1" ]]; then
+                    failed=$((failed + 1))
+                    echo "size_claims: $f:$lineno claims ${claim} MB but the built binary is ${ACTUAL_MB} MB (${ACTUAL} B) — drift >10%." >&2
+                    echo "  → $(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-100)" >&2
+                fi
+            done < <(printf '%s\n' "$line" | grep -oE '[0-9]+(\.[0-9]+)? ?MB' | grep -oE '[0-9]+(\.[0-9]+)?')
+        done < <(grep -nE '[0-9]+(\.[0-9]+)? ?MB' "$f" || true)
+    done
+
+    if [[ "$checked" -eq 0 ]]; then
+        echo "size_claims: no gated '<N> MB' size claim found in: $SIZE_CLAIM_FILES" >&2
+        echo "  At least README.md must state the shipped size (ADR-0172). Did every claim get an exemption marker?" >&2
+        exit 1
     fi
-    echo "size_claims: README claims ${CLAIM} MB but the built binary is ${ACTUAL_MB} MB (${ACTUAL} B) — drift >10%." >&2
-    echo "  Update README's size figure (and CHANGELOG on release) per ADR-0172; do not let the claim rot." >&2
-    exit 1
+    if [[ "$failed" -gt 0 ]]; then
+        echo "  Update the figure (and CHANGELOG on release) per ADR-0172, or mark the line $SIZE_EXEMPT_MARKER" >&2
+        echo "  if it deliberately reports something other than the shipped binary. Do not let a claim rot." >&2
+        exit 1
+    fi
+    echo "    size_claims: ${checked} claim(s) across $(echo "$SIZE_CLAIM_FILES" | wc -w | tr -d ' ') file(s) match ${ACTUAL_MB} MB (${ACTUAL} B) within 10%; ${exempt} line(s) exempt"
+    exit 0
 fi
 
 echo "== $BIN: ${ACTUAL} bytes (${ACTUAL_MB} MB decimal)"