release: add docs/FRONTEND.md

docs/FRONTEND.md

@@ -0,0 +1,1396 @@
+# SatQuery AI — Frontend
+
+**Chapter scope.** This chapter documents the SatQuery AI web frontend end to end: the static tier
+and every page in it, the staging and deploy path that publishes it, the Analyze console in full
+depth (every DOM handle, every state, every event), the eight-event execution protocol and the trace
+bar it drives, the REAL-vs-PREVIEW driver split, the captured-run page, the Hugging Face header
+link, cache-busting, and the Cloudflare platform traps that shape all of the above.
+
+**Grounding.** Every claim below is taken from a file that was read for this chapter. Where a claim
+comes from code, the file is cited inline, e.g. `(frontend/assets/js/mission.js)`. Where a number is
+quoted it is a number that appears in a file; none is estimated. Where the evidence does not exist,
+the text says exactly: `UNKNOWN — not established from the available evidence`.
+
+**Status vocabulary** follows `release/DOCS_STYLE_GUIDE.md` §2: `IMPLEMENTED` · `VERIFIED` ·
+`MEASURED` · `ATTEMPTED` · `NOT RUN` · `BLOCKED` · `DEFERRED` · `REJECTED` · `OPEN` · `RESOLVED` ·
+`CLOSED`.
+
+**Nothing in this chapter is a system-level accuracy claim.** Per `release/DOCS_STYLE_GUIDE.md` §3
+there is **no end-to-end benchmark** for SatQuery AI; the frontend is a *client* of the service, and
+the only system-level numbers quoted here are the ones the delivery documents themselves recorded
+(live validation 3 passes × 8 cases, 8/8 each, 24 runs, 0 mock nodes, trace fill 94.4444 %).
+
+---
+
+## 1. What the frontend is, and what it is not
+
+SatQuery AI's frontend is a **static site**. It is HTML, CSS, and ES modules served from Cloudflare
+Pages. There is no build step that compiles application code, no bundler, no framework, no server
+rendering, and no runtime dependency on a Node process. The staging tool
+(`scripts/stage_pages.mjs`) copies a *reference-closed subset* of `frontend/` into an output
+directory and then hands that directory to `wrangler`.
+
+The site is **hermetic except for one page**. The staging tool computes and prints a reference
+integrity and external-dependency audit, and it reports `HERMETIC` when a page's reference closure
+contains zero network dependencies (`scripts/stage_pages.mjs`). The single deliberate exception is
+`frontend/mission.html`, the Analyze console, which carries a live API base in a `<meta>` tag and can
+call the deployed service. Everything else — the homepage, the essay, the atlas, the architecture
+tour, the benchmark and research pages, the captured-run page — is designed to render without any
+network call beyond its own assets.
+
+> **Honesty note (drift recorded, not hidden).** An older comment inside `frontend/_headers` claimed
+> the site was "100% static, zero network calls". That claim is **stale** and is not repeated here as
+> current truth: `mission.html` is a live-calling page, and `mission.html` is one of the eleven
+> shipped pages. The correct current statement is: *ten of eleven pages are hermetic; `mission.html`
+> is the one live-calling page.*
+
+### 1.1 The design law the frontend was built under
+
+`frontend/HANDOFF.md` is the governing design document for the frontend. Its §1 states the design
+law; §2 defines the token system as CSS custom properties on `:root`; §3–§10 lay out build phases
+A–G; §9 names the integration seam (`SQ.run().ingest`); §13 lists known hard limits; §14 lists the
+real SatQuery schema type names that the frontend is allowed to speak.
+
+The practical consequences of that design law, as they appear in the shipped code:
+
+- **No fabricated imagery is presented as real.** Synthetic imagery produced at runtime carries a
+  `synthetic: true` flag (`frontend/assets/js/core.js`, `SQ.scene`), and pages that use placeholder
+  numbers say so in their own prose (e.g. `frontend/atlas.html` states its numbers are placeholders).
+- **The eight-event vocabulary is fixed.** The frontend may not invent event names; it emits exactly
+  the eight names declared in `SQ.EVENT_NAMES` (`frontend/assets/js/core.js`).
+- **The event stream is the seam.** Any driver — mock, live, or a captured replay — talks to the UI
+  only by calling `ingest(type, payload)`. Nothing else may mutate the console.
+
+---
+
+## 2. The static tier: file layout
+
+The shipped frontend is a flat set of pages plus three asset trees.
+
+```
+frontend/
+  *.html                      top-level pages (the staging seed set)
+  _headers                    Cloudflare Pages header rules (see §12)
+  HANDOFF.md                  the frontend design/handoff document
+  assets/
+    css/                      stylesheets
+    js/
+      core.js                 SQ namespace: rng, scene synthesis, policy router,
+                              event names, mock run driver, shared components
+      live.js                 the real HTTP ingestion client (assets + infer)
+      mission.js              the Analyze console driver (PREVIEW + LIVE)
+      run.js                  the captured-run ("Anatomy of a Run") driver
+      <page drivers>          per-page behaviour
+    data/
+      anatomy-run.js          the captured real ResultEnvelope (sanitized)
+    img/                      real EO imagery (eo/…), plates, thumbnails
+    video/                    the launch film and clips
+    fonts/                    webfonts
+```
+
+Two facts about this layout matter for deployment:
+
+1. The **staging seed** is the set of top-level `frontend/*.html` files
+   (`scripts/stage_pages.mjs`). Pages are discovered from HTML, and then their reference closure
+   (CSS `@import`/`url()`, JS `import`/`export … from`, and dynamic imports) is walked so that only
+   referenced assets ship.
+2. Because the closure is reference-driven, **an asset that is not referenced by a reachable page
+   does not ship**. This is deliberate: it keeps the uploaded tree small and it makes dead assets
+   visible (they simply do not appear in the staged tree report).
+
+---
+
+## 3. The eleven pages
+
+Eleven HTML pages ship. Each was read for this chapter. The table gives the page's purpose and its
+`data-view` (the attribute each page's `<body>` carries, which the CSS uses to scope page-specific
+rules).
+
+| # | File | Purpose | Notes |
+|---|---|---|---|
+| 1 | `frontend/index.html` | Homepage / front door. Orbit hero, invitation form, open questions, essay film, discover/evidence/understand/measure/atlas sections. | Carries the launch video and the delta pair. |
+| 2 | `frontend/mission.html` | **The Analyze console.** Query box, two upload widgets, intent panel, viewer, comparison, answer, evidence, confidence, provenance, trace bar, event drawer. | The **only** live-calling page. Carries `<meta name="satquery-api-base">`. |
+| 3 | `frontend/architecture.html` | Architecture tour: how a query becomes an answer, stage by stage. | Footer discloses that its transmission is driven by the prototype mock event stream. |
+| 4 | `frontend/run.html` | **Anatomy of a Run** — renders a real captured `ResultEnvelope` (`run_d124d8b9adea`). | Driven by `frontend/assets/js/run.js` over `frontend/assets/data/anatomy-run.js`. |
+| 5 | `frontend/benchmark.html` | Benchmark page: measured results with an evidence-state legend. | Legend vocabulary: VERIFIED / SUPPORTED / UNVERIFIED / BLOCKED / NOT RUN. |
+| 6 | `frontend/research.html` | Research notes: methods, calibration, honest caveats. | Links into the measurement story. |
+| 7 | `frontend/journey.html` | The build journey / narrative page. | Carries the HF + GitHub header links. |
+| 8 | `frontend/atlas.html` | Atlas of four real EO thumbnails. | Page states its numbers are placeholders. |
+| 9 | `frontend/references.html` | References / citations page. | — |
+| 10 | `frontend/video.html` | Video library: four clips, three planned shorts named. | — |
+| 11 | `frontend/404.html` | Not-found page. | Prose says "Ten pages exist" but links five — drift, recorded in §13. |
+
+### 3.1 Page-by-page detail
+
+**`index.html` (homepage).** 424 lines. Structure: a navigation bar carrying the GitHub and Hugging
+Face links; an orbit hero using `assets/img/eo/nile-wide.jpg`; an invitation form whose action is
+`mission.html`; an "open questions" list containing three `mission.html?q=…` links (so a visitor can
+land in the Analyze console with a question pre-filled); an essay-film section using
+`assets/video/satquery-launch-50s.mp4` with eight `data-chapters` markers; an "ask" section using
+`assets/img/eo/delta-plain.jpg`; a "discover" section that presents the **delta-growth t0/t1 pair** as
+a wipe slider (`delta-growth-t0-720` / `delta-growth-t1-720`); an "evidence" section using
+`delta-growth-t2-2075.jpg`; an "understand" section listing six layers; a "measure" section with
+benchmark and research cards; and an "atlas" section with four real EO thumbnails. The footer notes
+name the event span `QUERY_RECEIVED` → `RESULT_ASSEMBLED`, i.e. the first and last of the eight
+events.
+
+**`mission.html` (Analyze console).** 297 lines. This is the page this chapter spends most of its
+length on; see §5.
+
+**`architecture.html`.** The architecture tour. It walks the reader from a natural-language query
+through routing, planning, specialists, evidence, confidence, and result assembly. Its footer makes
+an explicit honesty disclosure: the transmission shown on the page is driven by the **prototype mock
+event stream**, not by a live run. That disclosure is the page doing the right thing — the animation
+is real UI driven by the same eight-event seam, but the data behind it on this page is the mock
+driver's.
+
+**`run.html` ("Anatomy of a Run").** Renders a **real captured** envelope. See §9.
+
+**`benchmark.html`.** Presents measured results. It carries an evidence-state legend whose
+vocabulary is VERIFIED / SUPPORTED / UNVERIFIED / BLOCKED / NOT RUN, and it notes the measured
+reliability curve. Per `release/DOCS_STYLE_GUIDE.md` §3, this page is the right place for the
+per-artifact numbers (grounding under two protocols, change IoU, optical-SAR accuracy-with-macro-F1,
+change-VQA two test sets, router validation-only), and it must never present them as a system-level
+score.
+
+**`research.html`.** Research notes: method, calibration, and caveats. This is where the calibration
+result belongs, and per the style guide it must be stated correctly: ECE went **0.013755 → 0.014929
+— worse**, and the transform is retained only because it is in the frozen config.
+
+**`journey.html`.** Narrative page for the build process.
+
+**`atlas.html`.** Four real EO thumbnails. The page states in its own prose that its numbers are
+placeholders. That statement is correct and must be preserved: the atlas is a *gallery*, not a
+measurement.
+
+**`references.html`.** Citations.
+
+**`video.html`.** Lists four clips and names three planned shorts. The planned shorts are labelled as
+planned, not shipped.
+
+**`404.html`.** The not-found page. Its prose says "Ten pages exist" while eleven do, and it links
+five. This is documentation drift inside a shipped page; it is recorded here and in §13 rather than
+silently corrected, because correcting it would be an edit outside this chapter's scope.
+
+### 3.2 The Hugging Face header link — present on all eleven pages
+
+Every one of the eleven pages carries, in its navigation, both:
+
+- a **GitHub** link to `https://github.com/Anish-lab-blip/SatQuery-AI`, and
+- a **Hugging Face** link to `https://huggingface.co/thundercode/SatQuery`.
+
+This was verified by searching all `frontend/*.html` for `huggingface.co` and `github.com` and
+confirming a match in each of: `index`, `journey`, `mission`, `404`, `video`, `atlas`,
+`architecture`, `benchmark`, `run`, `research`, `references` — eleven files, eleven matches each.
+`docs/FINAL_DELIVERY_TODO.md` records this as a post-handoff sprint outcome ("the HF link on all 11
+pages").
+
+The reason this is called out as its own subsection: the public release is *GitHub + Hugging Face*,
+and the requirement that the HF link appear on **all** pages (not just the homepage) is a delivery
+requirement, so it is stated as a verified fact with the method of verification.
+
+---
+
+## 4. Staging and deploy path
+
+### 4.1 `scripts/stage_pages.mjs` — the reference-closed staging tool
+
+`scripts/stage_pages.mjs` is 378 lines and is the tool that turns the working `frontend/` directory
+into a deployable tree. It is deliberately conservative.
+
+**Constants.**
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `PAGES_FILE_LIMIT` | `26214400` (25 MiB) | Cloudflare Pages per-file hard limit. |
+| `BIG_WARN_BYTES` | `10485760` (10 MiB) | Warn threshold for a large file. |
+
+**Reference extraction.** The tool uses a small set of regexes to find references inside each file
+type:
+
+- `RE_HTML` — HTML references (`<script src>`, `<link href>`, `<img src>`, etc.)
+- `RE_CSS_IMPORT` — CSS `@import`
+- `RE_CSS_URL` — CSS `url(...)`
+- `RE_JS_IMPORT` — JS `import … from`
+- `RE_JS_EXPORT` — JS `export … from`
+- `RE_JS_DYN` — JS dynamic `import(...)`
+
+Supporting helpers: `stripComments()` (so a reference inside a comment does not become a false
+edge), `extractRefs()`, `isExternal()` (absolute URLs and protocol-relative URLs are not followed),
+`stripQueryHash()` (so `app.js?v=2` resolves to `app.js`), and `insideFrontend()` (a guard so a
+reference cannot escape the `frontend/` root).
+
+**Algorithm.**
+
+1. **Seed.** Take the set of top-level `frontend/*.html` files.
+2. **Closure walk.** For each file in the frontier, extract its references, resolve each to a
+   path inside `frontend/`, and add the new ones to the frontier. Repeat until the frontier is empty.
+3. **Copy.** Copy every file in the closure into the output root, preserving relative paths.
+4. **Size gate.** If any file exceeds `PAGES_FILE_LIMIT` (25 MiB), hard-fail with **exit code 2**.
+   Files above `BIG_WARN_BYTES` (10 MiB) produce a warning.
+5. **Verify.** Re-walk the *staged* tree and confirm the closure is intact (no dangling reference).
+   Failure is **exit code 3**.
+6. **Report.** Print four report blocks:
+   - `=== STAGED TREE ===`
+   - `=== REFERENCE INTEGRITY ===`
+   - `=== EXTERNAL DEPENDENCY AUDIT ===` — prints `HERMETIC` when zero network dependencies are
+     found.
+   - `=== OPTIONS APPLIED ===`
+7. **Hint.** Print the deploy command to run next:
+   `npx wrangler pages deploy "<OUT_ROOT>" --project-name <name>`.
+
+**Why the exit codes matter.** A staging run that silently produced an incomplete tree would deploy
+a broken site; a staging run that silently produced an over-limit tree would deploy a site that
+Cloudflare rejects. The tool therefore fails loudly *before* upload (exit 2 for size, exit 3 for
+integrity) rather than letting `wrangler` discover the problem.
+
+**Argument parsing.** `parseArgs()` handles the CLI surface and `usage()` prints help. The tool is
+invoked as a Node script (`node scripts/stage_pages.mjs …`).
+
+### 4.2 The deploy command
+
+The tool's own final hint is the deploy step:
+
+```
+npx wrangler pages deploy "<OUT_ROOT>" --project-name <name>
+```
+
+Deployment is therefore: **stage to a directory → `wrangler pages deploy` that directory**. There is
+no compile step between the two. The deployed frontend HEAD recorded in the delivery documents is
+`2d7ae53b482d` (`docs/FINAL_DELIVERY_TODO.md`, `release/DOCS_STYLE_GUIDE.md` §3).
+
+> **Superseded-topology note.** `docs/DEPLOYMENT_ARCHITECTURE.md` opens with a superseded-topology
+> banner, and its body still names Railway / HF-Space hosts while the active topology is
+> Render / Codespace (`docs/DEPLOYMENT_TOPOLOGY.md`). For the frontend specifically, the host is
+> Cloudflare Pages in both readings; the drift concerns the *backend* hosts, not the static tier.
+
+---
+
+## 5. The Analyze console (`frontend/mission.html`) in depth
+
+The Analyze console is the frontend's centre of gravity. This section documents its markup (every
+handle), its state machine, its two drivers, and its event rendering.
+
+### 5.1 Markup and DOM handles
+
+`frontend/mission.html` is 297 lines. Its `<head>` carries the live API base:
+
+```html
+<meta name="satquery-api-base" content="https://satquery-backend-m4yv.onrender.com">
+```
+
+That meta tag is the second entry in the API-base resolution order (see §5.4). The page loads three
+scripts, in order:
+
+```html
+<script src="assets/js/core.js"></script>
+<script src="assets/js/live.js"></script>
+<script src="assets/js/mission.js"></script>
+```
+
+`core.js` defines the `SQ` namespace and the mock driver; `live.js` defines the real HTTP client;
+`mission.js` is the page driver that decides which of the two to use. The load order is significant:
+`mission.js` runs last because it consumes both.
+
+The console's handles, by region:
+
+**Query and run.**
+
+| Handle | Role |
+|---|---|
+| `#qtext` | The natural-language query input. |
+| `#btnRun` | The Run button. |
+| `#runid` | Displays the run identifier for the current run. |
+
+**Observation / upload.**
+
+| Handle | Role |
+|---|---|
+| `#obsTail` | The observation status tail. Its **initial text content is `none`** — i.e. no asset loaded yet. |
+| `#dropZone` | The drop target for a file. |
+| `#fileInput` | The primary file input (the single observation). |
+| `#obsNote` | The note under the observation widget. |
+
+**Metadata.**
+
+| Handle | Role |
+|---|---|
+| `#metaHost` | Container for the metadata readout. |
+| `#mFile` | Metadata: file name. |
+| `#mAcq` | Metadata: acquisition date (one of the `#m*` fields inside `#metaHost`). |
+| `#metaEmpty` | The empty-state placeholder for the metadata block. |
+
+**Intent panel.**
+
+| Handle | Role |
+|---|---|
+| `#intentTail` | Intent status tail. |
+| `#intentHost` | Container for the parsed intent (task, assets, route). |
+| `#pairTail` | Pair status tail (for the two-asset change tasks). |
+| `#pairNote` | Note under the pair widget. |
+| `#fileInputT0` | The **second** file input — the `t0` (before) image for paired tasks. |
+
+**Viewer.**
+
+| Handle | Role |
+|---|---|
+| `#vbtns` | Viewer mode buttons. |
+| `#viewerState` | Viewer state label. |
+| `#plate` | The plate container. |
+| `#plateImg` | The plate image; its `src` is `assets/img/eo/reservoir-low.jpg`. |
+| `#ev` | The evidence overlay layer on the plate. |
+| `#evNote` | Note under the evidence overlay. |
+| `#plateCreditLead` | Plate credit lead-in text. |
+| `#plateCredit` | Plate credit text. |
+
+**Comparison (paired tasks).**
+
+| Handle | Role |
+|---|---|
+| `#cmpWrap` | Comparison wrapper. |
+| `#cmpT0` | The t0 pane. |
+| `#cmpT1` | The t1 pane. |
+| `#cmpRange` | The comparison range/slider control. |
+| `#cmpCredit` | Comparison credit. |
+| `#cmpEmpty` | Comparison empty state. |
+
+**Answer.**
+
+| Handle | Role |
+|---|---|
+| `#answerHost` | Container for the rendered answer. |
+| `#ansTail` | Answer status tail. |
+
+**Evidence.**
+
+| Handle | Role |
+|---|---|
+| `#evHost` | Container for the evidence list. |
+| `#evEmpty` | Evidence empty state. |
+| `#evTail` | Evidence status tail. |
+
+**Confidence.**
+
+| Handle | Role |
+|---|---|
+| `#confHost` | Container for the confidence readout. |
+| `#confC` | The confidence value. |
+| `#confNote` | Note under the confidence value. |
+
+**Provenance.**
+
+| Handle | Role |
+|---|---|
+| `#provHost` | Container for provenance. |
+| `#pRun` | Provenance: run id. |
+| `#pPolicy` | Provenance: policy. |
+| `#pProtocol` | Provenance: protocol. |
+| `#pSchema` | Provenance: schema version. |
+
+**Report and trace.**
+
+| Handle | Role |
+|---|---|
+| `#btnReport` | The report button. |
+| `#ctrace` | The trace container. |
+| `#traceNow` | The "now" label on the trace bar. |
+| `#trace` | The trace bar (the element whose width is animated). |
+| `#traceNote` | Note under the trace bar. |
+
+**Event drawer.**
+
+| Handle | Role |
+|---|---|
+| `#drawer` | The event-log drawer. |
+| `#evlog` | The event log list. |
+| `#btnClose` | Close-drawer button. |
+| `#btnEvents` | Open-drawer button. |
+
+### 5.2 The intent panel
+
+The intent panel (`#intentHost`, `#intentTail`) is rendered by `renderIntent()` in
+`frontend/assets/js/mission.js`. It shows the *interpreted* query: which task the router chose, which
+assets the task requires, and which route (live vs mock) will be taken.
+
+The interpretation itself is `interpret()` in `mission.js` — a lexical router that runs in the
+browser. Its notable features, as read from the file:
+
+- a change stem `/chang/` (no `\b` word boundary) so "change"/"changed"/"changes" all match;
+- a `newAsChange` rule so phrasing like "new …" can be read as a change request;
+- a caption regex for caption/describe phrasings.
+
+`interpret()` is deliberately simple and deterministic. It exists so the console can show the user a
+*reason* for the task it is about to run, and so the console can decide which file inputs are
+relevant. It is **not** the server-side router: the server has its own deterministic policy planner
+(see the `SERVING.md` chapter and `core/controller.py`). The browser-side `interpret()` is a UI
+affordance; the authoritative routing decision is the server's, and the console renders what the
+server returns.
+
+### 5.3 Task selection and asset requirements
+
+`mission.js` maps the interpreted intent onto a server task name via `ROUTE_TASK_TO_SERVER`. The
+paired tasks are declared in `PAIRED_TASKS`:
+
+```js
+PAIRED_TASKS = { change, change_vqa, optical_sar }
+```
+
+These three tasks need **two** assets (a before/after pair), which is why the console has a second
+file input (`#fileInputT0`) and a comparison region (`#cmpWrap`). When a paired task is selected but
+only one asset is available, the console falls back to a single-asset task via
+`SINGLE_ASSET_FALLBACK = 'vqa'`. This is a UI-level fallback: rather than failing the run, the
+console narrows the request to something one image can answer.
+
+For optical-SAR there is a dedicated precondition check, `validateOpticalSar()`, because that task
+has modality-specific requirements. `assetsForTask()` assembles the asset list the chosen task needs.
+
+### 5.4 API-base resolution
+
+`frontend/assets/js/live.js` defines the resolution order for the API base in
+`SQ.live.baseUrl()`:
+
+1. `window.SATQUERY_API_BASE` (a runtime override, useful for testing), then
+2. `<meta name="satquery-api-base">` (the page's declared base — on `mission.html` this is
+   `https://satquery-backend-m4yv.onrender.com`), then
+3. the default `/api` (a same-origin path).
+
+`_normalizeBase()` normalises trailing slashes, and `SQ.live.url()` composes the final URL.
+`SQ.ENDPOINTS` names the four endpoints the client talks to:
+
+```js
+SQ.ENDPOINTS = { assets: '/assets', infer: '/infer', capabilities: '/capabilities', health: '/health' }
+```
+
+With the default `/api` base these resolve to `/api/assets`, `/api/infer`, `/api/capabilities`, and
+`/api/health`. On the deployed configuration the base is the Render orchestrator host, which is the
+`/api/*` mirror of the four-endpoint contract (see the `SERVING.md` chapter).
+
+### 5.5 Upload widgets
+
+Two file inputs exist: `#fileInput` (primary) and `#fileInputT0` (the before image for paired
+tasks). Both are wired through `handleFile()` in `mission.js`, and both feed
+`SQ.live.uploadAsset()` in `live.js`.
+
+`live.js` declares the accepted content types:
+
+```js
+SQ.CONTENT_TYPES = { tif, tiff, png, jpg, jpeg }
+```
+
+and maps a file to its MIME type via `SQ.contentTypeFor()`. The upload is a **raw-bytes POST with a
+`Content-Type` header** — not a multipart form. This mirrors the server contract: `POST /v1/assets`
+takes the file as the request body with its content type in the header, and `POST /v1/analyze` takes
+JSON (multipart is explicitly *not* implemented — see `docs/API_CONTRACT.md` §2.4 and the `SERVING.md`
+chapter).
+
+`uploadAsset()` asserts that the response contains an `asset_id`; `uploadAssets()` uploads a list
+**sequentially** (so the second upload cannot race the first). The returned `asset_id` is an opaque
+handle — the client never parses it, it only passes it back. The asset store's TTL and the fact that
+handles are ephemeral are documented in `SERVING.md`.
+
+### 5.6 The observation tail: `none` → ready
+
+`#obsTail` starts with text content `none`. When an asset is uploaded successfully, the tail is
+updated to a ready state. This is the console's way of making the *precondition* for a run visible:
+a query can be typed at any time, but a run that requires an asset cannot produce evidence until an
+asset is present. The `#obsNote` field carries the supporting note.
+
+### 5.7 The Run button, `#runid`, and `#answerHost`
+
+Pressing `#btnRun` calls `runQuery()` in `mission.js`. `runQuery()` decides between the two drivers
+(§6) and then dispatches. `#runid` is populated with the run identifier the service returns
+(`run_…`); `#answerHost` receives the rendered answer.
+
+### 5.8 The trace bar and the eight events
+
+The console's most load-bearing UI element is the trace bar. It is driven entirely by the eight
+execution events.
+
+**The eight event names** are declared once, in `frontend/assets/js/core.js`:
+
+```js
+SQ.EVENT_NAMES = [
+  'QUERY_RECEIVED',
+  'QUERY_UNDERSTOOD',
+  'ROUTE_SELECTED',
+  'SPECIALIST_STARTED',
+  'SPECIALIST_COMPLETED',
+  'EVIDENCE_GENERATED',
+  'CONFIDENCE_COMPUTED',
+  'RESULT_ASSEMBLED'
+]
+```
+
+(Declared at `core.js:616–620`.) These names are the protocol between any driver and the UI. The
+`architecture.html` footer's disclosure — that its transmission is driven by the mock event stream —
+is a statement about *which driver* feeds these names, not about the names themselves.
+
+**The nine UI states.** `mission.js` declares `STATES` (nine `ControllerState` values) and maps each
+event to a state via `EVENT_TO_STATE`, with per-state explanatory text in `STATE_NOTE`. Nine states
+over eight events is not an inconsistency: there is a state for "idle / not started" plus the eight
+event-driven states.
+
+**The fill formula.** `markState()` sets the trace bar width with:
+
+```js
+traceFill.style.width = ((traceProgress + 0.5) / STATES.length) * 100 + '%'
+```
+
+With eight events completed against nine states, the final fill is
+`((8 + 0.5) / 9) × 100` = **94.4444 %**. This is why the delivery documents record the trace fill as
+94.4444 %: it is the arithmetic consequence of the formula, not a measurement of a rendering. The
+`+ 0.5` means the bar advances *half a step* on entry to each state, so a completed eight-event run
+lands at 8.5/9 rather than 8/9 or 9/9. The remaining 5.5556 % corresponds to the ninth state, which
+a completed run does not enter.
+
+`buildTrace()` constructs the trace bar's segments; `logEvent()` appends to the event log
+(`#evlog`); `resetUI()` clears the console back to its initial state (including resetting `#obsTail`
+to `none`).
+
+### 5.9 The event drawer
+
+`#drawer` is the event log, opened by `#btnEvents` and closed by `#btnClose`. `#evlog` is the list
+itself. Each event appended by `logEvent()` records the event type and its payload summary, so a
+reader can see the full ordered sequence rather than only the current state. The drawer is what makes
+the "0 mock nodes" / "9 preview nodes" distinction auditable by a human: the live driver's log
+contains no mock nodes; the preview driver's log contains nine.
+
+---
+
+## 6. REAL vs PREVIEW: two drivers, one event seam
+
+`mission.js` opens with the comment "TWO DRIVERS, ONE EVENT SEAM". That is the whole design: two
+driver implementations, one `ingest()` seam, one UI.
+
+### 6.1 The seam
+
+`SQ.run(opts)` in `core.js` owns an `ingest()` switch (lines ~742–788) that dispatches each of the
+eight event types to the UI handlers. Any driver that wants to drive the console calls
+`ingest(type, payload)`; it does not touch the DOM. The console boot sequence builds the engine with
+`engine = SQ.run(...)`, then calls `runMock(QUERY)` to paint an initial state, then
+`loadCapabilities()` to fetch the service's capability block.
+
+### 6.2 PREVIEW (`runMock`)
+
+`runMock()` is the **preview** driver. Its properties, as read from `mission.js` and `core.js`:
+
+- It emits **empty payloads** — the payloads carry the shape of the data but not real values, because
+  there is no real run behind it.
+- It labels the console as a preview (`is-mock`).
+- It emits **nine mock nodes** — the event log for a preview run contains nine mock nodes.
+- It drives the trace bar through the same `markState()` path, so the fill arithmetic is identical.
+
+`core.js`'s `startMock()` drives the sequence with `setTimeout` timings, so the preview is *animated*:
+each event arrives after a short delay, which is what makes the trace bar and the event drawer move.
+
+**What preview does not emit.** The preview driver emits **no specialist events** — i.e. no
+`SPECIALIST_STARTED` / `SPECIALIST_COMPLETED` for a real specialist. This is the honest distinction
+between the two paths: the preview can show the *envelope* of a run, but it cannot show a specialist
+that actually ran, because no specialist ran.
+
+### 6.3 REAL (`runLive`)
+
+`runLive()` is the **live** driver. Its properties:
+
+- It makes **real HTTP calls** via `SQ.live` (`live.js`).
+- It sets a `liveRun` flag.
+- It reads two response headers from `SQ.live.infer()`: `X-SatQuery-State` and
+  `x-satquery-transport`. The state header carries the controller's state (see the nine
+  `ControllerState` values); the transport header records how the response was carried (the tunnel
+  transport vs a direct/forwarded transport).
+- It translates failures with `translateError()` and, for upload/inference failures,
+  `SQ.live.describeFailure()` / `LiveError` in `live.js`.
+- A live run shows **0 mock nodes** — the event log contains no mock nodes at all.
+
+### 6.4 Why the 0-vs-9 distinction is the honesty test
+
+The delivery documents record that live validation produced **24 runs** (3 passes × 8 cases, 8/8 each)
+with **0 mock nodes**. That number is only meaningful because the preview path *does* produce mock
+nodes (nine of them). The console's event drawer therefore lets a reader distinguish, from the UI
+alone, whether what they are looking at is a real run or a preview. This is the frontend's
+contribution to the project's truthfulness discipline: the same eight-event vocabulary is used for
+both, and the drawer is what tells them apart.
+
+### 6.5 `loadCapabilities()` and `setMode()`
+
+`loadCapabilities()` calls `SQ.live.capabilities()` (i.e. `GET /api/capabilities` on the deployed
+base) and renders the capability block. `setMode()` switches the console between modes. Because
+capabilities are fetched live, the console can show which tasks are available *right now* on the
+deployed service — which matters because the deployed device is CPU and because some capabilities
+are gated on artifacts that may be absent (the `SERVING.md` chapter documents the capability adapter
+and the five-word vocabulary it emits).
+
+### 6.6 The test hook
+
+`mission.js` exposes `window.SQ_MISSION` as a test hook. It lets an automated harness drive the
+console (select a task, inject a file, press run) without synthesising DOM events. This is how the
+live validation runs in the delivery documents were executed against the page.
+
+### 6.7 `translateError()`
+
+`translateError()` maps a service error into human-readable text in the console. It is the frontend
+half of the error contract: the service returns a machine code and an HTTP status
+(`docs/API_CONTRACT.md` §5.1–§5.3; `gateway/policy.py` `_CODE_STATUS`), and the console turns that
+into a sentence a person can act on. The console does not invent codes; it renders the ones it
+receives. One consequence worth stating: a `422` from the service is *not* necessarily a validation
+failure of the user's data — see the G-1 annotation-scope defect in the `SERVING.md` chapter, where a
+`422 {"detail":[{"loc":["query","request"]}]}` is a *server-side* bug that masquerades as a client
+validation error. `translateError()` will render it as an error; only the backend fix removes it.
+
+---
+
+## 7. The captured-run page: "Anatomy of a Run" (`run.html`)
+
+`frontend/run.html` renders a **real captured** `ResultEnvelope`. This is the page that lets a reader
+inspect an actual run without running anything.
+
+### 7.1 The captured envelope
+
+The data lives in `frontend/assets/data/anatomy-run.js` (329 lines), assigned to
+`window.SATQUERY_ANATOMY_RUN`. Its header states the provenance:
+
+- `_source`: "Captured live 2026-09-25 … Sanitized".
+
+The fields that matter, all read from the file:
+
+| Field | Value |
+|---|---|
+| `run_id` | `run_d124d8b9adea` |
+| `task` | `grounding` |
+| `query` | "Where is the reservoir?" |
+| `answer` | "[grounding] Located 3 candidate region(s) … Highest objectness 0.61." |
+| `config_hash` | `78f1e3700da15aa1` |
+| `transport` | `tunnel` |
+| `intent.source` | `forced` |
+| plan | `step_001` grounding, `requires_assets` |
+| steps | 8 steps, `RECEIVE` → `RESPOND` |
+| `selected_models` | ViT-B-32 (RemoteCLIP path) → GroundingHead (`params=1052677`) |
+| evidence | 4 items: 3 `bounding_box` + 1 `statistic` |
+| regions | 3 (`region_1cd3973de749`, …) |
+| confidence | raw `0.5231253252136926` / calibrated `0.5236623182649384` (`temperature_scaling`) |
+| calibration component | `temperature: 0.9772731820958189`, `calibration_samples: 16441.0` |
+| timings | `step_001: 209.873` |
+| geospatial | 730×730, `has_crs false` |
+| warnings | 2 — no CRS; contradictory spatial claims |
+
+### 7.2 How the page renders it
+
+`frontend/assets/js/run.js` (380 lines) is the driver. It reads `window.SATQUERY_ANATOMY_RUN` and
+exposes the envelope through a set of named views: `QUERY`, `TASK`, `RUN_ID`, `MODELS`, `EVIDENCE`,
+`CONF`, `TIMINGS`, `GEO`, `INTENT`, `PLAN`, `HASH`, `PLATE`.
+
+- `REGIONS` is built from `A.regions`, so the three captured regions drive the plate overlays.
+- `paintAll()` loads the **real plate image** and clears the `t0` and `diff` layers (this run has no
+  before/after pair, so those layers are empty rather than faked).
+- `buildEvidence()` renders the four evidence items; `evCandidates()`, `evLock()`, and
+  `evConfirmed()` render the three stages of the evidence story (candidates → locked → confirmed).
+- `SPECIALISTS_FOR_TASK` maps the task to the specialists that would run, so the page can show the
+  specialist panel even though this run's only specialist is grounding.
+- `buildLattice()` builds the step lattice from the 8 captured steps.
+- `DATA` is a table of eight key/value views, one per stage, and **each entry names the event** that
+  corresponds to that stage — i.e. the captured page is wired to the same eight-event vocabulary.
+- `setStage()`, `resetEvidence()`, and `gotoStep()` drive the page as the reader scrolls or uses the
+  keyboard.
+
+### 7.3 What the page proves, and what it does not
+
+It **proves**: a real grounding run was captured, sanitized, and shipped with its full envelope —
+run id, task, query, answer, config hash, transport, intent source, plan, steps, selected models with
+parameter counts, evidence with types, regions, raw and calibrated confidence with the calibration
+component and sample count, timings, geospatial facts, and warnings. A reader can verify that the
+number shown as "confidence" on the page is a *calibrated* value with a documented temperature and a
+documented calibration-sample count.
+
+It **does not prove**: any system-level accuracy. One captured run is one run. Per
+`release/DOCS_STYLE_GUIDE.md` §3 there is **no end-to-end benchmark**, and this page does not create
+one. The calibrated confidence `0.5236623182649384` is a per-run confidence, not an accuracy.
+
+The two captured warnings are also part of the honest record: `has_crs false` (the imagery had no
+coordinate reference system) and "contradictory spatial claims". Both are shown rather than
+suppressed.
+
+---
+
+## 8. Benchmark, Research, and Lab pages
+
+The frontend has a measurement-facing tier whose job is to present numbers *with their status*.
+
+- **`benchmark.html`** carries the evidence-state legend: **VERIFIED / SUPPORTED / UNVERIFIED /
+  BLOCKED / NOT RUN**. It notes the measured reliability curve. This page is where the per-artifact
+  results live, and per the style guide each must be stated with its correct qualification:
+  grounding under **two protocols** (canonical 0.2838 / matched6 0.2566) and **two decode variants**
+  (head_argmax 0.1215, zero-shot 0.0972) — never one alone; optical-SAR accuracy **0.931 with
+  macro-F1 0.434161**, ruling **OPEN**; change-VQA **two** test sets (test 0.697626/0.378373 and
+  test2 0.651469/0.372309), ruling **OPEN**; router **0.965116 = validation, ungated, n = 86**, test
+  split **NOT RUN**; the VLM adapter **usable** (exact_match 0.963) but **ACCEPTANCE-REJECTED**.
+- **`research.html`** carries the method and caveat material, including the calibration result stated
+  correctly: ECE **0.013755 → 0.014929 — worse**.
+- **The Lab page.** The brief for this chapter names a "Lab" page. `frontend/HANDOFF.md` §12 gives the
+  file map, and the eleven shipped pages are enumerated in §3 above. A page named "Lab" is **not**
+  among the eleven HTML files read for this chapter. The nearest things are the Analyze console
+  (`mission.html`) and the captured-run page (`run.html`), which are the pages where a reader can
+  "do" or "inspect" work. Whether a page named "Lab" existed at any point and was renamed or dropped
+  is `UNKNOWN — not established from the available evidence`.
+
+---
+
+## 9. The Hugging Face header link (delivery requirement)
+
+Stated separately because it is a delivery requirement with a verification method. See §3.2: the
+Hugging Face link `https://huggingface.co/thundercode/SatQuery` and the GitHub link
+`https://github.com/Anish-lab-blip/SatQuery-AI` are present in the navigation of **all eleven**
+pages, verified by searching every `frontend/*.html` for both hostnames.
+
+---
+
+## 10. Cache-busting behaviour
+
+The frontend uses **URL-versioned assets** plus **header rules** to control caching. The header rules
+live in `frontend/_headers` (a Cloudflare Pages file), and the versioning is visible in the markup.
+
+### 10.1 The `_headers` rules
+
+`frontend/_headers` declares:
+
+| Path pattern | Rule |
+|---|---|
+| `/*` | Baseline security headers: `X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options`, `Cross-Origin-Opener-Policy`. |
+| `/` and `/*.html` | Revalidate. |
+| `/assets/video/*` | `max-age=604800` (7 days). |
+| `/assets/fonts/*` | `max-age=31536000` (1 year). |
+| `/assets/css/*` | `public, max-age=0, must-revalidate`. |
+| `/assets/js/*` | `public, max-age=0, must-revalidate`. |
+| `/assets/img/*` | `max-age=604800` (7 days). |
+
+### 10.2 The rule that matters for correctness
+
+**JS and CSS are served `public, max-age=0, must-revalidate`.** That is the safe setting for code:
+the browser may cache a copy but must revalidate before using it. This is what makes a code change
+take effect without asking users to hard-refresh. Images, fonts, and video get long lifetimes because
+they are content, not logic — and because a *changed* image is given a **new URL** rather than
+overwriting the old one.
+
+### 10.3 The delta-growth pair as the worked example
+
+`frontend/_headers` itself carries a note that the delta-growth image pair was given **new URLs**
+when it changed (`delta-growth-t0-720` / `delta-growth-t1-720`, referenced from `index.html`). That is
+the correct pattern for a long-cached asset: change the URL, keep the long `max-age`. The homepage's
+wipe slider uses that pair, and the "evidence" section uses `delta-growth-t2-2075.jpg` — a third URL
+in the same family.
+
+---
+
+## 11. Cloudflare platform traps
+
+Two Cloudflare behaviours shape this frontend. Both are recorded because a future maintainer will hit
+them.
+
+### 11.1 `_headers` rules CONCATENATE (they do not override)
+
+This is the single most surprising Cloudflare Pages behaviour in this project, and
+`frontend/_headers` documents it **verbatim in a comment inside the file**. The rule is: when more
+than one `_headers` rule matches a path, Cloudflare **concatenates** the header values rather than
+letting the more specific rule override the more general one.
+
+The practical consequence: if two rules both set `Cache-Control`, the client receives **two**
+`Cache-Control` values. Chromium honours the **first** `max-age` it sees. So a broad rule that sets
+`max-age=0` and a specific rule that sets `max-age=604800` do not "resolve" to the specific one — the
+client sees both, in order, and takes the first.
+
+`docs/FINAL_DELIVERY_TODO.md` §1.7 lists this as known blocker item 9. The mitigation, as evidenced
+by the shipped `_headers`, is to **scope the patterns so that they do not overlap** where the value
+must be exact — i.e. write one rule per asset tree rather than a general rule plus an override. The
+`/assets/js/*` and `/assets/css/*` rules are separate from `/assets/img/*` precisely so that each
+tree has exactly one matching rule and there is nothing to concatenate.
+
+### 11.2 The 308 `.html` → extensionless redirect
+
+Cloudflare Pages issues a **308** redirect from a path that ends in `.html` to the extensionless
+path: a request for `/run.html` redirects to `/run`. A 308 preserves the method (unlike 301/302 in
+some clients), so a `POST` is not silently turned into a `GET`, but the redirect still happens and the
+final URL differs from the requested one.
+
+The second, related trap is the **trailing-slash 307**: Starlette's `redirect_slashes` behaviour
+issues a **307** when a request's trailing slash does not match the route. This is documented for the
+*API* in `docs/API_CONTRACT.md` §5.1 as a footgun, and it matters to the frontend because the
+frontend is the caller: `SQ.live.url()` and `_normalizeBase()` exist partly to make the client's URL
+composition predictable so that the client is not relying on a redirect to reach an endpoint.
+
+Both traps share a lesson: **the frontend must link to the canonical URL.** A page that links to
+`/run` (extensionless) never triggers the 308; a page that links to `/run.html` does.
+
+---
+
+## 12. Accessibility and UX caveats
+
+This section states what can be established from the files read, and marks the rest.
+
+### 12.1 What is established
+
+- **Keyboard driving exists on the captured-run page.** `run.js` supports keyboard input to move
+  between steps (`gotoStep()` plus key handling), so `run.html` is operable without a mouse.
+- **Reduced-motion and focus styling** are governed by the token system in `frontend/HANDOFF.md` §2
+  (CSS custom properties on `:root`). The handoff document is the design authority for the token
+  layer.
+- **The event drawer is a named, focusable pair of controls** (`#btnEvents` / `#btnClose`) with a
+  labelled region (`#drawer` → `#evlog`), so the event log is not hover-only.
+- **The upload widgets are real `<input type="file">` elements** (`#fileInput`, `#fileInputT0`),
+  which are natively keyboard- and screen-reader-operable, and they are paired with a `#dropZone`
+  for pointer drag-and-drop. Drag-and-drop is an *addition* to the file input, not a replacement.
+
+### 12.2 What is not established
+
+- **A formal accessibility audit** (axe / Lighthouse / WCAG conformance level) has not been
+  performed: `UNKNOWN — not established from the available evidence`.
+- **Contrast ratios** for the token palette: `UNKNOWN — not established from the available evidence`.
+- **Screen-reader behaviour** of the trace bar's animated width (whether a live region announces each
+  state transition): `UNKNOWN — not established from the available evidence`. The trace bar is a
+  visual affordance driven by `markState()`; whether its state changes are announced is not
+  determinable from the code read.
+- **Mobile/responsive breakpoints** beyond what the CSS declares: `UNKNOWN — not established from the
+  available evidence`.
+- **The 404 page's page count** is stale: `404.html` says "Ten pages exist" and links five, while
+  eleven ship. This is drift, recorded here and not silently repaired.
+
+---
+
+## 13. Documentation drift recorded (not propagated as current truth)
+
+Per the project's practice (mirrored from `P10-T02`), drift found during this chapter's research is
+recorded honestly rather than smoothed over:
+
+| Location | Stale claim | Correct current statement |
+|---|---|---|
+| `frontend/_headers` comment | "100% static, zero network calls" | Ten of eleven pages are hermetic; `mission.html` calls the live service. |
+| `frontend/404.html` prose | "Ten pages exist" (links five) | Eleven pages ship. |
+| `frontend/mission.html` / `_headers` relationship | (implicit) | The live API base is declared in `<meta name="satquery-api-base">`, which is a *live* dependency the hermeticity audit must be read as exempting. |
+
+None of these is a code defect; each is a documentation statement inside a shipped file that no
+longer matches the tree. They are listed so a reader is not misled by them.
+
+---
+
+## 14. What the frontend does NOT do
+
+Stated explicitly, because the depth of §5–§7 could otherwise imply more capability than exists:
+
+- **No framework and no build step for application code.** Pages are hand-written HTML plus ES
+  modules; `scripts/stage_pages.mjs` copies, it does not compile.
+- **No client-side model inference.** The browser never runs a model. All inference happens on the
+  service (`POST /api/infer` → the tunnel → the inference service).
+- **No multipart upload.** Uploads are raw-bytes POSTs with a `Content-Type` header, matching the
+  server contract (`docs/API_CONTRACT.md` §2.4: multipart is *not* implemented).
+- **No streaming.** There is no server-sent-events or websocket channel. The eight events are
+  *client-side UI states*; on a live run they are derived from the single inference response (plus
+  the two response headers `X-SatQuery-State` and `x-satquery-transport`), not pushed from the
+  server. (See the `SERVING.md` chapter: the service does not stream.)
+- **No authentication UI.** The service has no auth (`docs/API_CONTRACT.md` §7), so there is no login.
+- **No persistence of runs.** Nothing in the frontend stores a run; the console's state is in-memory,
+  and the captured-run page reads a static data file.
+- **No offline mode** beyond the fact that ten pages need no network.
+
+---
+
+## 4.3 The staging tool in detail: closure algorithm and report format
+
+This subsection expands §4.1 because the staging tool is the *only* build-like step in the frontend
+and its behaviour determines what ships.
+
+### 4.3.1 Why a closure walk instead of "copy the directory"
+
+Copying `frontend/` wholesale would ship unreferenced assets: draft images, superseded JS, experiment
+files. A closure walk ships exactly the transitive set of files reachable from the eleven seed pages.
+The consequences are worth stating precisely:
+
+- **Adding a page is a deliberate act.** Because the seed set is `frontend/*.html` (top level only),
+  a page placed in a subdirectory is *not* a seed. It ships only if a seed page references it.
+- **Removing a reference removes a file from the deploy.** If the last page that used
+  `assets/img/eo/old.jpg` stops referencing it, that image silently stops shipping. This is a feature
+  (smaller tree) and a hazard (an asset can disappear without an error) — which is exactly why the
+  tool prints the staged tree and the integrity report, so the disappearance is visible in the build
+  log rather than only in production.
+- **Query strings and hashes are normalised away.** `stripQueryHash()` means `app.js?v=3` and
+  `app.js` are the same edge, so versioned references do not create phantom files.
+- **External URLs are not followed.** `isExternal()` stops the walk at `https://…` and `//…`, which
+  is why the external-dependency audit can report `HERMETIC`: any external URL that *was* followed
+  would show up as a network dependency.
+- **References cannot escape the root.** `insideFrontend()` rejects a resolved path that leaves
+  `frontend/`, so a stray `../../secret` reference cannot pull a file from outside the tree.
+
+### 4.3.2 The four report blocks
+
+The tool prints four blocks. Reading them in order answers the four questions a deployer has.
+
+1. `=== STAGED TREE ===` — *what will be uploaded?* A listing of every file copied into the output
+   root, with sizes. Files over `BIG_WARN_BYTES` (10 MiB) are flagged.
+2. `=== REFERENCE INTEGRITY ===` — *is the closure complete?* The staged tree is re-walked and every
+   reference must resolve inside it. A dangling reference fails with exit code 3. This is the check
+   that catches the case where a file was referenced but not copied (e.g. because of a
+   case-sensitivity difference between the developer's filesystem and Linux).
+3. `=== EXTERNAL DEPENDENCY AUDIT ===` — *is the site hermetic?* External URLs found in the closure
+   are listed. When the list is empty the block prints `HERMETIC`. This is the check that keeps the
+   "ten of eleven pages are hermetic" claim honest: if a page gained a CDN script, the audit would
+   stop printing `HERMETIC`.
+4. `=== OPTIONS APPLIED ===` — *what flags were used?* The effective options, so a build log is
+   self-describing.
+
+### 4.3.3 The two hard gates and their exit codes
+
+| Condition | Exit code | Why it is fatal |
+|---|---|---|
+| Any file exceeds `PAGES_FILE_LIMIT` (25 MiB) | **2** | Cloudflare Pages rejects a file over the limit; deploying would fail *after* upload. Failing before upload is cheaper and clearer. |
+| Staged tree fails reference-integrity re-walk | **3** | A dangling reference means a broken page in production. |
+
+The deliberate design choice is **fail before upload**. Both gates run locally, on the staged tree,
+before `wrangler` is invoked. A non-zero exit stops a shell pipeline (`&&`) before the deploy command
+can run.
+
+### 4.3.4 The deploy hint
+
+The last thing the tool prints is the command to run:
+
+```
+npx wrangler pages deploy "<OUT_ROOT>" --project-name <name>
+```
+
+Note that the tool does **not** run the deploy itself. Staging and deploying are separate steps, which
+means a human (or CI) can inspect the staged tree between them. This is consistent with the project's
+general posture: make the artifact inspectable before it is published.
+
+---
+
+## 5.10 The nine console states
+
+`mission.js` declares nine `ControllerState` values in `STATES`, an `EVENT_TO_STATE` map from the
+eight event names onto those states, and a `STATE_NOTE` table of human-readable text per state.
+`markState()` is the single function that advances the UI from one state to the next, and it is the
+only place the trace-bar width is written.
+
+The relationship between the nine states and the eight events is:
+
+- One state is the **idle / pre-run** state — the state the console is in before `QUERY_RECEIVED`.
+  `resetUI()` returns the console to it (and resets `#obsTail` to `none`).
+- The other eight states are entered by the eight events, in order. `EVENT_TO_STATE` is the mapping,
+  so the console's state names and the protocol's event names are kept in one place rather than
+  duplicated across `if` branches.
+
+`STATE_NOTE` gives each state a sentence, which is what `#traceNow` and `#traceNote` display while the
+run progresses. The point of the separate state text is that the event name is protocol
+(`SPECIALIST_STARTED`) while the state text is human ("running the grounding specialist"). The console
+shows both: the event name in the drawer's log, the state text in the trace region.
+
+### 5.10.1 Why the fill formula uses `(traceProgress + 0.5) / STATES.length`
+
+The formula is:
+
+```js
+traceFill.style.width = ((traceProgress + 0.5) / STATES.length) * 100 + '%'
+```
+
+Three observations about it:
+
+1. **`STATES.length` is 9, not 8.** The denominator is the number of states, which includes the idle
+   state. So the maximum reachable fill from events alone is `(8 + 0.5) / 9 = 94.4444 %`.
+2. **The `+ 0.5` is a half-step lead.** Entering state *n* shows the bar at *(n + 0.5)/9*, i.e. the
+   midpoint of that state's band. The bar therefore never sits exactly on a boundary, which reads
+   better visually and means the bar is always "inside" a labelled state.
+3. **The remaining 5.5556 % is the idle state's band.** A completed run does not enter idle, so a
+   completed run does not fill the bar. This is the arithmetic origin of the 94.4444 % figure the
+   delivery documents record.
+
+Stated as a status: the **formula** is `IMPLEMENTED`; the 94.4444 % figure is `MEASURED` *as the
+arithmetic consequence of the formula against nine states*, and it is corroborated by the live
+validation runs recorded in the delivery documents. It is not a claim about anything else.
+
+### 5.10.2 `onEvent()` — the single funnel
+
+`onEvent()` is the console's event handler: every event delivered through the `ingest()` seam passes
+through it. It is responsible for
+
+- appending to the event log via `logEvent()` (which writes to `#evlog` in the drawer),
+- advancing the state via `markState()` (which writes the trace bar),
+- routing the payload to the appropriate renderer (`renderEvidence()`, `renderConfidence()`,
+  `renderIntent()`, the answer renderer into `#answerHost`, and the provenance writers into
+  `#pRun` / `#pPolicy` / `#pProtocol` / `#pSchema`).
+
+Having a single funnel is what makes the REAL/PREVIEW distinction safe: both drivers call the same
+`onEvent()`, so the rendering path is identical and only the *payload source* differs. It is also why
+the "0 mock nodes vs 9 mock nodes" property is checkable at one place — the drawer's contents are
+produced by one function.
+
+---
+
+## 5.11 The viewer and comparison regions
+
+### 5.11.1 The viewer
+
+The viewer is the plate at the top of the console's results area. Handles: `#vbtns` (mode buttons),
+`#viewerState` (state label), `#plate` (container), `#plateImg` (the image, `src` initially
+`assets/img/eo/reservoir-low.jpg`), `#ev` (evidence overlay), `#evNote` (overlay note),
+`#plateCreditLead` and `#plateCredit` (attribution).
+
+The initial `src` is a **real EO image** (`reservoir-low.jpg`), not a synthetic one. That matters for
+honesty: before any run, the console shows a real image with a credit, so a visitor is never looking
+at invented imagery while the console is idle.
+
+`#vbtns` selects a viewer mode and `#viewerState` names it. The evidence overlay `#ev` is where the
+grounding result's regions are drawn — for the captured grounding run there are three regions
+(`region_1cd3973de749`, …), which is why the overlay is a layer separate from the plate image rather
+than something painted into the image.
+
+### 5.11.2 The comparison region
+
+For paired tasks (`change`, `change_vqa`, `optical_sar`), the console shows a comparison region:
+`#cmpWrap` (wrapper), `#cmpT0` (before pane), `#cmpT1` (after pane), `#cmpRange` (the range/slider
+control), `#cmpCredit` (attribution), `#cmpEmpty` (empty state).
+
+The two panes are fed from the two upload widgets (`#fileInput` for t1, `#fileInputT0` for t0). When
+only one asset is available for a paired task, `SINGLE_ASSET_FALLBACK = 'vqa'` narrows the request so
+the console can still produce an answer instead of failing. `#cmpEmpty` is the state shown when there
+is nothing to compare.
+
+The homepage uses the same visual idiom for its delta-growth wipe slider, which is a nice consistency:
+the *idea* of "two dates, one place, slide to compare" appears both as a landing-page illustration and
+as a functional control in the console.
+
+---
+
+## 5.12 Provenance and report controls
+
+### 5.12.1 The provenance block
+
+`#provHost` contains four fields that together answer "what exactly produced this?":
+
+| Handle | Field | Meaning |
+|---|---|---|
+| `#pRun` | run id | The `run_…` identifier. |
+| `#pPolicy` | policy | The routing/planning policy that produced the plan. |
+| `#pProtocol` | protocol | The protocol under which the result was produced. |
+| `#pSchema` | schema | The schema version of the response. |
+
+The reason a provenance block is worth four fields: the project's measurement discipline depends on
+being able to say *which* protocol a number came from. The style guide's grounding rule — that
+grounding was measured under **two protocols** (canonical 0.2838 / matched6 0.2566) and **two decode
+variants** (head_argmax 0.1215, zero-shot 0.0972) — is exactly the kind of fact that a protocol field
+exists to disambiguate. A result rendered without its protocol is a result that cannot be compared to
+anything.
+
+### 5.12.2 The report button and the event drawer
+
+`#btnReport` triggers the console's report action. `#btnEvents` opens `#drawer`, whose `#evlog`
+contains the ordered event log; `#btnClose` closes it. The drawer is the console's audit surface: it
+is the one place where a reader can count events and check for mock nodes.
+
+---
+
+## 5.13 The mock data model inside `core.js`
+
+`core.js` (1029 lines) is not only the event seam; it is also the source of everything the preview
+driver draws. Its internals, as read:
+
+**Utilities.** `SQ.util` provides `rnd` (random), `rng` (a seeded random-number generator — which is
+what makes the preview *deterministic* across reloads), `pad`, and `ms` (formatting).
+
+**Raster synthesis.** The synthetic imagery path:
+
+| Symbol | Role |
+|---|---|
+| `BIOMES` | The biome definitions the synthesised terrain is drawn from. |
+| `CANON` | `{w: 900, h: 600}` — the canonical raster size. |
+| `buildMasks()` | Builds the masks (land/water/etc.) the raster is composed from. |
+| `fbm` | Fractal Brownian motion — the noise function that gives the terrain texture. |
+| `SQ.scene` | Produces a scene; it sets a **`synthetic: true` flag** and fills placeholder `gsd`, `aoi`, and `dates`. |
+
+The `synthetic: true` flag is the load-bearing honesty mechanism: synthetic imagery is *labelled* as
+synthetic in the data, so any renderer can disclose it. The placeholder `gsd` (ground sample
+distance), `aoi` (area of interest), and `dates` are placeholders, not measurements — and the flag
+says so.
+
+**Imagery.** `SQ.imagery` resolves which image to show.
+
+**Stages.** `SQ.STAGES` is the eight-stage list from `QUERY` through `ANSWER`. This is the *narrative*
+stage list (what a human sees), distinct from the eight *event* names (the protocol). The two are
+aligned but not identical: `SQ.STAGES` is the visual progression; `SQ.EVENT_NAMES` is the wire
+vocabulary.
+
+**The deterministic policy.** `SQ.policy()` is a deterministic router used by the preview. Its
+documented quirks: a **`where`-first** fix (a query containing "where" is routed to grounding before
+other rules are considered), the removal of a `built` keyword, and the `newAsChange` rule. Because it
+is deterministic and seeded, the same query produces the same preview every time — which is what makes
+the preview useful as a UI demo and useless as a measurement.
+
+**Answer material.** `SQ.ANSWER_BANK` supplies canned answers for the preview; `SQ.COMPONENTS` lists
+**seven components** with their model strings, which is what the preview's model panel shows.
+
+**Shared components.** `SQ.frame`, `SQ.reliabilityPlot`, and `SQ.chip` are reusable renderers. The
+`SQ.reliabilityPlot` is the component that draws the reliability curve referenced on
+`benchmark.html`.
+
+**The run engine.** `SQ.run(opts)` is the engine; its `ingest()` switch (lines ~742–788) dispatches
+the eight event types to handlers. `startMock()` drives a preview run by calling `ingest()` on a
+schedule of `setTimeout` delays.
+
+> **Honesty note on `SQ.policy()` vs the server router.** The browser's `SQ.policy()` and
+> `mission.js`'s `interpret()` are **UI-side** interpretations. The authoritative router is
+> server-side (`core/controller.py`, `core/registry.py`). The preview's routing can therefore differ
+> from what the server would do, and that is acceptable precisely because the preview is labelled a
+> preview and emits no specialist events. A reader must not read `SQ.policy()` as the routing
+> specification.
+
+---
+
+## 6.8 `live.js` API surface reference
+
+`frontend/assets/js/live.js` is 392 lines. Its header documents the end-to-end flow and **three
+design rules**. The module's public surface, as read:
+
+| Symbol | Kind | Behaviour |
+|---|---|---|
+| `SQ.ENDPOINTS` | const | `{ assets: '/assets', infer: '/infer', capabilities: '/capabilities', health: '/health' }`. |
+| `SQ.CONTENT_TYPES` | const | `{ tif, tiff, png, jpg, jpeg }` — the accepted upload types. |
+| `SQ.contentTypeFor(file)` | fn | Maps a file to its MIME type; used to set the upload `Content-Type`. |
+| `SQ.live.baseUrl()` | fn | Resolution order: `window.SATQUERY_API_BASE` → `<meta name="satquery-api-base">` ��� `/api`. |
+| `_normalizeBase(base)` | fn (internal) | Normalises the base (trailing slashes). |
+| `SQ.live.url(endpoint)` | fn | Composes the final URL from the normalised base and an endpoint. |
+| `LiveError` | class | The client's error type, carrying enough detail for `describeFailure()`. |
+| `describeFailure(err)` | fn | Turns a `LiveError` into human-readable text. |
+| `SQ.live.uploadAsset(file)` | fn | Raw-bytes POST with `Content-Type`; **asserts** the response contains `asset_id`. |
+| `SQ.live.uploadAssets(files)` | fn | Uploads a list **sequentially** (no parallel uploads). |
+| `SQ.live.infer(request)` | fn | POSTs the analysis request; **reads `X-SatQuery-State` and `x-satquery-transport`** from the response. |
+| `SQ.live.run(opts)` | fn | Composes upload + infer into one run. |
+| `SQ.live.capabilities()` | fn | `GET` the capability block (used by `loadCapabilities()`). |
+
+### 6.8.1 The three design rules (as stated in the file's header)
+
+The file's header states three rules that govern the client. They are worth restating because they
+explain several behaviours that would otherwise look arbitrary:
+
+1. **Raw bytes, not multipart.** The upload is a body-with-content-type POST because that is what the
+   service accepts (`docs/API_CONTRACT.md` §2.4: multipart is *not* implemented). A client that sent
+   multipart would be rejected.
+2. **Sequential uploads.** `uploadAssets()` uploads one at a time because the server's asset store is
+   a small ephemeral store with a file cap (`SERVING.md`: default `_asset_max_files()` = 32), and
+   because a paired task's second upload depends on the first succeeding. Parallel uploads would make
+   partial failure harder to reason about.
+3. **The asset handle is opaque.** The client asserts the handle exists and passes it back
+   unexamined. The handle's shape (`asset_<32 hex>`) and its TTL are server facts; the client must not
+   depend on either.
+
+### 6.8.2 The two response headers
+
+`SQ.live.infer()` reads two custom headers:
+
+| Header | Meaning |
+|---|---|
+| `X-SatQuery-State` | The controller state for the response (the same vocabulary as the console's `STATES`). |
+| `x-satquery-transport` | How the response was carried (the captured envelope records `transport: "tunnel"`). |
+
+These two headers are how the console can display a state and a transport *without* a streaming
+channel. They are the reason the console can show a live run's progress truthfully: the state and the
+transport come from the server's own response, not from a client-side guess.
+
+---
+
+## 7.4 The captured envelope, field by field
+
+This subsection expands §7.1 into a complete inventory, because the captured envelope is the frontend's
+single richest piece of real data and a reader should be able to reconstruct it.
+
+**Provenance and identity.**
+
+| Field | Value | Note |
+|---|---|---|
+| `_source` | "Captured live 2026-09-25 … Sanitized" | The capture date and the fact that the payload was sanitized before shipping. |
+| `run_id` | `run_d124d8b9adea` | The run identifier. |
+| `config_hash` | `78f1e3700da15aa1` | The frozen config hash — the same value recorded in the style guide §3. |
+
+**Request.**
+
+| Field | Value |
+|---|---|
+| `query` | "Where is the reservoir?" |
+| `task` | `grounding` |
+| `intent.source` | `forced` (the task was forced rather than inferred). |
+| `transport` | `tunnel` |
+
+**Plan.**
+
+| Field | Value |
+|---|---|
+| plan | `step_001`, task `grounding`, `requires_assets` |
+| steps | 8 steps, `RECEIVE` → `RESPOND` |
+| `timings.step_001` | `209.873` (ms) |
+
+**Models.**
+
+| Field | Value |
+|---|---|
+| `selected_models` | ViT-B-32 (the RemoteCLIP path) → GroundingHead |
+| GroundingHead `params` | `1052677` |
+
+**Result.**
+
+| Field | Value |
+|---|---|
+| `answer` | "[grounding] Located 3 candidate region(s) … Highest objectness 0.61." |
+| evidence | 4 items: 3 × `bounding_box`, 1 × `statistic` |
+| regions | 3, e.g. `region_1cd3973de749` |
+
+**Confidence.**
+
+| Field | Value |
+|---|---|
+| raw | `0.5231253252136926` |
+| calibrated | `0.5236623182649384` |
+| method | `temperature_scaling` |
+| `temperature` | `0.9772731820958189` |
+| `calibration_samples` | `16441.0` |
+
+The `calibration_samples` value `16441.0` is the size of the validation set the temperature was fitted
+on; `docs/API_CONTRACT.md` §4 records the same figure as 16,441 Val rows. The temperature
+`0.9772731820958189` is also recorded in `docs/API_CONTRACT.md` §4. This is a real cross-check: the
+number on the public page matches the number in the API contract.
+
+**Geospatial and warnings.**
+
+| Field | Value |
+|---|---|
+| geospatial | 730 × 730, `has_crs false` |
+| warnings | 2 — no CRS; contradictory spatial claims |
+
+The presence of the warnings in the shipped envelope is itself a design statement: the capture was not
+cleaned up to look better than it was.
+
+**Why this page is important to the release.** It is the one place where a reader can see a complete,
+real, sanitized result envelope — including its imperfections — rendered by the same event vocabulary
+the live console uses. It is a *sample of one*, and the page does not present it as more than that.
+
+---
+
+## 11.3 A worked path through the platform traps
+
+The following Mermaid diagram shows where the two traps (§11.1, §11.2) bite. It is a description of
+the behaviours documented in `frontend/_headers`, `docs/API_CONTRACT.md` §5.1, and the Cloudflare
+redirect behaviour recorded in the delivery documents — not a measurement.
+
+```mermaid
+flowchart TD
+    A["Browser requests /run.html"] --> B{"Cloudflare Pages"}
+    B -->|"308 (method preserved)"| C["/run"]
+    C --> D["run.html served from the staged tree"]
+
+    E["Browser loads the page"] --> F{"Assets referenced"}
+    F -->|"/assets/js/run.js"| G["Rule: /assets/js/*"]
+    F -->|"/assets/img/…"| H["Rule: /assets/img/*"]
+    G --> I["Cache-Control: public, max-age=0, must-revalidate"]
+    H --> J["Cache-Control: max-age=604800"]
+
+    K["If two rules matched one path"] --> L["Values CONCATENATE"]
+    L --> M["Chromium honours the FIRST max-age"]
+    M --> N["Mitigation: scope patterns so they do not overlap"]
+```
+
+Read together, the traps say: **link to the canonical extensionless URL** (so the 308 never fires for
+an internal navigation) and **give each asset tree exactly one matching `_headers` rule** (so there is
+nothing to concatenate).
+
+The third, API-side trap — the Starlette trailing-slash **307** documented in `docs/API_CONTRACT.md`
+§5.1 — is the client's concern rather than the static tier's: `_normalizeBase()` and `SQ.live.url()`
+exist so the client composes a URL that matches the route exactly, rather than relying on a redirect
+to reach it.
+
+---
+
+## 14.1 What the frontend is a client *of*
+
+Because this chapter documents a client, it is worth stating precisely what contract the client is
+written against, so a reader can follow the thread into the `SERVING.md` chapter.
+
+- The client posts **raw bytes** to `/api/assets` and receives an opaque `asset_id`
+  (`docs/API_CONTRACT.md` §2.5).
+- The client posts **JSON** to `/api/infer` (`docs/API_CONTRACT.md` §2.4) and receives a
+  `ResultEnvelope`.
+- The client reads `GET /api/capabilities` (`docs/API_CONTRACT.md` §2.2) to know which tasks are
+  available now.
+- The client may read `GET /api/health` (`docs/API_CONTRACT.md` §2.1) for the service's health block.
+- The client reads two custom response headers (`X-SatQuery-State`, `x-satquery-transport`).
+- The client renders errors from the service's machine codes (`docs/API_CONTRACT.md` §5.2 — a 23-code
+  taxonomy in `core/errors.py`, plus the gateway-origin `rate_limited`, mapped by
+  `gateway/policy.py` `_CODE_STATUS`).
+- The client sends **no credentials**; the service has no auth (`docs/API_CONTRACT.md` §7). CORS is
+  configured on the orchestrator (`deploy/render/main.py` `_PRODUCTION_ORIGINS` includes the Pages
+  origin).
+
+Every one of those six interactions is documented from the *server* side in the `SERVING.md` chapter,
+which is the other half of this pair.
+
+---
+
+## 15. Status summary
+
+| Subsystem | Status |
+|---|---|
+| Static tier (11 pages, CSS, JS modules, assets) | `IMPLEMENTED` |
+| Staging tool `scripts/stage_pages.mjs` (closure, size gate, integrity gate, hermeticity report) | `IMPLEMENTED` |
+| Deploy path (`wrangler pages deploy` of the staged tree) | `IMPLEMENTED`; deployed HEAD `2d7ae53b482d` |
+| Analyze console (`mission.html` + `mission.js` + `live.js` + `core.js`) | `IMPLEMENTED` |
+| Eight-event protocol + trace bar (94.4444 % fill) | `IMPLEMENTED`; fill `MEASURED` as the arithmetic consequence of the formula |
+| PREVIEW driver (`runMock`, 9 mock nodes, no specialist events) | `IMPLEMENTED` |
+| REAL driver (`runLive`, real HTTP, 0 mock nodes) | `IMPLEMENTED`; exercised in the 24-run live validation recorded in the delivery docs |
+| Captured-run page (`run.html` over `anatomy-run.js`) | `IMPLEMENTED`; data is a real sanitized capture (`run_d124d8b9adea`) |
+| Hugging Face + GitHub header links on all 11 pages | `VERIFIED` by search across `frontend/*.html` |
+| Cache-busting (`_headers` rules + URL versioning) | `IMPLEMENTED` |
+| `_headers` concatenation trap | `KNOWN` (blocker item 9 in `docs/FINAL_DELIVERY_TODO.md` §1.7); mitigated by non-overlapping patterns |
+| Accessibility audit | `NOT RUN` |
+
+---
+
+## 16. NOT RUN / OPEN / BLOCKED (frontend)
+
+Per `release/DOCS_STYLE_GUIDE.md` §4, every doc ends with this list.
+
+**NOT RUN**
+- No formal accessibility audit (axe / Lighthouse / WCAG conformance level).
+- No measured contrast-ratio audit of the token palette.
+- No screen-reader behaviour verification for the trace bar's state transitions.
+- No responsive-breakpoint verification beyond the CSS as written.
+- No end-to-end benchmark of the system (this is project-wide, per `release/DOCS_STYLE_GUIDE.md`
+  §3 — it is *not* a frontend gap, it is a project-level fact that the frontend must not contradict).
+
+**OPEN**
+- `frontend/404.html` prose says "Ten pages exist" while eleven ship — documentation drift, OPEN.
+- The `_headers` concatenation behaviour remains a known platform trap (blocker item 9); the shipped
+  rules avoid overlap, but the underlying platform behaviour is unchanged and OPEN as a hazard.
+- A page named "Lab" is not among the eleven shipped pages; whether it existed is
+  `UNKNOWN — not established from the available evidence`.
+- Accessibility conformance level: `UNKNOWN — not established from the available evidence`.
+
+**BLOCKED**
+- Nothing in the frontend is blocked. The frontend's live path depends on the backend, and the
+  backend's own blockers (e.g. B-07, tunnel gaps; patch prepared, NOT deployed) are recorded in the
+  `SERVING.md` chapter and the delivery documents. A backend blocker surfaces in the console only as
+  an error rendered by `translateError()`.
+
+---
+
+## 17. Where the evidence lives
+
+| Claim area | Evidence file(s) |
+|---|---|
+| Page inventory, purposes, `data-view`, section structure | `frontend/*.html` (11 files, each read) |
+| Homepage structure, video chapters, delta pair, open-question links | `frontend/index.html` |
+| Analyze console markup and every DOM handle | `frontend/mission.html` |
+| Console driver, `interpret()`, `chooseTask()`, `assetsForTask()`, `validateOpticalSar()`, `translateError()`, `routeSpecialists()`, `renderIntent()`, `STATES`/`EVENT_TO_STATE`/`STATE_NOTE`, `markState()` (fill formula), `buildTrace()`, `logEvent()`, `resetUI()`, `renderEvidence()`, `renderConfidence()`, `onEvent()`, `runMock()`, `runLive()`, `runQuery()`, `loadCapabilities()`, `setMode()`, `handleFile()`, `window.SQ_MISSION` | `frontend/assets/js/mission.js` |
+| `SQ` namespace, rng/util, synthetic scene flag, `SQ.STAGES`, `SQ.EVENT_NAMES`, `SQ.policy()`, `SQ.run().ingest()`, `startMock()`, `SQ.COMPONENTS` | `frontend/assets/js/core.js` |
+| Live client: `SQ.ENDPOINTS`, `SQ.CONTENT_TYPES`, `SQ.contentTypeFor()`, `SQ.live.baseUrl()`, `_normalizeBase()`, `SQ.live.url()`, `LiveError`, `describeFailure()`, `uploadAsset()`, `uploadAssets()`, `infer()` (header reads), `run()`, `capabilities()` | `frontend/assets/js/live.js` |
+| Captured-run driver: `QUERY…PLATE`, `REGIONS`, `paintAll()`, `buildEvidence()`, `evCandidates()/evLock()/evConfirmed()`, `SPECIALISTS_FOR_TASK`, `buildLattice()`, `DATA` (8 KV tables with event names), `setStage()`, `resetEvidence()`, `gotoStep()` | `frontend/assets/js/run.js` |
+| Captured envelope (run id, task, answer, config hash, transport, plan, steps, models, evidence, regions, confidence + calibration, timings, geospatial, warnings) | `frontend/assets/data/anatomy-run.js` |
+| Cache rules and the concatenation trap (verbatim comment) | `frontend/_headers` |
+| Design law, token system, phases A–G, file map, hard limits, schema types, `ingest` seam, 8 event names | `frontend/HANDOFF.md` |
+| Staging tool: constants, regexes, closure walk, exit codes 2/3, report blocks, `HERMETIC`, deploy hint | `scripts/stage_pages.mjs` |
+| Deployed frontend HEAD `2d7ae53b482d`; HF link on all 11 pages; blocker item 9 | `docs/FINAL_DELIVERY_TODO.md` |
+| Live topology and per-component responsibilities | `docs/DEPLOYMENT_TOPOLOGY.md` |
+| Superseded-topology banner; entrypoint requirements; failure-mode table | `docs/DEPLOYMENT_ARCHITECTURE.md` |
+| API contract the client speaks (endpoints, enums, confidence, errors, no-auth, CORS, multipart-not-implemented, 307 footgun, 23-code taxonomy) | `docs/API_CONTRACT.md` |
+| Captured run ids per task; metrics table; blockers | `docs/FINAL_DELIVERY_REPORT.md` |
+| Style, grounding rules, status vocabulary, facts-that-must-not-be-wrong, 94.4444 % trace fill | `release/DOCS_STYLE_GUIDE.md` |