docs: rewrite README as landing page, extract FAQ

CHANGELOG.md

@@ -50,6 +50,7 @@ A **new hardened rule** is a minor version, not a major one — it adds a check,
 - **Two documentation checks, on the standard tool contract.** `tools/linkcheck.mjs` (`D1`–`D3`) and `tools/mermaidcheck.mjs` (`D4`–`D7`) — same flags, same severity ladder, same `0` / `1` / `2` exit semantics as every other tool, zero dependencies. Documented in `VALIDATION_ENGINE.md § 13`, including the two false positives that shaped them.
 - **`.github/workflows/checks.yml`.** Three jobs: documentation integrity, tool and config syntax, and a re-derivation of `examples/signin` by the three browser-free validators — with `git diff --exit-code` on the run's committed artifacts, because a validator that rewrites the run it is validating is not validating it. The browser-driven checks are deliberately **not** in CI, and the workflow says why.
 - **`docs/rule-candidates.md` — the waiting room.** Observations that look like hardened rules and have not earned it. Principle 5 says every defect becomes a rule; it does not say *immediately*, and a rule is a claim about a **class** that one occurrence cannot establish. Promotion needs the five conditions in `CONTRIBUTING.md` **plus independent recurrence** — a different project, a different author, or a different state reached without knowledge of the first. Two instances one fix removes are one occurrence. Nothing in the register carries a rule code, is cited in a plan or gate record, is checked by a tool, or blocks anything. Seeded with `RC-1`.
+- **`FAQ.md`.** The nine questions previously inline in the README, plus one correction: the `examples/` answer described the folder as empty, which stopped being true when the reference run landed. It now points at `examples/signin/`.
 - **`review.harnessFiles`.** The files in the prototype directory that are review chrome, not product surface. `audit.mjs`'s palette sweep and `annotate.mjs`'s network sweep now read one list, resolved once in `config.mjs` with `review.player` always included.
 - **[`examples/signin/`](examples/signin/) — the toolkit's own reference run.** One feature, brief to frozen deliverable: all twelve states, all seven validators, three human gates, one revision cycle, zero waivers, machine closed at `DONE` with 7/7 completion rules. Includes the **failing** audit (`audit-signin-01`, 138/138 checks passed and the screenshots failed it on three `major` defects) preserved alongside the passing one.
 
@@ -64,6 +65,7 @@ A **new hardened rule** is a minor version, not a major one — it adds a check,
 
 ### Changed
 
+- **`README.md` rewritten as a landing page.** Onboarding-first order — outcome, audience, first project, evidence — with the detail moved to where it already lived in full: the architecture overview, workflow diagram, validator table, philosophy table, repository structure and commercial vision now live only in their dedicated documents. The FAQ moved to `FAQ.md`. Nothing was deleted from the documentation set; the README summarizes, the documents explain. This also retires the README's stale claim that `examples/` is empty — the example section now shows the reference run.
 - **The canonical state vocabulary is defined once (M-2).** The 14 canon terms lived in `templates/state-vocabulary.md`, `tools/navgraph.mjs` and `tools/stategraph.mjs`; all three agreed, and `skills/12` told a contributor to edit two. Both tools now import `CANON_STATES` from `tools/config.mjs`, next to the shared `SEVERITIES` ladder. The set is unchanged, so no product's findings change; a CI step asserts the count and asserts that neither tool has restated the set locally. It stays a toolkit constant rather than a config key on purpose — a per-product term set would make every product's state machine private again, which is the failure `E5` exists to prevent.
 - `docs/workflow.md` § 1.3 now states in one line that its artifact ids are written without the feature suffix while the on-disk convention is `<artifact>-<feature>.md` (M-1). Both forms were correct and documented; a reader met both without being told they were the same thing.
 - **`GETTING-STARTED.md` is now `SETUP.md`** (A-2). The file is configuration and wiring for a real product; "getting started" read as a synonym for `START_HERE.md`, which is the zero-knowledge tutorial. Renamed with `git mv` and all five inbound links updated in the same commit, before anything external could point at the old name.

DIAGRAMS.md

@@ -26,7 +26,7 @@ All diagrams are Mermaid, rendered natively by GitHub. To reuse one, copy the fe
 
 ## 1 · Workflow
 
-The twelve states in machine order. Also in [README § Workflow overview](README.md#workflow-overview).
+The twelve states in machine order. Explained state by state in the [Workflow Guide](WORKFLOW_GUIDE.md).
 
 ```mermaid
 flowchart TD

FAQ.md

@@ -0,0 +1,68 @@
+# FAQ
+
+The questions people actually ask, with the answers the documentation backs.
+
+[← README](README.md) · [Start Here](START_HERE.md) · [Workflow Guide](WORKFLOW_GUIDE.md)
+
+---
+
+## Contents
+
+- [Do I have to run all twelve states?](#do-i-have-to-run-all-twelve-states)
+- [Does this only work with Claude?](#does-this-only-work-with-claude)
+- [Does the agent design the product, or do I?](#does-the-agent-design-the-product-or-do-i)
+- [How long does a feature take?](#how-long-does-a-feature-take)
+- [What if the audit reports dozens of failures?](#what-if-the-audit-reports-dozens-of-failures)
+- [What happens when a revision loop hits its ceiling?](#what-happens-when-a-revision-loop-hits-its-ceiling)
+- [Can I use my own design system?](#can-i-use-my-own-design-system)
+- [Is Figma required?](#is-figma-required)
+- [Where do I put my product's screens, routes and states?](#where-do-i-put-my-products-screens-routes-and-states)
+- [Why is there exactly one example?](#why-is-there-exactly-one-example)
+
+---
+
+## Do I have to run all twelve states?
+
+Two are legitimately skippable. **STATE 12** is skipped when the work is not going to a build team — set `handoff_required: false`. **STATE 02** may be waived per goal when a goal is explicitly marked `no-research-needed`; that is per goal, not wholesale.
+
+You cannot skip STATE 08 before STATE 09, or STATE 09 before STATE 11. The audit exists so the user never debugs; the gate exists so the machine never ships on its own authority.
+
+## Does this only work with Claude?
+
+The skills are written as Claude Skills and that is the smoothest path, but nothing in the contracts is vendor-specific. A state is a document that says what to read, what to write, what must be true on exit and what to do on failure. Any agent that can read files, write files and run Node can execute one. The validators are plain Node and know nothing about any model.
+
+## Does the agent design the product, or do I?
+
+You rule; it produces and proves. The two decisions the machine is structurally forbidden from making are the product direction (Direction Approval Gate, STATE 03) and the decision to ship (Primary User Approval Gate, STATE 09). Between those, the machine does the work and shows its evidence. An unruled question is carried forward as an open decision (`o-<id>`), never defaulted at build time.
+
+## How long does a feature take?
+
+Agent time is dominated by STATE 07 and STATE 08; human time is dominated by the two gates. A small feature — one flow, five to eight screens — is typically a working session plus two review passes. See the per-state indicative durations in [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md). Treat them as planning aids, not commitments.
+
+## What if the audit reports dozens of failures?
+
+Assume the instrument first. On the extraction run, one audit opened at 60 failures with 3 real, and one state probe reported 37 failures of which every single one was the harness. The known false-positive classes are catalogued in [`skills/08-self-audit/SKILL.md`](skills/08-self-audit/SKILL.md#b-harness-false-positives) — scroll rails read as overflow, `#feed` read as a colour, harness chrome read as off-palette, deliberate crops, timing flakes. Confirm at source, correct the harness, re-run. Never waive, never report unconfirmed.
+
+## What happens when a revision loop hits its ceiling?
+
+`HALT_BLOCKED`, with an escalation summary of unresolved items — never a fourth unbounded cycle. The state is fully persisted and resumable. The ceiling resets only by explicit user authorisation, recorded in the revision log. This is a working outcome, not a crash.
+
+## Can I use my own design system?
+
+That is the intended path. Name it in `toolkit.config.json` → `designSystem.sourceId`, **by source id**. STATE 06 maps components to your primitives reuse-first and raises an Extension Note for genuine gaps. The rule exists because a plan built on the wrong design system validates perfectly against it — one such mix-up survived four revision cycles and reached `HALT_BLOCKED` before anyone spotted the tell.
+
+## Is Figma required?
+
+Only for STATE 12, and only when `handoff_required` is true. The navigation graph, the state graphs, the annotations and the reports are all produced by local tools and are readable without Figma. The Figma layer is where those derivations get drawn for a build team.
+
+## Where do I put my product's screens, routes and states?
+
+[`reference/screen-registry.csv`](reference/README.md). It is the spine: `tools/navgraph.mjs` derives the entire navigation model from its cells. Rows are added as flows are designed, not up front — but the columns are fixed. Two separators, not interchangeable: `states` is comma-separated, `entry_from` and `navigates_to` are pipe-separated.
+
+## Why is there exactly one example?
+
+Because it is ours. [`examples/signin/`](examples/signin/README.md) is this repository running its own pipeline on its own product — all twelve states, all seven validators, three human gates, one revision cycle, zero waivers. Shipping another product's artifacts as examples invites the exact failure STATE 06 records first — a plan built on a borrowed source validates perfectly against it. Run the pipeline once on a small feature of **your** product and keep that feature's artifacts as your reference set; [`examples/README.md`](examples/README.md) explains how.
+
+---
+
+[← README](README.md) · [Start Here](START_HERE.md) · [Workflow Guide](WORKFLOW_GUIDE.md) · [Glossary](GLOSSARY.md)