docs: say what the engine is for, and give the laws a home

The root README was a status page: a migration note, a two-engines-converging
paragraph, and a flat crate list. It told a reader what is in the tree and never
what the engine is for, which is the one thing a stranger arrives wanting.

It now leads with the position. `n0` is the renderer half of a browser —
embeddable, deterministic, eventually editable — and the refusals (scripting,
navigation, network, the user-agent surface, an ambient clock) are stated as
what buys determinism, a single binary, a small attack surface, and animation
where dropped frames are structurally impossible. "Nothing but drawing" stays,
promoted from a subtitle to the thesis, because it is the same refusal the rest
of the page spells out. Stylo and Skia are named for the first time: the two
borrowed pieces are Firefox's cascade and Chromium's rasterizer, and n0 is the
architecture between them — which is also why byte-comparing against a Chromium
bake is a reasonable bar rather than a boast.

Honesty is structural rather than per-sentence. The engine's goals are stated as
goals; **Where it is today** carries the admitted slice, the corpus, and the
explicit not-yet list; and the legacy engine plus the parked `.grida`/`.n0.xml`
formats get one bounded section that explains *why* they are parked, instead of
appearing as an asterisk on every claim. FLIP is respected throughout: the
corpus is described exactly as `svg-engine-of-record.md` describes it, followed
by a statement that it is not a conformance claim and no score exists.

**The laws had no home.** The mode rule lived in `topology.md`, refusal-as-
identity in three crate READMEs, reuse-≡-fresh only in the naming convention of
`crates/n0/tests/cache.rs` — so every session re-derived them. `AGENTS.md` now
states seven, each with the mechanism that enforces it, including the tripwire
that a mode/budget/quality flag must never become readable from `websem`,
`rframe`, or resolve, and the note that `DirtyClass` is referenced zero times on
purpose and must not be "finished" without the reuse gate. It also gains a
**Current state and caveats** section — two live engines, nothing publishable,
no n0 wasm target, Taffy as today's layout engine and the wall that would force
a house one — and a **Provenance** section that absorbs the migration history
the README shed.

Two claims were corrected against the code rather than carried over. The CLI
transcript in the README is verbatim output from both admissions, not a
paraphrase. And a draft line claiming no crate on this path is publishable was
dropped: `n0`, `math2`, and `fonts` carry no `publish` key and therefore default
to publishable. The true statement — there are no releases, and the only shipped
artifact is the frozen v1 wasm package — is what shipped.

Not done, deliberately: `www/app/(home)/page.tsx` still carries the older, weaker
description and now reads inconsistently with this page; #43 is
still the position pointer AGENTS.md sends sessions to, and is still stale; and
the false Skia-confinement comment in `crates/n0/Cargo.toml`, found while
checking whether the README could claim it, is filed rather than fixed here.

Author: softmarshmallow

AGENTS.md

@@ -1,11 +1,64 @@
-# Hi robots, welcome to nothing — the Grida graphics engine.
-
-`n0` ("nothing") is the 2D graphics engine. This is a **Rust-first Cargo
-workspace** (resolver 3; members in the root `Cargo.toml`). The Grida product
-monorepo — editor, packages, services — is
-[gridaco/grida](https://github.com/gridaco/grida); it consumes this repo
-**only** as the published `@grida/canvas-wasm` npm artifact. Do not add
-product/editor code here.
+# Hi robots, welcome to n0 ("nothing") — the Grida graphics engine.
+
+[README.md](./README.md) says what this engine is and why. This file is the
+working map: the laws that bind every change, the commands, the layout, and the
+caveats that are true right now.
+
+`n0` is a 2D graphics engine and a **Rust-first Cargo workspace** (resolver 3;
+members in the root `Cargo.toml`). The Grida product monorepo — editor,
+packages, services — is [gridaco/grida](https://github.com/gridaco/grida); it
+consumes this repo **only** as the published `@grida/canvas-wasm` npm artifact.
+Do not add product/editor code here.
+
+## The laws (bind every change)
+
+These are what keep two duty cycles, three source languages, and an editor from
+becoming three engines. Each has an enforcing mechanism — a law without one is
+a comment.
+
+- **Never a silent wrong pixel.** A construct the compiler cannot honour must
+  refuse loudly (`--strict`) or be declared by name at a stable node path
+  (best-effort). A patrol that over-refuses beats one that lets a wrong pixel
+  through. _Enforced by:_ the websem patrols, the refusal corpus, and the law
+  that both admissions are frame-identical where nothing degrades.
+
+- **One meaning, many policies.** Render modes may differ in _when and at what
+  quality_ they paint — never in _what things mean_. Static is not a second
+  renderer; it is the same pipeline with an empty temporal input set (no camera
+  delta, no previous frame, no dirty set). _Tripwire:_ a mode, budget, or
+  quality flag must never become readable from `websem`, `rframe`, or resolve.
+  The moment one is, two pipelines have started growing.
+
+- **Realtime in structure, static in policy.** The architecture that makes
+  realtime possible ships from day one, because retrofitting it _is_ the
+  rebuild. The optimizations realtime needs ship only once measured, because an
+  optimization is a relative claim — _same as X, faster_ — and a cache built
+  over an unverified X becomes a second place that believes the wrong answer.
+  _In tree:_ `DirtyClass` is fully classified in `n0-model/src/ops.rs` and
+  referenced **zero** times in `crates/n0/src`. The socket is shaped, the policy
+  is deliberately absent. Do not "finish" it without the gate below.
+
+- **Reuse ≡ fresh.** Any frame produced with reuse must be byte-identical to the
+  same frame produced from scratch. _Enforced by:_ `crates/n0/tests/cache.rs` —
+  the `*_matches_fresh` naming _is_ the law. Every new cache, damage path, or
+  incremental stage adds its own instance.
+
+- **A module's identity is what it refuses**, and the refusal has a guarding
+  test. `rframe` cannot express a gradient. `animation-sampling` owns no clock.
+  `csscascade` adds no matcher of its own. _Enforced by:_ the architecture tests
+  — `rframe`'s backend-free lock, the model tier's skia-free lock, `n0_cli`'s
+  lock against the retired `htmlcss` route. Before adding to a module, state
+  what it refuses; if the addition violates no refusal, the name is too loose.
+
+- **The oracle is external.** Chromium or declared consensus grades pixels —
+  never the other engine in this tree. Stylo bounds what can be _supported_: a
+  gap there is a declared hole, not a wrong pixel, and never a reason to add a
+  second matcher.
+
+- **Patrol before drop.** No deletion, replacement, or conflict resolution
+  without a triage pass and a captured-essence ledger first. Load-bearing
+  caveats are re-homed before the deletion merges; deliberate drops are named in
+  the commit message.
 
 ## Setup
 
@@ -72,6 +125,36 @@ python3 bin/activate-flatc -- --rust -o crates/grida/src/io/generated format/gri
 | `third_party/`              | vendored usvg (reference source) + emsdk submodule                                         |
 | `bin/`                      | `activate-flatc`, `activate-emsdk` — pinned tool activators                                |
 
+## Current state and caveats
+
+What is true right now, so a session does not infer it from ambition.
+
+- **Two engines are live, on purpose.** `crates/grida` still depends on
+  `crates/htmlcss` and still renders Web sources; D-N permitted breaking that
+  and the permission was never used. The n0 path (`websem → rframe → n0`) is the
+  SVG engine of record for **new** work — `htmlcss` is a frozen semantics donor
+  that evolution rungs mine, never extend.
+- **Nothing on the n0 path is publishable.** `n0_cli`, `n0-model`, `websem`, and
+  `rframe` are all `publish = false`, and there are no releases. The only shipped
+  artifact in the tree is the frozen v1 wasm package.
+- **There is no n0 WebAssembly target.** `grida-canvas-wasm` binds
+  `crates/grida` only. The v2 port is priced work, not an assumption.
+- **Taffy is the layout engine.** A house-built layout engine is a stated goal,
+  not a current fact. The wall that would force it is browser-grade intrinsic
+  sizing across a namespace-aware tree — not flex.
+- **No conformance score may be produced or inspected.** The FLIP rule is
+  unratified ([gridaco/nothing#49](https://github.com/gridaco/nothing/issues/49)).
+  A corpus may be described; results may not be scored, aggregated, or presented
+  as conformance.
+- **The admitted slice has one statement of record** —
+  [`crates/n0_cli/README.md`](./crates/n0_cli/README.md). Do not restate it
+  elsewhere; link it. The same holds for the v1 capability inventory
+  ([`crates/grida/README.md`](./crates/grida/README.md)) and the realtime
+  optimization estate ([`docs/wg/feat-2d/optimization.md`](./docs/wg/feat-2d/optimization.md)).
+- **Plans are `*.plan.md`** — gitignored scratch, never committed knowledge.
+  Durable knowledge lands in `docs/wg/` or a crate README; work items land in
+  issues.
+
 ## Skills
 
 Agent skills live in `.agents/skills/` (`.claude/skills` symlinks to it):
@@ -98,6 +181,23 @@ This repo owns publishing and must never unpublish/deprecate that version.
 The `v1-freeze` branch pins the tree that built it, for emergency `canary.N+1`
 cuts.
 
+## Provenance
+
+The engine migrated from [gridaco/grida](https://github.com/gridaco/grida) with
+its full history (2025→); Grida remains the product monorepo. The v2 family was
+promoted from the `model-v2-anchor` research branch
+([gridaco/nothing#9](https://github.com/gridaco/nothing/issues/9)); its frozen
+workbench record lives in [`archive/model-v2/`](./archive/model-v2/README.md),
+and paths inside those frozen papers refer to the pre-promotion layout.
+
+How two engines become one is the **consolidation program** —
+[`docs/wg/consolidation/`](./docs/wg/consolidation/index.md). It owns the phases,
+the gates, and the owner decision registry (D-C, D-L, D-M, D-N taken; FLIP,
+NAME, D-D, D6, D-H, D-G(b), D-J, D-K, D-E/D-I open). Read
+[its index](./docs/wg/consolidation/index.md) before program work; the charter
+records the *route*, and the current *position* is tracked on
+[gridaco/nothing#43](https://github.com/gridaco/nothing/issues/43).
+
 ## Where work gets filed
 
 - **This repo (gridaco/nothing)**: engine rendering, the node/document model,

README.md

@@ -2,40 +2,196 @@
   <img src="./assets/logo.svg" alt="Nothing" width="474">
 </p>
 
-# n0 ("nothing")
+# n0
 
-Nothing but drawing. An engine for everything drawable.
+**Nothing but drawing.** A 2D graphics engine that speaks the Web — browser-grade
+rendering, without a browser.
 
-`n0` (pronounced "nothing") is a 2D graphics engine.
+`n0` (pronounced "nothing") turns SVG and HTML/CSS into exact pixels: from a
+command line, from a library, and eventually onto an editable realtime canvas.
+No scripting, no navigation, no network, no user agent.
 
-## Status
+## The claim
 
-The graphics engine lives here. It migrated from the
-[Grida repository](https://github.com/gridaco/grida) with its full history
-(2025→) carried over; Grida remains the service/editor monorepo and consumes
-the engine only through published artifacts.
+n0 is the renderer half of a browser — embeddable, deterministic, and
+eventually editable. There is no agent half:
 
-Two engines live side by side while the topology converges: the migrated
-production engine (`crates/grida`, shipping as `@grida/canvas-wasm`) and
-the v2 `n0` engine family (`crates/n0`), promoted from the
-`model-v2-anchor` research branch. The v2 model program is tracked in
-[gridaco/nothing#9](https://github.com/gridaco/nothing/issues/9).
+| n0 refuses             | which buys                                                         |
+| ---------------------- | ------------------------------------------------------------------ |
+| scripting              | determinism — same input, same declared time, same bytes           |
+| navigation & network   | one binary, no sandbox, no headless flags, no 200MB download       |
+| the user-agent surface | a small attack surface and a core you can embed                    |
+| an ambient clock       | frame-exact animation — dropped frames are structurally impossible |
+
+## What it's for
+
+- **Deterministic Web rendering.** SVG and HTML/CSS to exact pixels — in CI, in
+  a container, on a machine that will never have a browser. Same input, same
+  declared time, same bytes.
+- **Animation as exact time.** A source compiles once and is sampled at a
+  declared signed-nanosecond instant. An exported sequence has no frame to drop.
+- **Realtime on heavy documents.** 60+ fps where an entire page is one frame
+  inside an infinite canvas — panning, zooming, editing.
+- **Layout we own.** Browser-grade layout is where general-purpose layout
+  libraries stop. Taffy carries flex until it doesn't.
+- **One engine, everywhere.** Native and WebAssembly, single-threaded — no
+  worker threads to hide behind.
+
+## The pipeline
+
+One document, one cascade, one compiler, one contract, one kernel.
+
+```text
+source bytes  (.svg | .html)
+    → one namespace-aware document        csscascade
+    → one Stylo cascade                   csscascade
+    → effective values: Base | Sample t   websem
+    → rframe::Frame                       websem
+    → resolve → drawlist → paint          n0
+```
+
+Each stage owns one decision. `csscascade` resolves values and decides no
+meaning; `websem` decides what will and will not render, and never touches a
+canvas; `rframe` is a vocabulary whose value is what it *cannot* express; `n0`
+decides how to get pixels, never what they mean.
+
+Two pieces are borrowed on purpose. The cascade is **Stylo** — Firefox's style
+engine, pinned to an upstream revision, not a CSS subset written here. The
+rasterizer is **Skia** — the same one Chromium rasterizes with, which is much of
+why byte-exact comparison against a Chromium bake is a reasonable bar at all.
+n0 is the architecture between them: it owns resolution, the drawlist, damage,
+caching, and time. It owns no cascade and no rasterizer.
+
+## Declared holes, never guessed pixels
+
+The engine refuses loudly, or it names the hole. It never guesses.
+
+```console
+$ # best-effort (the default): render what is admitted, declare the rest by name
+$ cargo run -q -p n0_cli --bin n0 -- fixtures/test-svg/probe/polygon-fill-probe.svg out.png 64x64
+degraded: skipped svg/polygon[1]: unsupported element <polygon>
+rendered fixtures/test-svg/probe/polygon-fill-probe.svg -> out.png (64x64, base-shared-frame, 1 degraded, 223 bytes)
+
+$ # --strict: refuse on the first construct outside the slice
+$ cargo run -q -p n0_cli --bin n0 -- fixtures/test-svg/probe/polygon-fill-probe.svg out.png 64x64 --strict
+error: render failed: unsupported element <polygon>
+```
+
+Where nothing degrades, the two admissions are frame-identical, and a law
+checks that across the whole corpus.
+
+```sh
+# a whole composition — containers, curves, strokes, one animated rect —
+# rendered at its authored state, and at exactly one second
+cargo run -p n0_cli --bin n0 -- \
+  fixtures/web-first/animation/svg-scene-cub-animation.svg cub.png 96x96
+cargo run -p n0_cli --bin n0 -- \
+  fixtures/web-first/animation/svg-scene-cub-animation.svg cub-1s.png 96x96 \
+  --time-ns 1000000000
+```
+
+## Where it is today
+
+The Web path renders a standalone SVG, or an HTML document's first inline SVG:
+`<rect>`, `<circle>`, `<ellipse>`, `<path>` and `<line>` — filled and stroked —
+nested in `<g>` with the whole `transform` grammar; root sizing per SVG2 §8.2
+with the full `preserveAspectRatio` grammar; and one exact-time `<animate>`.
+[`crates/n0_cli/README.md`](./crates/n0_cli/README.md) is the statement of
+record for that slice and what it refuses.
+
+Its corpus is 77 Chromium-baked cells and 10 sampled frames, byte-exact except
+six curved cells carrying a declared tolerance confined to the weighted
+rational conic. That describes one enumerated corpus — **it is not a
+conformance claim**, and no conformance score exists.
+
+Not admitted yet: text, gradients, clips, masks, filters, and opacity. Not built
+yet: any layout engine, any editor host, any WebAssembly target.
+
+**Nothing here is published.** There are no releases, and the only shipped
+artifact in the tree is the frozen v1 wasm package. Run it from a clone —
+[setup](./AGENTS.md#setup).
+
+## One pipeline
+
+2D has no perceptual slack: a 40px icon is either right or visibly wrong, and no
+level-of-detail trick hides it. So there is no fast renderer beside an exact one.
+Static is the same pipeline with an empty temporal input set — no camera delta,
+no previous frame, no dirty set. Realtime is the same pipeline allowed to reuse.
+
+> Modes may differ in **when and at what quality** they paint — never in **what
+> things mean**.
+
+The architecture that makes realtime possible ships from day one; the
+optimizations it needs ship only once measured. So the sockets ship empty:
+`DirtyClass` classifies every operation's invalidation in `n0-model`, and the
+engine references it exactly zero times. It full-resolves every frame until
+correctness has earned the right to reuse.
+
+## The laws
+
+- **Never a silent wrong pixel.** Refuse, or name the hole.
+- **A module's identity is what it refuses**, and the refusal has a guarding
+  test. `rframe` cannot express a gradient. `animation-sampling` owns no clock.
+  `n0_cli` is architecturally forbidden from calling the renderer it replaced.
+- **Reuse ≡ fresh.** Any frame produced with reuse is byte-identical to the same
+  frame produced from scratch.
+- **The oracle is external.** Chromium, or declared consensus. Never this
+  engine's other half. Stylo bounds what can be *supported*; a gap there is a
+  declared hole, never a wrong pixel.
+
+## Why the Web first
+
+The destination is n0's own source language — SVG with layout, reimagined. It
+is deliberately not being built yet.
+
+The Web is the only 2D graphics specification that is frozen, adversarially
+tested, and ships with a free executable oracle. A custom format has none of
+that. On the Web path every correctness question has an answer before anyone has
+an opinion — and the cascade, layout, paint, text, and animation built to satisfy
+it are the same ones the format will stand on.
+
+The format is not deprioritized. It is waiting for a bar that can grade it.
+
+## Also in this tree
+
+**A second engine.** [`crates/grida`](./crates/grida/README.md) is the mature
+v1: 19 node types, gradients, image filters, shadows, masks, PDF and SVG export,
+and a realtime estate benchmarked to 135K-node documents. It ships
+as `@grida/canvas-wasm` and is frozen there. It is being succeeded, not
+extended — its know-how migrates into n0 through contracts, never by copying,
+and the measurements in
+[`docs/wg/feat-2d/optimization.md`](./docs/wg/feat-2d/optimization.md) are the
+best existing description of what a realtime 2D engine actually needs.
+
+**Two custom formats, parked.** `.grida` (the v1 FlatBuffers binary) is frozen
+and read-only. `.n0.xml` (the authored source language) builds and is tested,
+and is deliberately not being expanded. Both are waiting on the same thing: a
+foundation proven against an oracle that can grade it.
 
 ## Workspace
 
-- [`crates/grida`](./crates/grida) — the legacy engine compatibility consumer
-- [`crates/cg`](./crates/cg) — the backend-neutral canvas-graphics vocabulary
-- [`crates/htmlcss`](./crates/htmlcss) — the extracted mature static HTML/CSS/SVG renderer
-- [`crates/grida_editor`](./crates/grida_editor) — the editor core (document, history, commands)
-- [`crates/grida-canvas-wasm`](./crates/grida-canvas-wasm) — WASM bindings (`@grida/canvas-wasm`)
-- [`crates/math2`](./crates/math2) · [`crates/csscascade`](./crates/csscascade) · [`crates/fonts`](./crates/fonts) — foundations
-- [`crates/grida_dev`](./crates/grida_dev) · [`crates/grida_wpt`](./crates/grida_wpt) — dev tools, benchmarks, reftests
-- [`crates/n0`](./crates/n0) — the `n0` engine (v2): resolve → drawlist → paint
-- [`crates/n0-model`](./crates/n0-model) · [`crates/n0_dev`](./crates/n0_dev) — the skia-free `anchor` model · the v2 dev shell
-- [`crates/websem`](./crates/websem) · [`crates/rframe`](./crates/rframe) · [`crates/animation-sampling`](./crates/animation-sampling) — the Web semantic compiler · the resolved render contract it emits · the time axis both read
-- [`crates/n0_cli`](./crates/n0_cli) — the thin `n0` file-render command host
-- [`archive/model-v2/`](./archive/model-v2) — the frozen v2 workbench archive (decision record)
-- [`format/`](./format) — the FlatBuffers schema (source of truth)
-- [`docs/wg/`](./docs/wg) — the engine's normative working-group specs
-
-The repository is a Rust-first Cargo workspace.
+The Web path — `csscascade` → `websem` → `rframe` → `n0`:
+
+| crate                                                         |                                                                    |
+| ------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [`csscascade`](./crates/csscascade/README.md)                 | the Stylo bridge — one namespace-aware document, one cascade       |
+| [`websem`](./crates/websem/README.md)                         | the Web semantic compiler — what will and will not render          |
+| [`rframe`](./crates/rframe/README.md)                         | the resolved render contract — backend-free, provisional           |
+| [`animation-sampling`](./crates/animation-sampling/README.md) | the time axis — no ambient clock                                   |
+| [`n0`](./crates/n0/README.md) · [`n0-model`](./crates/n0-model/README.md) | the engine, and its skia-free model                     |
+| [`n0_cli`](./crates/n0_cli/README.md)                         | the `n0` binary                                                     |
+
+The v1 engine and its satellites: `grida`, `htmlcss`, `cg`, `grida_editor`,
+`grida-canvas-wasm`, `grida_dev`, `grida_wpt`. Foundations: `math2`, `fonts`.
+The full map is in [AGENTS.md](./AGENTS.md).
+
+## Docs
+
+[`docs/wg/`](./docs/wg/index.md) is the engine's working group — normative
+specifications, domain studies, and research, including 41 documents on
+Chromium's rendering architecture. Start at
+[the consolidation program](./docs/wg/consolidation/index.md) for how the two
+engines become one.
+
+Rust-first Cargo workspace. Licensed under [MIT](./LICENSE-MIT) or
+[Apache-2.0](./LICENSE-APACHE), at your option.