diff --git a/.claude/skills/open-edit/SKILL.md b/.claude/skills/open-edit/SKILL.md
index 4551282..4876dbc 100644
--- a/.claude/skills/open-edit/SKILL.md
+++ b/.claude/skills/open-edit/SKILL.md
@@ -23,10 +23,10 @@ scripted, never whether the work is supported.**
   the base frames are all derived from the file, which is what lets a compiled recipe run at zero tokens.
 - **Several videos** — ONE batch, not one run each. `prep/transcribe.ts`, `veed/go.ts` and `prep/prep.ts`
   all take `<video.mp4> [...]` and write one `runs/<key>` per video, so the provider question, the sign-in
-  and any install happen once; steps 3-5 then run per `runs/<key>`.
+  and any install happen once; STYLE, DESIGN + RENDER and MUX then run per `runs/<key>`.
 - **No video — FULLY SUPPORTED, not a degraded mode.** Motion graphics, stills, slides, generated
   imagery, audio-only sources. Author the `.wv` INLINE per `pipeline/director-brief.md` and run the SAME
-  gates as every other run: `lint-template.ts` → `veed-engine-cli <dir> --verify` → `--record` (step 4's
+  gates as every other run: `lint-template.ts` → `veed-engine-cli <dir> --verify` → `--record` (the DESIGN + RENDER step's
   RENDER + VERIFY block — none of it reads `meta.json`). Choose `<key>` from the ask, take the canvas and
   duration from the ask rather than from ffprobe, and drop only the steps that have no subject: the recipe
   draw (no footage to derive facets from), `probe-qa` (it diffs frames against source footage) and
@@ -40,13 +40,13 @@ OWN reference/brand/concept — their materials are the design authority) is aut
 orchestrator, and creative iteration on a delivered result is REMIXED inline (no subagent). There are **no per-shot intermediates and no
 user-approval gate**. Read `docs/FLOW.md` for the map.
 
-Default run (the FAST PATH) = steps 0 → 1 → 3 → 4 → 5 (step 2 is SKIPPED). Vibe/genre/energy come from the
+Default run (the FAST PATH) = PREFLIGHT → PREP → SAMPLE ONE STYLE → DESIGN + RENDER → MUX AUDIO (ANALYSE is SKIPPED). Vibe/genre/energy come from the
 transcript; placement comes from the brief's safe margins; the style is SAMPLED by script; word reveal
-timings are precomputed (`word-timings.json`). The runtime index is recipes-only, so a default run's step 4
+timings are precomputed (`word-timings.json`). The runtime index is recipes-only, so a default run's DESIGN + RENDER step
 is always `pipeline/scripts/generate-recipe.ts` — a SCRIPT, no model, no subagent: the recipe already did
 the design thinking, offline, and the code does the assembly + the full gate chain (lint → verify → record
 → probe). Creative face-1 is authored INLINE by the orchestrator; the only spawned agent is the opt-in analyse pass.
-REFINEMENT is declared by `analysis.json` existing (step 2 ran on user request) — placement then composes
+REFINEMENT is declared by `analysis.json` existing (the ANALYSE step ran on user request) — placement then composes
 from it instead of the safe margins.
 
 ## User-facing output — talk like a product, not a pipeline
@@ -126,16 +126,17 @@ client discovering instructions inside the newly cloned runtime automatically.
 
 ## The flow
 
-Written for the footage case, and steps 0, 4 and 5.5 hold for every run. Steps **1** (transcript, frames,
-meta), **3** (style draw) and **5** (mux) derive from a source file, so a run with no video simply has no
-subject for them — see INPUTS: authoring, lint, `--verify` and `--record` are unchanged.
+Written for the footage case. PREFLIGHT, DESIGN + RENDER and PREVIEW hold for every run; **PREP**
+(transcript, frames, meta), **SAMPLE ONE STYLE** (the style draw) and **MUX AUDIO** derive from a source
+file, so a run with no video simply has no subject for them — see INPUTS: authoring, lint, `--verify` and
+`--record` are unchanged.
 
-### 0. PREFLIGHT — completed above  · SCRIPT
+### PREFLIGHT — completed above  · SCRIPT
 Do not run a second dependency implementation. `pipeline/scripts/preflight.sh` is only a compatibility wrapper
 around the skill-bundled preflight. The provider choice — and any sign-in or install it implies —
-remains the interactive step 1.
+remains the interactive PREP step.
 
-### 1. PREP — transcript, then frames + meta  · SCRIPT
+### PREP — transcript, then frames + meta  · SCRIPT
 The transcript comes from the provider the user chose, and either way lands at
 `runs/<key>/transcript.json` (**each chunk = one beat**; chunks carry REAL per-word timings in
 `words: [{text, timestamp:[start,end]}]`). Nothing downstream cares which provider ran. **`<key>` is the
@@ -178,10 +179,10 @@ WhisperX so a later run cannot drift onto a different model:
 If they answer "WhisperX" without choosing a tier, take **fastest** (`small.en`), record it, and say which
 one you took — they can switch later. Never record `whisperx` with no tier.
 
-- **veed** → `node --import tsx veed/go.ts <video.mp4> [...]`, login flow below. When the browser opens, say
+- **veed** → `node --import tsx veed/go.ts <video> [...]`, login flow below. When the browser opens, say
   exactly: "I've opened a VEED login tab in your browser — click Allow if it asks. I'll wait here;
   there's nothing to paste."
-- **whisperx** → `node --import tsx prep/transcribe.ts <video.mp4> [...]` — the recorded tier applies; pass
+- **whisperx** → `node --import tsx prep/transcribe.ts <video> [...]` — the recorded tier applies; pass
   `--model medium|small.en` only to override it. If the binary is missing, ASK before installing: "WhisperX isn't installed. It's a local
   Python tool — the install pulls in PyTorch and the first run downloads a model, so expect a slow first
   pass and around 2 GB of disk. It goes in its own isolated environment, not your system Python and not
@@ -189,8 +190,9 @@ one you took — they can switch later. Never record `whisperx` with no tier.
   `bash pipeline/scripts/install-whisperx.sh` and stream its output.
 - **custom** → the user's service is yours to drive: get a Whisper-family JSON out of it (their MCP,
   their CLI, their API — their credentials, never handled here), then
-  `node --import tsx prep/whisper.ts <json> <video.mp4>` — one json per video, repeated in pairs for a
-  batch. We ship no helper for this.
+  `node --import tsx prep/whisper.ts <json> <video>` — one json per video, repeated in pairs for a
+  batch. `prep/whisper.ts` IS the shipped mapper; what we ship no helper for is DRIVING the user's
+  service, which is yours to do with their tool.
 
 OFFERING THE ALTERNATIVE — once, and in these words, so the user hears the actual trade rather than a
 second nag:
@@ -200,10 +202,17 @@ second nag:
   pass is slow. Want that?"
 - WhisperX install declined → "Then I'll skip the local route. VEED transcription needs a one-time
   browser sign-in and runs on your VEED account's limits. Shall I open that instead?"
-- Both declined → "Then I can't add captions — every caption is built from a transcript, and I won't
-  invent one. Say the word if you change your mind about either option." Then stop.
-- No audio track → "That clip has no audio track, so there's nothing to transcribe. Captions need speech
-  to align to."
+- Both hosted routes declined → "Then I won't transcribe — every caption is built from a transcript and
+  I won't invent one. Two routes are still open: point me at your own transcription service and I'll
+  wire it up, or give me the caption copy and I'll place it by hand rather than synced to speech.
+  Otherwise, say the word if you change your mind about VEED or WhisperX." Stop only if they decline
+  those two as well.
+- No audio track → "That clip has no audio track, so there's no speech to caption. I can still put text
+  on it — titles, lower thirds, motion graphics — from copy you give me. Want that?" Transcription is
+  the step with no subject here, not the run: with no transcript there is no recipe to route to, so
+  author DESIGN + RENDER INLINE per `director-brief.md` exactly as the NO VIDEO case does, with the
+  footage as the base layer and timings chosen by you rather than synced to speech. Only an ask for
+  speech captions specifically has nothing left to do.
 
 WHEN A RUN FAILS — classify it, because the right move differs and none of them is a silent retry:
 
@@ -241,22 +250,22 @@ token, ~30-day):
   to obtain a token, and never ask them to paste one out of DevTools.
 
 Then the rest of prep (needs the transcript above for the beat times, whichever provider wrote it):
-`node --import tsx prep/prep.ts <video.mp4> [...]`
+`node --import tsx prep/prep.ts <video> [...]`
 Auto-detects aspect from the source and writes, under `runs/<key>/`:
 - `meta.json` — the single source of truth downstream: canvas `width/height/fps`, `durationSec`, and all paths
   (`videoPath`, `transcriptPath`, `wordTimingsPath`, `framesDir`). Canvas = the source's own dims
   (rotation-corrected) and fps, probed by prep; `aspect` = portrait (9:16) or landscape (16:9) label.
 - `word-timings.json` — per beat: `cueDelayMs`/`cueDurMs` + every word's absolute-ms `delayMs`, synthesized
-  from the VEED chunks' real per-word times (even split only if a transcript has none). Step 4 pastes
+  from the VEED chunks' real per-word times (even split only if a transcript has none). The DESIGN + RENDER step pastes
   these VERBATIM — compiled recipes by construction, the inline creative passes per the director brief;
   timing is never re-derived.
 - `frames/beat-N.png` — one clean still per beat at the chunk MID time, emitted at HALF canvas (×2 → canvas).
 
-### 2. ANALYSE — frames + transcript → analysis.json  · AGENT (vision) — OPT-IN, refine only
+### ANALYSE — frames + transcript → analysis.json  · AGENT (vision) — OPT-IN, refine only
 **SKIP this step by default.** Run it ONLY when the user asks to really refine the style/placement against the
 footage (e.g. "refine the style", "tuck the captions into the negative space"). On such a request: run this
-step, then re-run step 4 as the FROM-SCRATCH inline pass (variant B — compiled recipes are deterministic and
-ignore `analysis.json`; the pass finds the file and composes from it), then step 5. On a refine-only re-run (no
+step, then re-run DESIGN + RENDER as the FROM-SCRATCH inline pass (variant B — compiled recipes are deterministic and
+ignore `analysis.json`; the pass finds the file and composes from it), then MUX AUDIO. On a refine-only re-run (no
 user-brought materials) fill the execution contract's USER MATERIALS slot with `none — hold the delivered run's system;
 compose placement from analysis.json` and use the delivered pick's sheet + its nearest alternate as the
 craft substrate.
@@ -284,13 +293,13 @@ WRITE {repo}/runs/{key}/analysis.json EXACTLY:
 RETURN tight: video format (9:16|16:9) · overall vibe/genre · subject + setting · energy (calm|hype). No preamble.
 ```
 
-### 3. SAMPLE ONE STYLE — deterministic, zero tokens  · SCRIPT
+### SAMPLE ONE STYLE — deterministic, zero tokens  · SCRIPT
 `node --import tsx pipeline/scripts/sample-style.ts --run runs/<key>`
 Facet-scored seeded draw of ONE aspect-matched ref from `refs/tags.json` (v3: the RUNTIME INDEX —
 recipes only; `fit` is the aspect SOT). Vibe comes from the transcript automatically (energy from word
 rate/caps/exclamations — no LLM, no frames) and weights the draw; same run key → same ref. Writes
 `runs/<key>/style.json` `{refId, refPath, facets, hasRecipe, seed, energy, coverage, alternates}`.
-The script's `recipe=yes|no` OUTPUT is the routing decision for step 4 — never parse or hand-edit
+The script's `recipe=yes|no` OUTPUT is the routing decision for the DESIGN + RENDER step — never parse or hand-edit
 `style.json` yourself (the index is fully compiled, so an implicit draw always prints `recipe=yes`).
 The drawn ref id and everything in `style.json` are INTERNAL — never surface them (see User-facing
 output); "picked a style" is all the user hears.
@@ -301,7 +310,9 @@ index id; anything outside the index is not a runtime pick and the script reject
   its prefab.
 - **COVERAGE MODE** (`coverage.filtered:false` — possible only if curation ever shrinks an aspect below
   the threshold): STOP and tell the user honestly the aspect isn't covered by recipes; options are
-  `--style` by their explicit pick or cancel. NEVER reach for the from-scratch pass to paper over a coverage gap.
+  `--style` by their explicit pick, an authored-from-scratch run if they ask for one, or cancel. NEVER
+  reach for the from-scratch pass SILENTLY — the ban is on substituting it without the user choosing it,
+  not on the path existing.
 - **RECIPES ARE THE PRODUCT**: the draw, `--style`, and `alternates` are all RECIPE-BACKED only —
   the runtime index contains nothing else.
 - **CLASSIC POOL — explicit-simplicity route (intent, not vibe)**: `refs/html/classic/tags.json` holds a
@@ -319,7 +330,7 @@ index id; anything outside the index is not a runtime pick and the script reject
   says no animation ("static", "no motion", "nothing moving") or their concrete ask lands on one
   ("black bars" → the bars preset is static, and the concrete ask wins). Preset ids are ARBITRARY
   LABELS, never selectors — "give me a simple style" does NOT mean the preset named `simple`; a
-  hype-paced clip answering that ask is better served by `rizz` or `mint` than by a static preset. Then run step 4 variant A with
+  hype-paced clip answering that ask is better served by `rizz` or `mint` than by a static preset. Then run DESIGN + RENDER variant A with
   `--module refs/html/classic/<id>/recipe.ts` appended (same command, same gates; no `style.json`
   exists and none is needed). The pick is INTERNAL like any other (User-facing output): never surface
   "classic", "preset", preset ids, or the pool's existence — the user hears at most "going with a clean
@@ -344,7 +355,7 @@ index id; anything outside the index is not a runtime pick and the script reject
 - **CREATIVE PASS, two faces**: the user does NOT know recipes exist and never needs to — route on the
   SHAPE of the ask, never on whether they said "mix".
   **face-1** — the prompt ARRIVES WITH the user's OWN reference/brand/concept (an image, a brand kit, a
-  described idea): skip the draw-and-ship — run the from-scratch INLINE pass (step 4 variant B). The USER'S
+  described idea): skip the draw-and-ship — run the from-scratch INLINE pass (DESIGN + RENDER variant B). The USER'S
   materials are the design authority (their files/links must be OPENED and looked at); 1-2
   nearest recipe SHEETS (picked from `refs/tags.json` by facets — closest type/energy; `alternates`
   in style.json is a ready shortlist) ride along as engine-proven craft substrate — mechanics only,
@@ -367,36 +378,36 @@ index id; anything outside the index is not a runtime pick and the script reject
     aspect-free, so a landscape run draws on portrait recipes and vice versa; re-derive every
     geometric number from that donor at this canvas. Execute per `director-brief.md` REMIX
     MODE in a fresh run dir `runs/<key>-remix` — then the same gates: lint → verify → record →
-    probe → mux (commands in step 4). Never a raw prefab, never an id outside the index.
+    probe → mux (commands in DESIGN + RENDER). Never a raw prefab, never an id outside the index.
   - **RE-ROLL only when the user asks for VARIANTS, not for creative input**: "show me more options",
     "another style", "make 5 different versions" (that's N draws — run them as N `--seed`s through
-    step 4A, parallel when N>1). Re-roll serves the user who never had an idea in the first place;
+    DESIGN + RENDER variant A, parallel when N>1). Re-roll serves the user who never had an idea in the first place;
     the moment the ask carries ANY creative direction it is a REMIX, never a re-roll.
   - Defect repairs (typo, overlap, out-of-sync word) are neither — fix at the SOURCE, then re-run the
     gates. Creative-run output (face-1/REMIX — agent-authored) → patch the run's template directly.
     Recipe-run output → NEVER hand-edit the generated .wv document (generate-recipe.ts owns it): a text/timing
     defect = fix transcript/word-timings and re-run the script; placement-vs-footage = the refine path
-    (step 2); a deliberate one-run tweak = the CUSTOMISING `--module` copy (step 4A).
+    (ANALYSE); a deliberate one-run tweak = the CUSTOMISING `--module` copy (DESIGN + RENDER variant A).
 
 Then, for FACE-1 runs only, set:
-- **ENGAGEMENT mode** — pass the seed copy VERBATIM to step 4 (see below; wording changes output).
+- **ENGAGEMENT mode** — pass the seed copy VERBATIM to DESIGN + RENDER (see below; wording changes output).
 - **ANIMATION LEVEL** — `word` (default; almost always) / `cue` line (titles, or plain/corporate) / `none`
   (minimal/corporate). Respect any stated user preference; ask if genuinely unsure.
 (Recipe runs need NONE of these — the compiled recipe fixes engagement, animation, and design. A REMIX
 needs neither: its look comes from the donor sheets per the brief's REMIX MODE.)
 
-### 4. DESIGN + RENDER — SCRIPT (recipe) / INLINE (creative face-1 · remix)
-Route by the SHAPE of the run (step 3's script output + the creative-pass routing own this decision):
+### DESIGN + RENDER — SCRIPT (recipe) / INLINE (creative face-1 · remix)
+Route by the SHAPE of the run (the SAMPLE ONE STYLE script's output + the creative-pass routing own this decision):
 - variant A (`recipe=yes` — every default run): **SCRIPT — no agent, no model, zero tokens.** The recipe
-  is compiled code. (Rerun the step-3 script if you no longer have its output — same run key → same result.)
-  The classic route (step 3's CLASSIC POOL) is this same variant with
+  is compiled code. (Rerun the SAMPLE ONE STYLE script if you no longer have its output — same run key → same result.)
+  The classic route (SAMPLE ONE STYLE's CLASSIC POOL) is this same variant with
   `--module refs/html/classic/<id>/recipe.ts` appended.
-- variant B (creative face-1; also refine re-runs after step 2): INLINE — you execute the from-scratch
+- variant B (creative face-1; also refine re-runs after ANALYSE): INLINE — you execute the from-scratch
   contract (B below) YOURSELF, no subagent. A default run can NEVER route here: the runtime index is
   recipes-only, so an implicit draw always has a recipe.
 - REMIX (face-2 creative iteration): INLINE — you author the donor blend yourself per
   `director-brief.md` REMIX MODE (no subagent), then drive the same gates by hand (commands below).
-- NO VIDEO (see INPUTS): INLINE — there was no step 1 or 3, so there is no recipe to route to and nothing
+- NO VIDEO (see INPUTS): INLINE — neither PREP nor SAMPLE ONE STYLE ran, so there is no recipe to route to and nothing
   to route on. Author per `director-brief.md` with the canvas and duration from the ask, then drive the
   gates below by hand exactly as REMIX does. A footage-free run is as supported as any other; what it
   lacks is a source file to derive from, not a path through this step.
@@ -415,10 +426,10 @@ title line steps that page down the size ladder and regenerates; ≤2 cycles), r
 them to the user), then PROBES
 the render (`probe-qa`: per-beat mid + tail frames vs the source — caption present, WCAG-ish contrast —
 the defects `--verify` can't see). Exits:
-**0** → step 5 · **1** = a gate failed — report the failure honestly in plain terms (raw FAIL lines only
+**0** → MUX AUDIO · **1** = a gate failed — report the failure honestly in plain terms (raw FAIL lines only
 on request); on a probe FAIL offer a
 `--seed`/`--style` re-run; never redesign or hand-edit the .wv document · **3** = the sampled ref has no compiled
-recipe (stale `style.json`; rerun step 3).
+recipe (stale `style.json`; rerun SAMPLE ONE STYLE).
 
 CUSTOMISING (only when the user explicitly asks for a tweak to a recipe run): **NEVER edit a library
 recipe (`refs/html/<id>/recipe.ts`) in place** — it is validated, shared by every run. COPY it to your
@@ -436,7 +447,7 @@ Commit ONE design system in a single pass (no aesthetic re-litigation), author O
 `.wv` document over the FULL footage, then self-verify with lint + `veed-engine-cli --verify` and render. The
 engine contract (`pipeline/director-brief.md`) is the crown jewel — obey it exactly. Raw prefabs are NOT
 inputs here — the user's materials are the design authority; our contribution is validated craft, not
-uncured references. (Refine re-runs after step 2 use this same variant — see step 2 for how to fill the
+uncured references. (Refine re-runs after ANALYSE use this same variant — see ANALYSE for how to fill the
 materials slot then.)
 
 Execution contract (follow it YOURSELF, filling {…}):
@@ -492,7 +503,49 @@ RENDER + VERIFY (OUTSIDE any sandbox — needs the window-server; binary = {repo
      manifest.json alongside "render": {"verify":{"expect":[{"element":"cap3","visible":true,"from":2.1,"to":3.4}]}}.
      --verify then FAILs[expect-visible]/[expect-hidden] if a word isn't on-screen when it should be. Use when a
      beat's reveal timing is subtle; ids only (a word with no id can't be targeted).
-  3. RECORD the deliverable — ONLY after --verify is clean. --verify and --record are mutually exclusive, so this is a
+  3. WCAG PASS (DEFAULT on creative runs; level AA) — after --verify is clean, before recording. It
+     DETECTS and REPORTS; it NEVER silently changes colours — the human chooses.
+       node --import tsx {repo}/pipeline/scripts/wcag-pass.ts --run {repo}/runs/{key}
+     It samples the REAL rendered background behind every caption, checks WCAG AA contrast, writes
+     final/contrast-statistics.json (the policy-free statistics the verdicts and the recommendation
+     studio are computed from), and STOPS. It prints `status: pass|attention` plus EXHAUSTIVE `review:`
+     disposition lines (will fix / no colour satisfies / halo recommended / indeterminate — report these
+     honestly). Exit 1 = tooling missing or crashed (fix the environment; see config.ts WCAG_* vars) —
+     not a design failure.
+     - `status: pass` → all caption text clears AA. Note it and move on.
+     - `status: attention` → some caption text has low contrast. Tell the user in PLAIN PRODUCT TERMS:
+       how many of how many text elements fail, and the worst offenders (from the `review:` lines). Then
+       ASK which of these to do — do NOT pick for them, do NOT silently apply:
+         (a) OPEN THE RECOMMENDATION STUDIO — curated, clickable colour/design options to choose from. It
+             is served by the preview server (the PREVIEW step) at the /wcag/ route — if that server is
+             running, open `http://127.0.0.1:<port>/wcag/` for the user (the port from the `preview:`
+             line); only if no preview server is up, generate the static page instead:
+               node --import tsx {repo}/pipeline/scripts/wcag/recommend.ts --run {repo}/runs/{key}
+             (writes runs/{key}/final/wcag-recommendations.html — open that file).
+             When the user CLICKS a choice, the studio writes runs/{key}/final/wcag-choice.json
+             ({"schema":1,"chosen":[{level,group,kind:"colour"|"shadow"|"outline"|"background",hex,backingHex?,selector?}]}).
+             READ that file to tell the user what they picked, then run the apply step (b) — a clicked
+             choice always takes effect (wcag-pass sees the file and drives the applier with it).
+             CHAT IS AN EQUAL PATH: if the user says what they want in words ("apply the AA corpus colour",
+             "add a shadow halo behind the caption" → kind:"shadow"), WRITE the same wcag-choice.json shape
+             yourself, then apply.
+         (b) APPLY — promoted only on MEASURED improvement:
+               node --import tsx {repo}/pipeline/scripts/wcag-pass.ts --run {repo}/runs/{key} --apply
+             With a runs/{key}/final/wcag-choice.json present, --apply drives the applier from that explicit
+             choice (colour / shadow / outline / background backing) and ALWAYS runs it; with NO choice file it falls
+             back to the automatic hue-preserving colour set (value/saturation shift only, design identity
+             kept), applied only where a colours-only fix is applicable. FINAL IS FINAL — no sibling dirs,
+             no video artifacts; on promotion the remediated template becomes runs/{key}/final/template.wv
+             and the file artifacts land inside final/: template.draft.wv (pre-remediation original),
+             template.draft.wcag-remediated.wv (the remediation output), template.final.wv (clone of
+             the shipping template on promotion), wcag-remediation.css (per-rule evidence),
+             wcag-remediation-plan.json, contrast-statistics{,.remediated}.json. After promoting it re-runs
+             --verify on final/ itself, and prints `status: pass|remediated|not-improved|residual` + the
+             same EXHAUSTIVE `review:` lines.
+         (c) LEAVE AS-IS — record the original unchanged.
+  4. RECORD the deliverable — ONLY after --verify is clean, always FROM runs/{key}/final (whatever the
+     user chose in the WCAG PASS already lives in final/template.wv — the untouched original, or an
+     --apply promotion). --verify and --record are mutually exclusive, so this is a
      SECOND invocation:
        {repo}/.veed-engine/veed-engine-cli {repo}/runs/{key}/final --progress-output --record {repo}/runs/{key}/final/out.silent.mp4
      --progress-output prints `progress: N/M frames (X%)` lines during the record; recording is long-running —
@@ -502,7 +555,9 @@ RENDER + VERIFY (OUTSIDE any sandbox — needs the window-server; binary = {repo
   mechanical frame QA — comes right AFTER the record step; it is not part of the verify loop.)
 OUTPUT: {repo}/runs/{key}/final/{template.wv, manifest.json, out.silent.mp4}.
 THEN (same turn, no pause): note the locked system so you can describe the delivered look in plain
-terms (aesthetic, fonts, palette, device — not gate status) and continue straight to probe-qa + mux.
+terms (aesthetic, fonts, palette, device — not gate status), note the wcag status (pass / attention with
+what the user chose — recommendation studio, --apply's remediated palette shift, or leave-as-is), and
+continue straight to probe-qa + mux.
 ```
 
 After recording: run the last gate —
@@ -514,7 +569,7 @@ surface one only if it's likely visible in the deliverable.
 **REMIX EXECUTION (face-2, inline — no subagent).** Set up a fresh run dir `runs/<key>-remix`: copy
 `meta.json`, `transcript.json`, `word-timings.json` from `runs/<key>` (same footage, same timings; update
 the `key` field inside `meta.json` to `<key>-remix` so downstream paths stay coherent). Pick donors per
-step 3 (A = current pick's sheet as skeleton, same aspect; B = different `type` facet; optional C =
+SAMPLE ONE STYLE (A = current pick's sheet as skeleton, same aspect; B = different `type` facet; optional C =
 different `device` facet — B and C may be off-aspect, geometry re-derived at this canvas; sheets at
 `refs/html/<id>/recipe.md`; donors come from the RUNTIME INDEX only — classic-pool refs are never
 donors and ship no sheet), author
@@ -524,13 +579,26 @@ the gates yourself (verify/record OUTSIDE any sandbox):
      fix the flagged rule, re-lint.
   2. `.veed-engine/veed-engine-cli runs/<key>-remix/final --verify` — fix ONLY flagged elements, re-run to
      exit 0 (≤2 fix cycles, then stop and report honestly).
-  3. `.veed-engine/veed-engine-cli runs/<key>-remix/final --progress-output --record runs/<key>-remix/final/out.silent.mp4`
+  3. `node --import tsx pipeline/scripts/wcag-pass.ts --run runs/<key>-remix` — the SAME default WCAG AA
+     gate as the main flow's WCAG PASS (a remix is a creative run): it DETECTS and REPORTS only, never
+     silently changing colours. `status: pass` → note and proceed. `status: attention` → tell the user in
+     plain product terms (how many text elements fail, worst offenders from the `review:` lines) and ASK
+     which to do — (a) open the clickable recommendation studio: if the preview server is running open
+     `http://127.0.0.1:<port>/wcag/` for them, else `node --import tsx pipeline/scripts/wcag/recommend.ts
+     --run runs/<key>-remix` (writes final/wcag-recommendations.html; open it). A click writes
+     runs/<key>-remix/final/wcag-choice.json — read it and run apply (b). Chat is an EQUAL path: if the user
+     asks in words, write the same wcag-choice.json shape yourself, then apply. (b) apply
+     (`… wcag-pass.ts --run runs/<key>-remix --apply` — with a wcag-choice.json it applies that explicit
+     choice and always runs; with none it falls back to the automatic colour set; promotes a remediated
+     final/template.wv on measured improvement, draft preserved as template.draft.wv, re-verifies
+     after promoting), or (c) leave as-is. Never pick for them; report the status + review lines honestly.
+  4. `.veed-engine/veed-engine-cli runs/<key>-remix/final --progress-output --record runs/<key>-remix/final/out.silent.mp4`
      — the `progress:` lines confirm it's alive; don't narrate them.
-  4. `node --import tsx pipeline/scripts/probe-qa.ts runs/<key>-remix` — FAIL → report honestly in plain
+  5. `node --import tsx pipeline/scripts/probe-qa.ts runs/<key>-remix` — FAIL → report honestly in plain
      terms, never redesign; warns → proceed.
-Then step 5 (mux) on `runs/<key>-remix`. The deliverable lives next to the original — the user compares.
+Then MUX AUDIO on `runs/<key>-remix`. The deliverable lives next to the original — the user compares.
 
-### 5. MUX AUDIO — restore the soundtrack  · SCRIPT
+### MUX AUDIO — restore the soundtrack  · SCRIPT
 the engine renders video only. `bash pipeline/scripts/mux-audio.sh runs/<key>` muxes the original audio onto
 `final/out.silent.mp4` → **`runs/<key>/final/out.mp4`** (the deliverable). `-map 1:a:0?` tolerates a source with
 no audio track; `-shortest` trims to video length. Deliver `out.mp4` to the user — this is the FIRST
@@ -539,7 +607,7 @@ With NO source video there is no soundtrack to restore and no source for the scr
 `final/out.silent.mp4` to `final/out.mp4` and deliver that, so the deliverable path is the same for
 every run. A silent deliverable is a complete one here, not a failed mux.
 
-### 5.5 PREVIEW — open the localhost preview  · SCRIPT (parallel, non-blocking)
+### PREVIEW — open the localhost preview  · SCRIPT (parallel, non-blocking, runs alongside the rest)
 As soon as render is DONE, launch the preview server in the BACKGROUND, OUTSIDE any sandbox, and continue
 immediately:
 `node --import tsx preview/server.ts runs/<key>`
@@ -565,9 +633,9 @@ Kill the server(s) when the session wraps up.
 - **variety / bold-broadcast** (good for 16:9 landscape): "loud broadcast / sports-lower-third energy; big type in the landscape thirds; heavy effects."
 
 ## Gotchas
-- veed-engine-cli is checked by Step 0 (preflight) — keep it current via `bash pipeline/scripts/install-veed-engine.sh`; macOS-arm64 binary. Older builds lose features (e.g. pre-0.3 = no shadows = major degrade).
-- Sandbox: step 1 (veed/go.ts) needs network egress to `*.veed.io` — a sandboxed
-  `fetch failed` there means the sandbox blocked the call; re-run it outside the sandbox. Step 4's
+- veed-engine-cli is checked by PREFLIGHT — keep it current via `bash pipeline/scripts/install-veed-engine.sh`; macOS-arm64 binary. Older builds lose features (e.g. pre-0.3 = no shadows = major degrade).
+- Sandbox: PREP (veed/go.ts) needs network egress to `*.veed.io` — a sandboxed
+  `fetch failed` there means the sandbox blocked the call; re-run it outside the sandbox. The DESIGN + RENDER step's
   engine `--verify`/`--record` always runs OUTSIDE the sandbox (it needs the window-server).
 - Recipes are COMPILED CODE (`refs/html/<id>/recipe.ts` over the shared `pipeline/recipes/lib.ts`),
   authored + validated OFFLINE, one-time per ref (derived from the ref's prose sheet
@@ -578,9 +646,9 @@ Kill the server(s) when the session wraps up.
 - **USER MATERIALS GET OPENED** (creative face-1): the design pass OPENS and studies the user's
   files/links (that's the point). The opt-in ANALYSE pass stays
   the only agent that reads the FOOTAGE frames.
-- Word timing is NEVER invented — step 4 pastes `word-timings.json` delays verbatim (compiled recipes do
+- Word timing is NEVER invented — DESIGN + RENDER pastes `word-timings.json` delays verbatim (compiled recipes do
   this by construction).
-- The preview server (step 5.5) is loopback-only and additive — if its default port 8978 is busy (an
+- The preview server (PREVIEW) is loopback-only and additive — if its default port 8978 is busy (an
   orphan from a dead session), it self-selects an ephemeral port; trust the URL it prints.
 - TRANSCRIPTION WARNINGS (local provider) — read them precisely, same discipline as the font rules below.
   A WhisperX run prints a wall of `Could not load libtorchcodec`, `dlopen` failures and
diff --git a/AGENTS.md b/AGENTS.md
index ac8da8e..b667673 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,7 +88,7 @@ fast-path/refinement switch.
   reads the FOOTAGE frames** — it writes per-beat facts in CANVAS px to `analysis.json`; the design pass
   composes from those numbers when the file exists (safe margins otherwise) and never opens the frames.
   (User-SUPPLIED materials on face-1 are the one exception to "no vision in design" — studying them is the point.)
-- Engine = `veed-engine-cli` (the veed render engine, downloaded directly from the upstream `veedstudio/weave-renderer-public-releases` repo into `.veed-engine/` via `pipeline/scripts/install-veed-engine.sh`; **Step 0 of the SKILL self-checks the version** vs the latest GitHub release).
+- Engine = `veed-engine-cli` (the veed render engine, downloaded directly from the upstream `veedstudio/weave-renderer-public-releases` repo into `.veed-engine/` via `pipeline/scripts/install-veed-engine.sh`; **the SKILL's PREFLIGHT step self-checks the version** vs the latest GitHub release).
 
 ## Conventions
 - Canvas (probed by prep): the source's own width/height (rotation-corrected) and fps (nominal `r_frame_rate`); `aspect` is an orientation label — 9:16 when h ≥ w, else 16:9. Beat render frame = `round(beatMidSec * fps)`.
@@ -113,7 +113,7 @@ workspace. There is no project-scoped path: the no-project route is the only one
 
 `runs/<key>/transcript.json` is the only seam. Anything that writes that shape is a valid provider and
 nothing downstream can tell which one ran. **There is no default provider**: on a cold start the choice
-belongs to the user (SKILL.md step 1), and picking one for them is a defect, not a shortcut. VEED is
+belongs to the user (SKILL.md, the PREP step), and picking one for them is a defect, not a shortcut. VEED is
 listed first because it transcribes best, not because it wins ties.
 
 | Provider | What it is | Entry point |
@@ -161,7 +161,7 @@ reordered so the caption text and the reveals agree.
 If a transcription MCP is available, prefer one that writes a file and returns its path. Routing
 hundreds of timestamps through model context invites drift in the numbers themselves.
 
-A failed VEED run is classified rather than retried blindly (SKILL.md step 1): out of credits returns to
+A failed VEED run is classified rather than retried blindly (SKILL.md, the PREP step): out of credits returns to
 the provider question with VEED still offered — a free account covers about 10 minutes a month, so
 `veed/orchestrate.ts` names https://www.veed.io/pricing and the local alternative in the error itself; a
 login failure retries the login once; anything else retries the command once. The recorded provider is
@@ -171,6 +171,7 @@ Run the isolated VEED tests without network access:
 
 ```sh
 node --import tsx --test \
-  tests/cli-entry.test.ts tests/oauth.test.ts tests/orchestrate.test.ts tests/token-store.test.ts \
-  tests/transcript-mapper.test.ts
+  tests/cli-entry.test.ts tests/login-page.test.ts tests/oauth.test.ts tests/orchestrate.test.ts \
+  tests/token-store.test.ts \
+  tests/transcript-mapper.test.ts tests/workspace.test.ts
 ```
diff --git a/README.md b/README.md
index 5500bfe..a78b5a5 100644
--- a/README.md
+++ b/README.md
@@ -38,8 +38,9 @@ rather than collapsing every ask onto captions.
 
 | | |
 | --- | --- |
-| Platform | Apple Silicon Mac, macOS Tahoe 26.0 |
-| Intel Macs, earlier macOS | Not supported |
+| Platform | Apple Silicon Mac. Preflight requires macOS on arm64 and stops there |
+| Intel Macs | Not supported — the renderer ships macOS-arm64 only |
+| Older macOS | Built and tested on Tahoe 26.0. Nothing checks the version, so earlier releases may work — untested |
 | Windows, Linux | Planned; prioritisation depends on demand |
 | Transcription | needed only to caption speech — OpenEdit asks once and remembers: VEED ([sign up](https://www.veed.io/signup) / [login](https://www.veed.io/login)), WhisperX locally, or your own service |
 
diff --git a/config.ts b/config.ts
index 1f9a5d5..b63305f 100644
--- a/config.ts
+++ b/config.ts
@@ -13,7 +13,7 @@ export const FFMPEG = process.env.VEED_ENGINE_FFMPEG ?? 'ffmpeg';
 export const FFPROBE = process.env.VEED_ENGINE_FFPROBE
   ?? (process.env.VEED_ENGINE_FFMPEG ? process.env.VEED_ENGINE_FFMPEG.replace(/ffmpeg([^/]*)$/, 'ffprobe$1') : 'ffprobe');
 
-// veed-engine-cli render engine. Step 0 (pipeline/scripts/preflight.sh) checks your binary against the
+// veed-engine-cli render engine. PREFLIGHT (pipeline/scripts/preflight.sh) checks your binary against the
 // latest veedstudio/weave-renderer-public-releases GitHub release (upstream repo name) and offers an
 // install if behind — no version is pinned here. Default: the repo-local .veed-engine/ install produced
 // by pipeline/scripts/install-veed-engine.sh.
@@ -25,3 +25,21 @@ export const WHISPERX_BIN = process.env.WHISPERX_BIN ?? 'whisperx';
 
 // Fallback quality tier, used only until the user's choice is recorded in .open-edit-prefs.json.
 export const WHISPERX_MODEL = process.env.WHISPERX_MODEL ?? 'small.en';
+
+// --- WCAG pass (creative runs run it by default; recipes via --wcag) -------
+// The analyzer is not bundled with the release engine binary; default to a
+// sibling weave-renderer checkout, overridable via the env vars.
+export const WEAVE_RENDERER_ROOT =
+  process.env.WEAVE_RENDERER_ROOT ?? path.join(REPO_ROOT, '..', 'weave-renderer');
+
+// wcag-contrast analyzer binary. Build once in the checkout:
+//   cd src/crates/wcag-contrast && cargo build
+export const WCAG_CONTRAST_BIN =
+  process.env.WCAG_CONTRAST_BIN ??
+  path.join(WEAVE_RENDERER_ROOT, 'src', 'crates', 'wcag-contrast', 'target', 'debug', 'wcag-contrast');
+
+// Remediation applier — lives in this repo (application policy belongs to the
+// consumer). Requires plain `node` (native .ts type-stripping, >=22.18), NOT
+// tsx; wcag-pass spawns it accordingly.
+export const WCAG_REMEDIATE =
+  process.env.WCAG_REMEDIATE ?? path.join(REPO_ROOT, 'pipeline', 'scripts', 'wcag', 'remediate.ts');
diff --git a/docs/FLOW.md b/docs/FLOW.md
index da2fdc5..0ddf551 100644
--- a/docs/FLOW.md
+++ b/docs/FLOW.md
@@ -6,15 +6,15 @@ reference/brand/concept) and creative iteration on a delivered result are author
 The whole thing is encoded executably in `.claude/skills/open-edit/SKILL.md` (the golden master) — this doc
 is the conceptual map. One video → ONE captioned MP4. No per-shot intermediates, no user-approval gate.
 
-| # | step | kind | what |
-|---|------|------|------|
-| 0 | preflight | SCRIPT | check `veed-engine-cli` vs the latest release; offer install if stale/missing |
-| 1 | prep | SCRIPT | transcript from the chosen provider (VEED `veed/go.ts`, local WhisperX `prep/transcribe.ts`, or the user's own via `prep/whisper.ts`; chunks = beats, real per-word timings) → `word-timings.json` (per-word absolute-ms reveal delays, synthesized by `prep/prep.ts`) + base frames; auto-detect aspect → write `meta.json` (canvas + duration + paths) |
-| 2 | analyse | AGENT (vision) | **OPT-IN, skipped by default** — run only when the user asks to refine the style; then ONE nameless bg subagent reads the frames + transcript → `analysis.json` (per-beat shot/bboxes/neg-space/brightness in CANVAS px), and step 4 re-runs with it. The **only** vision pass. `analysis.json` existing IS the fast-path/refinement switch. |
-| 3 | sample ONE style | SCRIPT | `pipeline/scripts/sample-style.ts` — facet-scored seeded draw of one aspect-matched ref from `refs/tags.json` (v3 RUNTIME INDEX, recipes only; `fit` = aspect SOT; transcript energy weights the draw) → `style.json` (facets, energy, coverage, alternates). Zero tokens. The CREATIVE PASS routes here too: face-1 (user brought materials) → step 4 from-scratch; face-2 REMIX (any creative iteration) / RE-ROLL (variants asks) / patch (defects). |
-| 4 | design + render | SCRIPT (recipe) · INLINE (creative face-1 · remix) | default → **compiled recipe** (`pipeline/scripts/generate-recipe.ts`: the generator module emits `final/template.wv` + `manifest.json` deterministically — word delays from `word-timings.json` by construction, zero tokens — then drives the gate chain: lint → `--verify` with the mechanical ladder fix loop (≤2 cycles) → `--record` → probe-qa); **face-1** (INLINE, orchestrator-authored: one design system from the USER'S materials, 1-2 recipe sheets as craft substrate, per `director-brief.md`; lint + `--verify` to exit 0, then `--record` → probe-qa); **REMIX** (inline donor blend per the brief's REMIX MODE in `runs/<key>-remix`, same gates) |
-| 5 | mux audio | SCRIPT | ffmpeg muxes the source audio onto the silent render → `final/out.mp4` (the deliverable) |
-| 5.5 | preview | SCRIPT (parallel) | `preview/server.ts runs/<key>` — localhost preview opened for the user (read-only): watch and scrub the footage, follow the transcript, preview the subtitles; auto-swaps to the new `final/out.mp4` when an amend re-render lands. Launched in the background; the pipeline never waits on it |
+| step | kind | what |
+|------|------|------|
+| preflight | SCRIPT | check `veed-engine-cli` vs the latest release; offer install if stale/missing |
+| prep | SCRIPT | transcript from the chosen provider (VEED `veed/go.ts`, local WhisperX `prep/transcribe.ts`, or the user's own via `prep/whisper.ts`; chunks = beats, real per-word timings) → `word-timings.json` (per-word absolute-ms reveal delays, synthesized by `prep/prep.ts`) + base frames; auto-detect aspect → write `meta.json` (canvas + duration + paths) |
+| analyse | AGENT (vision) | **OPT-IN, skipped by default** — run only when the user asks to refine the style; then ONE nameless bg subagent reads the frames + transcript → `analysis.json` (per-beat shot/bboxes/neg-space/brightness in CANVAS px), and the DESIGN + RENDER step re-runs with it. The **only** vision pass. `analysis.json` existing IS the fast-path/refinement switch. |
+| sample ONE style | SCRIPT | `pipeline/scripts/sample-style.ts` — facet-scored seeded draw of one aspect-matched ref from `refs/tags.json` (v3 RUNTIME INDEX, recipes only; `fit` = aspect SOT; transcript energy weights the draw) → `style.json` (facets, energy, coverage, alternates). Zero tokens. The CREATIVE PASS routes here too: face-1 (user brought materials) → the DESIGN + RENDER step, from-scratch; face-2 REMIX (any creative iteration) / RE-ROLL (variants asks) / patch (defects). |
+| design + render | SCRIPT (recipe) · INLINE (creative face-1 · remix) | default → **compiled recipe** (`pipeline/scripts/generate-recipe.ts`: the generator module emits `final/template.wv` + `manifest.json` deterministically — word delays from `word-timings.json` by construction, zero tokens — then drives the gate chain: lint → `--verify` with the mechanical ladder fix loop (≤2 cycles) → `--record` → probe-qa); **face-1** (INLINE, orchestrator-authored: one design system from the USER'S materials, 1-2 recipe sheets as craft substrate, per `director-brief.md`; lint + `--verify` to exit 0, then `--record` → probe-qa); **REMIX** (inline donor blend per the brief's REMIX MODE in `runs/<key>-remix`, same gates) |
+| mux audio | SCRIPT | ffmpeg muxes the source audio onto the silent render → `final/out.mp4` (the deliverable) |
+| preview | SCRIPT (parallel) | `preview/server.ts runs/<key>` — localhost preview opened for the user (read-only): watch and scrub the footage, follow the transcript, preview the subtitles; auto-swaps to the new `final/out.mp4` when an amend re-render lands. Launched in the background; the pipeline never waits on it |
 
 ## Where quality lives (do not let these drift)
 - **Prep (1)** transcribes with whichever provider the user chose — asked once, recorded in
diff --git a/package.json b/package.json
index e4973d2..a5c892e 100644
--- a/package.json
+++ b/package.json
@@ -9,8 +9,12 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
+    "@types/culori": "^4.0.1",
     "@types/node": "^22.0.0",
     "tsx": "4.21.0",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
   }
 }
diff --git a/pipeline/director-brief.md b/pipeline/director-brief.md
index 95b0fec..1c85a42 100644
--- a/pipeline/director-brief.md
+++ b/pipeline/director-brief.md
@@ -21,7 +21,7 @@ Commit ONE design system in a single pass — do NOT re-litigate the aesthetic o
 extract frames / eyeball the video / run any visual self-check unless the execution contract EXPLICITLY tells you
 to. You do not redesign based on renders, run legibility passes, or chase timing.
 
-Your execution contract (the filled step-4B contract from the SKILL) gives: the run dir, `meta.json` (canvas W/H/fps + `durationSec` + all paths),
+Your execution contract (the filled DESIGN + RENDER variant B contract from the SKILL) gives: the run dir, `meta.json` (canvas W/H/fps + `durationSec` + all paths),
 `transcript.json` (captions + windows), the USER'S MATERIALS (their reference/brand/concept — the design
 authority) plus 1-2 recipe SHEETS as craft substrate, the video path, the DIRECTION, the ENGAGEMENT mode,
 and the ANIMATION LEVEL. `analysis.json` (per-beat composition facts) exists ONLY on style-refine runs — when
@@ -191,14 +191,14 @@ The binary is `{run dir}/../../.veed-engine/veed-engine-cli` (the preflight-mana
 Do NOT extract frames or run any ffmpeg/visual self-check unless the execution contract EXPLICITLY instructs it — --verify
 is the self-check. Author the timeline correctly up front using the recipe + limits above so --verify passes on the
 first pass; it is a safety net, not a design loop. (The last gate, `probe-qa` — mechanical frame QA vs the source —
-runs right after the record (SKILL step 4, same turn); it is not part of this verify loop and never a licence to
+runs right after the record (the SKILL's DESIGN + RENDER step, same turn); it is not part of this verify loop and never a licence to
 eyeball frames.)
 
 ## OUTPUT
 - `{run}/final/template.wv` — the single-timeline document.
 - `{run}/final/manifest.json` — EXACT: `{"render":{"width":{W},"height":{H},"fps":{FPS},"duration":{durationSec}}}`
   (duration covers the FULL clip).
-- `{run}/final/out.silent.mp4` — the render (video only; audio is muxed in step 5).
+- `{run}/final/out.silent.mp4` — the render (video only; audio is muxed in the MUX AUDIO step).
 
 ## REPORT (fold into your summary — after probe-qa + mux, same turn, no preamble)
 - aesthetic name + fonts + hex palette + recurring device.
diff --git a/pipeline/scripts/generate-recipe.ts b/pipeline/scripts/generate-recipe.ts
index e531010..ba7557a 100644
--- a/pipeline/scripts/generate-recipe.ts
+++ b/pipeline/scripts/generate-recipe.ts
@@ -1,4 +1,4 @@
-// Recipe runner — the fast path's step 4 for recipe-backed picks. Loads the compiled recipe for the
+// Recipe runner — the fast path's DESIGN + RENDER for recipe-backed picks. Loads the compiled recipe for the
 // run's sampled ref (refs/html/<id>/recipe.ts), generates runs/<key>/final/{template.wv,
 // manifest.json} deterministically (zero tokens), then optionally drives the full gate chain:
 // lint → --verify (mechanical ladder fix loop) → --record → probe-qa. Run OUTSIDE any sandbox when
@@ -43,17 +43,33 @@ async function main(): Promise<number> {
       module: { type: 'string' },
       record: { type: 'boolean' },
       verify: { type: 'boolean' },
+      wcag: { type: 'boolean' },
+      'wcag-apply': { type: 'boolean' },
       'progress-output': { type: 'boolean' },
     },
   });
   const runArg = values.run;
   if (!runArg) {
-    console.error('usage: node --import tsx pipeline/scripts/generate-recipe.ts --run <runDir> [--verify] [--record] [--module <path>]');
+    console.error('usage: node --import tsx pipeline/scripts/generate-recipe.ts --run <runDir> [--verify] [--record] [--wcag] [--wcag-apply] [--module <path>]');
     return 2;
   }
   const runDir = resolve(runArg);
   const doRecord = values.record ?? false;
   const doVerify = (values.verify ?? false) || doRecord; // record only ever happens on a clean verify
+  // --wcag: opt-in WCAG AA contrast pass between verify and record (DEFAULT on
+  // the creative faces, which run the gates by hand — see the skill; opt-in
+  // here so the recipe fast path stays byte-identical until asked). It runs
+  // DETECT-ONLY: it audits real rendered contrast + emits contrast-statistics.json
+  // and reports, but changes nothing. It only makes sense inside the gate
+  // chain — bare --wcag would run without a rendered final/ to audit.
+  // --wcag-apply implies --wcag and runs the pass in APPLY mode (remediate +
+  // promote a remediated final/template.wv on measured improvement).
+  const doWcagApply = values['wcag-apply'] ?? false;
+  const doWcag = (values.wcag ?? false) || doWcagApply;
+  if (doWcag && !doVerify) {
+    console.error('[generate-recipe] --wcag requires --verify or --record (the WCAG pass runs after a clean verify)');
+    return 2;
+  }
 
   // --module needs no style.json (independent/standalone runs); the sampled-ref path requires it.
   const moduleOverride = values.module;
@@ -73,7 +89,7 @@ async function main(): Promise<number> {
       return 2;
     }
     if (!style.hasRecipe || !existsSync(modPath)) {
-      console.error(`[generate-recipe] no compiled recipe for "${style.refId}" (${modPath}) — run the from-scratch inline pass (SKILL step 4 variant B)`);
+      console.error(`[generate-recipe] no compiled recipe for "${style.refId}" (${modPath}) — run the from-scratch inline pass (SKILL: DESIGN + RENDER variant B)`);
       return 3;
     }
   }
@@ -128,6 +144,21 @@ async function main(): Promise<number> {
     return 1;
   }
 
+  // Gate 3.5 — WCAG: audit real rendered contrast + emit contrast-statistics.json,
+  // then report. DETECT-ONLY: status 'attention' lists every low-contrast
+  // selector but changes nothing — record still consumes the verified final/.
+  if (doWcag) {
+    const { runWcagPass } = await import('./wcag-pass.ts');
+    try {
+      const d = runWcagPass(runDir, { apply: doWcagApply });
+      console.log(`[generate-recipe] wcag: ${d.status}${d.promoted ? ' (remediated template promoted into final/template.wv)' : ''}`);
+      for (const n of d.notes) console.log(`[generate-recipe] wcag: ${n}`);
+    } catch (e) {
+      console.error(String((e as Error).message ?? e));
+      return 1;
+    }
+  }
+
   if (doRecord) {
     const outMp4 = join(finalDir, 'out.silent.mp4');
     const r = spawnSync(VEED_ENGINE_BIN, [finalDir, '--progress-output', '--record', outMp4], { stdio: 'inherit' });
diff --git a/pipeline/scripts/mux-audio.sh b/pipeline/scripts/mux-audio.sh
index 9240472..dbacc4e 100755
--- a/pipeline/scripts/mux-audio.sh
+++ b/pipeline/scripts/mux-audio.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Step 5 — restore the soundtrack. veed-engine-cli renders video only; this muxes the original audio
+# MUX AUDIO — restore the soundtrack. veed-engine-cli renders video only; this muxes the original audio
 # onto the clean silent render. Deterministic; run OUTSIDE any sandbox is NOT required (ffmpeg only).
 #
 #   bash pipeline/scripts/mux-audio.sh <run-dir>
diff --git a/pipeline/scripts/preflight.sh b/pipeline/scripts/preflight.sh
index b1dc173..64c8719 100755
--- a/pipeline/scripts/preflight.sh
+++ b/pipeline/scripts/preflight.sh
@@ -2,6 +2,19 @@
 # Compatibility entrypoint. The installable skill owns the canonical preflight implementation.
 set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# WCAG tooling (report-only, like everything here): the wcag pass is a DEFAULT gate on creative
+# runs and hard-fails at run time when the analyzer is missing — surface that up front instead of
+# mid-pipeline. Path mirrors the config.ts default (env-overridable the same way).
+WEAVE_RENDERER_ROOT="${WEAVE_RENDERER_ROOT:-$REPO_ROOT/../weave-renderer}"
+WCAG_CONTRAST="${WCAG_CONTRAST_BIN:-$WEAVE_RENDERER_ROOT/src/crates/wcag-contrast/target/debug/wcag-contrast}"
+if [ ! -x "$WCAG_CONTRAST" ]; then
+  echo "wcag: analyzer NOT FOUND ('$WCAG_CONTRAST') — the wcag pass will fail. Build it:"
+  echo "  cd $WEAVE_RENDERER_ROOT/src/crates/wcag-contrast && cargo build"
+else
+  echo "wcag: analyzer ok"
+fi
+
 # Only default the workspace when the caller did not give one, otherwise it is passed twice.
 for arg in "$@"; do
   [ "$arg" = "--workspace" ] && exec bash "$REPO_ROOT/.claude/skills/open-edit/scripts/preflight.sh" "$@"
diff --git a/pipeline/scripts/wcag-pass.ts b/pipeline/scripts/wcag-pass.ts
new file mode 100644
index 0000000..b3af4ef
--- /dev/null
+++ b/pipeline/scripts/wcag-pass.ts
@@ -0,0 +1,560 @@
+// WCAG text-contrast pass — DEFAULT gate on creative runs (face-1 AND remix),
+// opt-in on the recipe fast path (generate-recipe.ts --wcag). Level AA.
+//
+// STATISTICS-NATIVE, two modes:
+//  DETECT (default): sample real backgrounds (veed-engine-cli --contrast-audit)
+//    → analyze (wcag-contrast --statistics → the policy-free
+//    final/contrast-statistics.json) → score verdicts and policy IN TS
+//    (verdicts.ts + policy.ts) → summarize and RETURN. Renders nothing,
+//    changes nothing, promotes nothing. Clean → status 'pass'; low-contrast
+//    elements → status 'attention' with the counts, the --apply offer, and one
+//    review line per non-passing selector.
+//  APPLY (--apply): DETECT, then remediate, re-audit the candidate, and
+//    promote. With a studio/chat choice at final/wcag-choice.json the applier
+//    is driven by that explicit choice (--choice) and ALWAYS runs — a clicked
+//    choice always takes effect and promotes unconditionally. With NO choice it
+//    falls back to the automatic hue-preserving colour plan (within-bar
+//    recolors only), promoted only on MEASURED improvement (strictly fewer
+//    failing runs).
+// The analyzer's compliance report is NEVER read — statistics + the TS policy
+// layer are the whole runtime contract.
+//
+// FINAL IS FINAL. On promotion (--apply only), inside final/:
+//   template.draft.wv                  — the pre-remediation original
+//   template.draft.wcag-remediated.wv  — the remediation output (artifact)
+//   template.wv                        — = the remediated content (the
+//                                           engine's required entry name)
+//   template.final.wv                  — clone of the shipping template
+//   wcag-remediation.css               — per-rule evidence comments
+//   wcag-remediation-plan.json + contrast-statistics{,.remediated}.json
+// No directory copies, no video artifacts — the pass renders nothing. A
+// promoted final/ is re---verify'd before the pass returns.
+//
+// TRANSPARENCY IS THE CONTRACT: every non-passing selector is listed with its
+// disposition (will fix / no colour satisfies / halo recommended /
+// indeterminate) — nothing failing goes unlisted, and missing tooling is a
+// HARD failure (exit 1), never a skip.
+//
+//   node --import tsx pipeline/scripts/wcag-pass.ts --run runs/<key> [--apply]
+//
+// Requires (until releases bundle them — see config.ts): a weave-renderer
+// checkout providing the wcag-contrast binary.
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VEED_ENGINE_BIN, WCAG_CONTRAST_BIN, WCAG_REMEDIATE } from '../../config.ts';
+import {
+  effectiveThreshold,
+  guaranteedFix,
+  relativeLuminance,
+  rollUpPolicy,
+  type ClassPolicyResult,
+  type RecOption,
+  type RunPolicyInput,
+} from './wcag/policy.ts';
+import { resolveCreditedVerdicts } from './wcag/credited-verdicts.ts';
+import { hex, type RemediationPlan } from './wcag/remediate.ts';
+import { parseElementClasses, resolveVerdicts, type Statistics } from './wcag/verdicts.ts';
+
+// The analyzer CLI's default knobs; the gate scores with the same values.
+export const DEFAULT_BAR = 0.1;
+export const DEFAULT_MIN_LEAD_RATIO = 2.0;
+
+// --- pure helpers (unit-tested in tests/wcag-pass.test.ts) ------------------
+
+export interface WcagRunSummary {
+  passed: boolean;
+  totalRuns: number;
+  failingRuns: number;
+  indeterminateRuns: number;
+  /** True when ANY within-bar recolor exists at class OR exception level —
+   * i.e. the applier would change at least one rule. */
+  anyApplicable: boolean;
+  /** EXHAUSTIVE per-selector dispositions — every class/exception that is not
+   * already passing gets a line; nothing is ever suppressed. */
+  dispositions: string[];
+}
+
+// The roll-up key rule: classed -> `.name`, class-less -> `#id`.
+const keyFor = (r: RunPolicyInput) => (r.className !== null ? `.${r.className}` : `#${r.id}`);
+
+// One statistics element -> the roll-up's policy input. `passes` is the TS
+// verdict at AA (verdicts.ts); `requiredRatio` is the STRICTEST per-frame
+// threshold (font metrics may vary across peak frames).
+function policyInput(
+  elt: Statistics['elements'][number], passes: boolean, className: string | null,
+): RunPolicyInput {
+  const sampled = elt.frames.filter((f) => !f.unsampled);
+  const requiredRatio = sampled.length
+    ? Math.max(...sampled.map((f) => effectiveThreshold('AA', f.font_size, f.font_weight, null)))
+    : effectiveThreshold('AA', elt.font_size, elt.font_weight, null);
+  const anyUnsampled = elt.frames.some((f) => f.unsampled) || (elt.unsampled_frames?.n ?? 0) > 0;
+  const clusters = elt.clusters.map((c) => ({ color: c.color, weight: c.weight }));
+  return {
+    id: elt.id,
+    className,
+    fg: { r: elt.fg.r, g: elt.fg.g, b: elt.fg.b },
+    fgAlpha: elt.steady_alpha,
+    requiredRatio,
+    bgLums: clusters.map((c) => relativeLuminance(c.color)),
+    clusters,
+    totalSamples: elt.total_samples,
+    indeterminate: elt.indeterminate || anyUnsampled,
+    passes,
+  };
+}
+
+// One selector's outcome: the within-bar recolor the auto path applies (or
+// null), and its disposition line. The single source both the summary and the
+// remediation plan are built from.
+interface SelectorOutcome {
+  selector: string;
+  applied: RecOption | null;
+  disposition: string;
+}
+
+// A within-bar recolor leads and is the auto-appliable fix; otherwise a
+// guaranteed halo/backing (recommended, never auto-applied — colours-only
+// policy); otherwise the honest negatives.
+function outcomeFor(
+  selector: string, opts: RecOption[], kind: 'class' | 'exception',
+  haloInput: { fg: RunPolicyInput['fg']; r: number; a: number },
+): SelectorOutcome {
+  const lead = opts[0];
+  if (lead && lead.withinBar) {
+    return { selector, applied: lead, disposition: `${selector}: will fix (${kind} recolor)` };
+  }
+  const gf = guaranteedFix(haloInput.fg, haloInput.r, haloInput.a);
+  const disposition = gf
+    ? `${selector}: ${gf.kind === 'halo' ? 'halo' : 'recolor+backing'} recommended — not auto-applied (colours-only policy), human review`
+    : lead
+      ? `${selector}: no colour satisfies AA within policy (best colour above bar) — human review`
+      : `${selector}: no feasible fix computed — human review`;
+  return { selector, applied: null, disposition };
+}
+
+// TS verdicts + the class roll-up over the statistics, walked into per-selector
+// outcomes. Pure.
+function analyzeStatistics(stats: Statistics, classOf: (id: string) => string | null) {
+  const verdicts = resolveVerdicts(stats);
+  const passing = new Map(verdicts.elements.map((e) => [e.id, e.aa]));
+  const inputs = stats.elements.map((elt) =>
+    policyInput(elt, passing.get(elt.id) ?? false, classOf(elt.id)),
+  );
+  const byId = new Map(inputs.map((i) => [i.id, i]));
+  const members = new Map<string, RunPolicyInput[]>();
+  for (const i of inputs) {
+    const key = keyFor(i);
+    if (!members.has(key)) members.set(key, []);
+    members.get(key)!.push(i);
+  }
+
+  const classes: ClassPolicyResult[] = rollUpPolicy(inputs, DEFAULT_BAR, DEFAULT_MIN_LEAD_RATIO);
+  const outcomes: SelectorOutcome[] = [];
+  for (const c of classes) {
+    if (c.recolorOptions.length === 0 && c.exceptions.length === 0) continue; // tier 0 — passing
+    // Class-level halo check mirrors rollupClass's option inputs: the first
+    // determinate member's fg/alpha at the class's strictest required ratio.
+    // A class line is emitted whenever a determinate member fails — even with
+    // no recolor options (the halo/no-fix negatives still need saying).
+    const determinate = (members.get(c.classKey) ?? []).filter((m) => !m.indeterminate);
+    if (determinate.some((m) => !m.passes)) {
+      const maxR = determinate.reduce((r, m) => Math.max(r, m.requiredRatio), 0.0);
+      const halo = { fg: determinate[0].fg, r: maxR, a: determinate[0].fgAlpha };
+      outcomes.push(outcomeFor(c.classKey, c.recolorOptions, 'class', halo));
+    }
+    for (const e of c.exceptions) {
+      if (e.indeterminate) {
+        outcomes.push({
+          selector: `#${e.id}`,
+          applied: null,
+          disposition: `#${e.id}: indeterminate — background unsampleable; no sound fix`,
+        });
+        continue;
+      }
+      const m = byId.get(e.id)!;
+      const halo = { fg: m.fg, r: m.requiredRatio, a: m.fgAlpha };
+      outcomes.push(outcomeFor(`#${e.id}`, e.recolorOptions, 'exception', halo));
+    }
+  }
+  return { verdicts, outcomes };
+}
+
+// Compress the statistics into what the gate reasons about. Pure.
+export function summarizeStatistics(
+  stats: Statistics, classOf: (id: string) => string | null,
+): WcagRunSummary {
+  const { verdicts, outcomes } = analyzeStatistics(stats, classOf);
+  return {
+    passed: verdicts.failingAA === 0,
+    totalRuns: stats.elements.length,
+    failingRuns: verdicts.failingAA,
+    indeterminateRuns: verdicts.indeterminateCount,
+    anyApplicable: outcomes.some((o) => o.applied !== null),
+    dispositions: outcomes.map((o) => o.disposition),
+  };
+}
+
+// The automatic colours-only remediation plan the applier consumes: one rule
+// per within-bar recolor lead, every unapplied recommendation carried as a
+// note so the emitted CSS keeps the full review trail. Pure.
+export function buildRemediationPlan(
+  stats: Statistics, classOf: (id: string) => string | null,
+): RemediationPlan {
+  const { outcomes } = analyzeStatistics(stats, classOf);
+  return {
+    level: 'AA',
+    rules: outcomes
+      .filter((o) => o.applied !== null)
+      .map((o) => ({
+        selector: o.selector,
+        hex: hex(o.applied!.fix.color),
+        massPct: o.applied!.estimatedFailure.mass * 100,
+        worstRatio: o.applied!.estimatedFailure.worstRatio,
+      })),
+    notes: outcomes.filter((o) => o.applied === null).map((o) => o.disposition),
+  };
+}
+
+export type WcagStatus = 'pass' | 'attention' | 'remediated' | 'not-improved' | 'residual';
+
+export interface WcagDecision {
+  status: WcagStatus;
+  /** True iff the remediated template was PROMOTED into final/template.wv.
+   * Always false in DETECT mode — detect never writes. */
+  promoted: boolean;
+  notes: string[];
+}
+
+// DETECT-mode decision (default): report only, never promote. Clean → 'pass';
+// otherwise 'attention' whose FIRST note is a single product-voice offer line
+// naming the two remediation routes (recommendation studio OR --apply),
+// followed by the exhaustive per-selector dispositions. `runDir` is spliced
+// into the recommend.ts command so the offer is copy-pasteable. `choicePending`
+// (a wcag-choice.json the studio/chat wrote) adds a clause pointing at it — the
+// caller passes the file-existence boolean; the pure layer does no I/O. Pure.
+export function wcagDetectDecision(
+  before: WcagRunSummary,
+  runDir: string,
+  choicePending = false,
+): WcagDecision {
+  if (before.passed) {
+    // A passing run with NO pending choice is plainly clean. But a pending
+    // studio/chat choice (e.g. an AAA tweak on an AA-passing run) must NOT be
+    // silently dropped — surface it as 'attention' with the pending clause only.
+    if (!choicePending) {
+      return { status: 'pass', promoted: false, notes: ['WCAG AA: all text runs pass'] };
+    }
+    return {
+      status: 'attention',
+      promoted: false,
+      notes: ['WCAG AA: all text runs pass at the current level; a studio choice is pending — apply it (wcag-pass --apply)'],
+    };
+  }
+  const offer =
+    `WCAG AA: ${before.failingRuns} of ${before.totalRuns} text elements have low contrast — ` +
+    `see recommendations (node --import tsx pipeline/scripts/wcag/recommend.ts --run ${runDir}) ` +
+    `or apply the automatic colour fixes (wcag-pass --apply)` +
+    (choicePending ? `; a studio choice is pending — apply it (wcag-pass --apply)` : ``);
+  return {
+    status: 'attention',
+    promoted: false,
+    notes: [offer, ...before.dispositions.map((d) => `review: ${d}`)],
+  };
+}
+
+// Whether the APPLY path runs the remediation applier. A pending studio/chat
+// choice ALWAYS runs it — a clicked choice always takes effect, even on an
+// AA-passing run carrying only an AAA tweak. With no choice, the AUTO path runs
+// only when the run fails AND a colours-only fix is applicable. Pure.
+export function shouldRunApplier(passed: boolean, anyApplicable: boolean, hasChoice: boolean): boolean {
+  return hasChoice || (!passed && anyApplicable);
+}
+
+// Promotion rule: AUTO remediation promotes ONLY on measured improvement —
+// strictly fewer failing runs after remediation. A USER-CHOSEN option
+// (choiceApplied) promotes unconditionally, EVEN on an otherwise-passing run:
+// the click/chat pick IS the decision; the re-audit numbers are reported as
+// context, never a veto. The note credits the falloff model ONLY when a
+// shadow/outline was actually applied (the sampler can't see those); a
+// colour/background choice is measured directly. Pure.
+export function wcagPassDecision(
+  before: WcagRunSummary, after: WcagRunSummary | null,
+  opts: { choiceApplied?: boolean; appliedKinds?: string[] } = {},
+): WcagDecision {
+  // A user-chosen option, once applied (after !== null), always promotes —
+  // checked BEFORE the passing short-circuit so a choice on a passing run is
+  // never dropped.
+  if (opts.choiceApplied && after) {
+    const kinds = opts.appliedKinds ?? [];
+    const creditsFalloff = kinds.some((k) => k === 'shadow' || k === 'outline');
+    const creditPhrase = creditsFalloff
+      ? '(shadows/outlines credited via the falloff model)'
+      : '(measured directly)';
+    return {
+      status: 'remediated',
+      promoted: true,
+      notes: [
+        `WCAG AA: your chosen option is applied — re-audit: ${before.failingRuns} -> ${after.failingRuns} failing ${creditPhrase}`,
+        ...after.dispositions.map((d) => `review (post-remediation re-audit): ${d}`),
+      ],
+    };
+  }
+  if (before.passed) {
+    return { status: 'pass', promoted: false, notes: ['WCAG AA: all text runs pass'] };
+  }
+  const residue = before.dispositions.map((d) => `review: ${d}`);
+  if (!after) {
+    return {
+      status: 'residual',
+      promoted: false,
+      notes: [`WCAG AA: ${before.failingRuns} of ${before.totalRuns} run(s) fail and no colour fix applies`, ...residue],
+    };
+  }
+  if (after.failingRuns < before.failingRuns) {
+    return {
+      status: 'remediated',
+      promoted: true,
+      notes: [
+        `WCAG AA: remediation promoted — ${before.failingRuns - after.failingRuns} of ${before.failingRuns} failing run(s) now pass`,
+        // The re-audit's dispositions describe the PROMOTED template — "will
+        // fix" there means a further pass could still improve it (single-pass
+        // by design); the prefix keeps that context explicit.
+        ...after.dispositions.map((d) => `review (post-remediation re-audit): ${d}`),
+      ],
+    };
+  }
+  return {
+    status: 'not-improved',
+    promoted: false,
+    notes: [
+      `WCAG AA: remediation did NOT improve (${before.failingRuns} -> ${after.failingRuns} failing) — original kept; artifacts retained for inspection`,
+      ...residue,
+    ],
+  };
+}
+
+// One promotion file-operation, relative to final/. `rename` moves (and thus
+// consumes the source); `copy` duplicates.
+export interface PromotionOp {
+  kind: 'rename' | 'copy';
+  from: string;
+  to: string;
+  reason: string;
+}
+
+// PURE plan of the promotion file-ops, given the pre-promotion state of final/.
+// Ordered so execution is a straight for-loop. Three lifecycle rules:
+//  - NEVER overwrite an existing template.draft.wv: the draft is the ORIGINAL,
+//    captured at the FIRST promotion only; later promotions leave it untouched
+//    and just re-point template.wv at the new remediation.
+//  - a CHOICE that was applied is ARCHIVED (wcag-choice.json -> .applied.json)
+//    so a stale click cannot silently re-promote forever.
+//  - at the FIRST promotion, an existing pre-apply render is SNAPSHOTTED
+//    (out.silent.mp4 -> out.draft.silent.mp4, and the muxed out.mp4 if present)
+//    so a before/after comparison stays possible.
+export function planPromotion(state: {
+  draftExists: boolean;
+  choiceApplied: boolean;
+  renderExists: boolean;
+  muxedExists: boolean;
+}): PromotionOp[] {
+  const ops: PromotionOp[] = [];
+  const firstPromotion = !state.draftExists;
+  if (firstPromotion && state.renderExists) {
+    ops.push({ kind: 'rename', from: 'out.silent.mp4', to: 'out.draft.silent.mp4', reason: 'snapshot pre-apply silent render' });
+    if (state.muxedExists) {
+      ops.push({ kind: 'rename', from: 'out.mp4', to: 'out.draft.mp4', reason: 'snapshot pre-apply muxed render' });
+    }
+  }
+  if (firstPromotion) {
+    ops.push({ kind: 'rename', from: 'template.wv', to: 'template.draft.wv', reason: 'preserve pre-remediation original' });
+  }
+  ops.push({ kind: 'copy', from: 'template.draft.wcag-remediated.wv', to: 'template.wv', reason: 'promote remediated template' });
+  ops.push({ kind: 'copy', from: 'template.wv', to: 'template.final.wv', reason: 'mark shipping template final' });
+  // Archive a consumed choice so it cannot re-promote on a later bare --apply.
+  if (state.choiceApplied) {
+    ops.push({ kind: 'rename', from: 'wcag-choice.json', to: 'wcag-choice.applied.json', reason: 'archive consumed studio/chat choice' });
+  }
+  return ops;
+}
+
+// Entry-point check that survives percent-encodable paths (spaces etc.). Pure.
+export function isMainModule(argvPath: string | undefined, moduleUrl: string): boolean {
+  return !!argvPath && path.resolve(argvPath) === fileURLToPath(moduleUrl);
+}
+
+// remediate.ts runs under plain node native type-stripping (>=22.18 / >=23).
+export function nodeVersionSupportsTsStripping(version: string): boolean {
+  const [maj, min] = version.replace(/^v/, '').split('.').map(Number);
+  return maj >= 23 || (maj === 22 && min >= 18);
+}
+
+export function missingToolError(tool: 'engine' | 'analyzer' | 'remediate', p: string): string {
+  switch (tool) {
+    case 'engine':
+      return `wcag-pass: veed-engine-cli not found at ${p} — run pipeline/scripts/install-veed-engine.sh or set VEED_ENGINE_BIN`;
+    case 'analyzer':
+      return `wcag-pass: analyzer not found at ${p} — build it (cd <weave-renderer>/src/crates/wcag-contrast && cargo build) or set WCAG_CONTRAST_BIN / WEAVE_RENDERER_ROOT`;
+    case 'remediate':
+      return `wcag-pass: remediation applier not found at ${p} — it ships in-repo at pipeline/scripts/wcag/remediate.ts; set WCAG_REMEDIATE to point at it`;
+  }
+}
+
+// --- the pass (spawns real tools; not covered by unit tests) ----------------
+
+function sh(bin: string, args: string[], okCodes: number[], quietStdout = false): void {
+  const r = spawnSync(bin, args, { stdio: ['ignore', quietStdout ? 'ignore' : 'inherit', 'inherit'] });
+  if (r.error) {
+    throw new Error(`wcag-pass: failed to spawn ${bin}: ${r.error.message}`);
+  }
+  if (r.status === null || !okCodes.includes(r.status)) {
+    const how = r.status === null ? `killed by signal ${r.signal}` : `exited ${r.status}`;
+    throw new Error(`wcag-pass: ${bin} ${args.join(' ')} ${how}`);
+  }
+}
+
+// Sample + analyze one template dir: engine --contrast-audit, then the
+// analyzer for statistics only (no -o, so its unused report goes to stdout —
+// silenced; exit 1 = failing runs, a valid outcome).
+function audit(templateDir: string, samplesPath: string, statsPath: string): Statistics {
+  sh(VEED_ENGINE_BIN, [templateDir, '--contrast-audit', samplesPath, '--audit-fps', '5'], [0]);
+  sh(WCAG_CONTRAST_BIN, [samplesPath, '--statistics', statsPath], [0, 1], true);
+  return JSON.parse(readFileSync(statsPath, 'utf8'));
+}
+
+function classOfDir(templateDir: string): (id: string) => string | null {
+  const classes = parseElementClasses(readFileSync(path.join(templateDir, 'template.wv'), 'utf8'));
+  return (id) => classes.get(id) ?? null;
+}
+
+export function runWcagPass(runDir: string, opts: { apply?: boolean } = {}): WcagDecision {
+  const finalDir = path.join(runDir, 'final');
+  const sibling = `${finalDir}.wcag-remediated`; // applier impl detail; removed before return
+  // A studio click (or chat "apply ...") writes final/wcag-choice.json; when it
+  // is present the applier is driven by that explicit choice (--choice) and
+  // ALWAYS runs. Its presence also surfaces in the detect offer as a "choice
+  // pending" clause.
+  const choiceFile = path.join(finalDir, 'wcag-choice.json');
+  const hasChoice = existsSync(choiceFile);
+  // DETECT needs only the engine + analyzer; the remediation applier (and the
+  // Node type-stripping it needs) is an APPLY-only requirement — checked there.
+  for (const [tool, p] of [['engine', VEED_ENGINE_BIN], ['analyzer', WCAG_CONTRAST_BIN]] as const) {
+    if (!existsSync(p)) throw new Error(missingToolError(tool, p));
+  }
+
+  const stats = audit(
+    finalDir,
+    path.join(finalDir, 'wcag-contrast-samples.json'),
+    path.join(finalDir, 'contrast-statistics.json'),
+  );
+  const classOf = classOfDir(finalDir);
+  const before = summarizeStatistics(stats, classOf);
+
+  // DEFAULT: detect + report, no remediation, no promotion, no sibling dir.
+  if (!opts.apply) {
+    return wcagDetectDecision(before, runDir, hasChoice);
+  }
+
+  // APPLY: plan, remediate, re-audit, promote on measured improvement, re-verify.
+  if (!existsSync(WCAG_REMEDIATE)) throw new Error(missingToolError('remediate', WCAG_REMEDIATE));
+  if (!nodeVersionSupportsTsStripping(process.version)) {
+    throw new Error(`wcag-pass: Node ${process.version} cannot run the remediation applier (needs native .ts type-stripping: >=22.18 or >=23)`);
+  }
+
+  let after: WcagRunSummary | null = null;
+  try {
+    if (shouldRunApplier(before.passed, before.anyApplicable, hasChoice)) {
+      // --choice REPLACES --plan (the applier treats them as mutually exclusive
+      // modes: auto colours vs user-chosen).
+      let sourceArgs: string[];
+      if (hasChoice) {
+        sourceArgs = ['--choice', choiceFile];
+      } else {
+        const planPath = path.join(finalDir, 'wcag-remediation-plan.json');
+        writeFileSync(planPath, JSON.stringify(buildRemediationPlan(stats, classOf), null, 2) + '\n');
+        sourceArgs = ['--plan', planPath];
+      }
+      sh('node', [WCAG_REMEDIATE, ...sourceArgs, '--template-dir', finalDir], [0]);
+      const afterStats = audit(
+        sibling,
+        path.join(sibling, 'wcag-contrast-samples.json'),
+        path.join(finalDir, 'contrast-statistics.remediated.json'),
+      );
+      after = summarizeStatistics(afterStats, classOfDir(sibling));
+      // Harvest the file artifacts out of the sibling before it is removed.
+      copyFileSync(path.join(sibling, 'template.wv'), path.join(finalDir, 'template.draft.wcag-remediated.wv'));
+      copyFileSync(path.join(sibling, 'wcag-remediation.css'), path.join(finalDir, 'wcag-remediation.css'));
+    }
+  } finally {
+    rmSync(sibling, { recursive: true, force: true });
+  }
+
+  const appliedKinds =
+    hasChoice && after !== null
+      ? ((JSON.parse(readFileSync(choiceFile, 'utf8')).chosen ?? []) as { kind: string }[]).map((c) => String(c.kind))
+      : [];
+  const decision = wcagPassDecision(before, after, { choiceApplied: hasChoice && after !== null, appliedKinds });
+  // CREDITED re-audit (falloff model IN THE TS RESOLVER): the sampler cannot
+  // see an applied shadow/outline, so the resolver blends the falloff-covered
+  // treatment over the re-audit's sampled clusters and reports the credited
+  // counts alongside. Samples are used as-is. Colour/background-only choices
+  // are measured directly by the re-audit — nothing to credit, so no resolver
+  // line.
+  if (hasChoice && after !== null && appliedKinds.some((k) => k === 'shadow' || k === 'outline')) {
+    try {
+      const stats = JSON.parse(readFileSync(path.join(finalDir, 'contrast-statistics.remediated.json'), 'utf8')) as Statistics;
+      const entries = JSON.parse(readFileSync(choiceFile, 'utf8')).chosen;
+      const classes = parseElementClasses(readFileSync(path.join(finalDir, 'template.draft.wcag-remediated.wv'), 'utf8'));
+      const credited = resolveCreditedVerdicts(stats, entries, (id: string) => classes.get(id) ?? null);
+      decision.notes.splice(1, 0, `credited re-audit (falloff model, TS resolver): ${credited.failingAA} of ${credited.elements.length} failing at AA`);
+    } catch (e) {
+      decision.notes.splice(1, 0, `credited re-audit unavailable: ${(e as Error).message ?? e}`);
+    }
+  }
+  if (decision.promoted) {
+    // FINAL IS FINAL: execute the pure promotion plan (draft preservation,
+    // choice archival, pre-apply render snapshot — see planPromotion).
+    const plan = planPromotion({
+      draftExists: existsSync(path.join(finalDir, 'template.draft.wv')),
+      choiceApplied: hasChoice && after !== null,
+      renderExists: existsSync(path.join(finalDir, 'out.silent.mp4')),
+      muxedExists: existsSync(path.join(finalDir, 'out.mp4')),
+    });
+    for (const op of plan) {
+      const from = path.join(finalDir, op.from);
+      const to = path.join(finalDir, op.to);
+      if (op.kind === 'rename') renameSync(from, to);
+      else copyFileSync(from, to);
+    }
+    // The promoted final/ must hold the same structural guarantee the record
+    // step relies on: verify-clean. Colours-only edits cannot move geometry,
+    // so this is expected to pass; a failure here is loud (throw -> exit 1)
+    // with template.draft.wv preserved for rollback.
+    sh(VEED_ENGINE_BIN, [finalDir, '--verify'], [0]);
+  }
+  return decision;
+}
+
+// --- CLI --------------------------------------------------------------------
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  const i = process.argv.indexOf('--run');
+  const runDir = i >= 0 ? process.argv[i + 1] : undefined;
+  const apply = process.argv.includes('--apply');
+  if (!runDir) {
+    console.error('usage: node --import tsx pipeline/scripts/wcag-pass.ts --run runs/<key> [--apply]');
+    process.exit(1);
+  }
+  try {
+    const d = runWcagPass(runDir, { apply });
+    console.log(`[wcag-pass] status: ${d.status}${d.promoted ? ' (final/template.wv is now the remediated template; draft preserved)' : ''}`);
+    for (const n of d.notes) console.log(`[wcag-pass] ${n}`);
+    process.exit(0);
+  } catch (e: any) {
+    console.error(String(e.message ?? e));
+    process.exit(1);
+  }
+}
diff --git a/pipeline/scripts/wcag/credited-verdicts.ts b/pipeline/scripts/wcag/credited-verdicts.ts
new file mode 100644
index 0000000..654b06b
--- /dev/null
+++ b/pipeline/scripts/wcag/credited-verdicts.ts
@@ -0,0 +1,160 @@
+// CREDITED re-audit resolver — applies the Gaussian falloff model IN TS, over the
+// policy-free contrast-statistics as-is (NO rendering / weave-renderer changes,
+// no re-sampling). Given the APPLIED choice entries, it credits shadow/outline
+// treatments against every element and returns credited verdicts.
+//
+// - SHADOW: blend the falloff-covered shadow (the entry's recipe: `layers` × `blur`
+//   at alpha SHADOW_ALPHA) over EACH sampled cluster, then score fg-vs-blended.
+//   Background-dependent, per-frame for the worst-frame verdict.
+// - OUTLINE: fg vs the outline colour ONLY — the outline replaces the background,
+//   so the sampled clusters play no part.
+// - Everything else (unshadowed, or colour/background choices) scores AS-IS from
+//   the raw statistics (uncredited).
+//
+// The raw verdicts (verdicts.ts) stay untouched/uncredited — this is a SEPARATE
+// credited interpretation for the apply-path after-summary. Pure; the caller
+// (wcag-pass.ts) supplies `classOf` so class-key selectors (".w") can match.
+
+import {
+  compositeLuminance,
+  ratioFromLuminance,
+  relativeLuminance,
+  threshold,
+  type Level,
+  type Rgba,
+  type Srgb8,
+} from "./policy.ts";
+import { SHADOW_ALPHA, layerCoverage, outlineRatio, type ElementStat, type FrameStat, type Statistics } from "./recommend.ts";
+import { DEFAULT_SHADOW_RECIPE, type ChoiceEntry } from "./wcag-choice.ts";
+
+export type CreditKind = "shadow" | "outline";
+
+export interface CreditedElement {
+  id: string;
+  aa: boolean;
+  aaa: boolean;
+  /** Worst per-sampled-frame ratio (credited when a shadow/outline covers it). */
+  worstFrameRatio: number;
+  /** Which treatment was credited, or null (scored as-is). */
+  credited: CreditKind | null;
+}
+
+export interface CreditedResult {
+  elements: CreditedElement[];
+  failingAA: number;
+  failingAAA: number;
+}
+
+const hexToSrgb = (h: string): Srgb8 => ({ r: parseInt(h.slice(1, 3), 16), g: parseInt(h.slice(3, 5), 16), b: parseInt(h.slice(5, 7), 16) });
+
+// Does a (comma-joined) CSS selector cover this element? `#id` matches by id;
+// `.cls` matches when classOf(id) === cls (the caller supplies the class map).
+function selectorCovers(selector: string, id: string, classOf?: (id: string) => string | null): boolean {
+  for (const raw of selector.split(",")) {
+    const tok = raw.trim();
+    if (tok.startsWith("#") && tok.slice(1) === id) return true;
+    if (tok.startsWith(".") && classOf && classOf(id) === tok.slice(1)) return true;
+  }
+  return false;
+}
+function entryCovers(entry: ChoiceEntry, id: string, classOf?: (id: string) => string | null): boolean {
+  if (entry.split) return entry.split.some((p) => selectorCovers(p.selector, id, classOf));
+  return entry.selector ? selectorCovers(entry.selector, id, classOf) : false;
+}
+// The applied colour for this element: a split part's own hex, else the entry hex.
+function appliedColour(entry: ChoiceEntry, id: string, classOf?: (id: string) => string | null): string {
+  if (entry.split) {
+    const p = entry.split.find((s) => selectorCovers(s.selector, id, classOf));
+    if (p) return p.hex;
+  }
+  return entry.hex;
+}
+
+// Ratio of `fg` over a background cluster, optionally with a shadow stack blended
+// over the cluster first (each layer at its own coverage `C`).
+function creditedRatio(fg: Rgba, clusterColor: Srgb8, layerCoverages: number[] | null, shadow: Srgb8 | null): number {
+  let lBg = relativeLuminance(clusterColor);
+  if (layerCoverages && shadow) {
+    const lShadow = relativeLuminance(shadow);
+    for (const C of layerCoverages) lBg = compositeLuminance(lShadow, C, lBg);
+  }
+  const lFg = compositeLuminance(relativeLuminance(fg), fg.a, lBg);
+  return ratioFromLuminance(lFg, lBg);
+}
+
+interface Credit {
+  kind: CreditKind;
+  shadow?: Srgb8;
+  layerCoverages?: number[];
+  outlineColour?: Srgb8;
+}
+
+// Per-element credited verdict: worst-FRAME scoring (each sampled frame with its
+// OWN fg/font metrics; the run's worst is the min across frames; aa/aaa require
+// every sampled frame to clear the per-frame threshold).
+function verdictFor(elt: ElementStat, credit: Credit | null): CreditedElement {
+  const sampled = elt.frames.filter((f) => !f.unsampled);
+  if (elt.indeterminate || sampled.length === 0) {
+    return { id: elt.id, aa: false, aaa: false, worstFrameRatio: 0, credited: credit?.kind ?? null };
+  }
+  let worst = Infinity;
+  let aa = true;
+  let aaa = true;
+  for (const f of sampled) {
+    const frameWorst = worstFrameRatio(f, credit);
+    if (frameWorst < threshold("AA", f.font_size, f.font_weight)) aa = false;
+    if (frameWorst < threshold("AAA", f.font_size, f.font_weight)) aaa = false;
+    if (frameWorst < worst) worst = frameWorst;
+  }
+  return { id: elt.id, aa, aaa, worstFrameRatio: worst === Infinity ? 0 : worst, credited: credit?.kind ?? null };
+}
+
+function worstFrameRatio(f: FrameStat, credit: Credit | null): number {
+  // OUTLINE replaces the background — fg vs the outline colour, cluster-independent.
+  if (credit?.kind === "outline") return outlineRatio(f.fg, credit.outlineColour!);
+  let worst = Infinity;
+  for (const cl of f.clusters) {
+    const ratio =
+      credit?.kind === "shadow"
+        ? creditedRatio(f.fg, cl.color, credit.layerCoverages!, credit.shadow!)
+        : creditedRatio(f.fg, cl.color, null, null);
+    if (ratio < worst) worst = ratio;
+  }
+  return f.clusters.length === 0 ? 0 : worst; // no adjacent bg sampled on this frame
+}
+
+// THE entry point (wcag-pass.ts wires this into the apply-path after-summary).
+// `appliedEntries` = the applied wcag-choice.json entries; only shadow/outline
+// are credited. `classOf` maps an element id to its declared class so class-key
+// selectors match (from the template; id-only matching works without it).
+export function resolveCreditedVerdicts(
+  statistics: Statistics,
+  appliedEntries: ChoiceEntry[],
+  classOf?: (id: string) => string | null,
+): CreditedResult {
+  const elements = statistics.elements.map((elt) => {
+    const entry = appliedEntries.find(
+      (e) => (e.kind === "shadow" || e.kind === "outline") && entryCovers(e, elt.id, classOf),
+    );
+    let credit: Credit | null = null;
+    if (entry) {
+      const colour = hexToSrgb(appliedColour(entry, elt.id, classOf));
+      if (entry.kind === "outline") {
+        credit = { kind: "outline", outlineColour: colour };
+      } else {
+        const { layers, blur } = entry.recipe ?? DEFAULT_SHADOW_RECIPE;
+        const C = layerCoverage(SHADOW_ALPHA, blur, 0, 0); // centered
+        credit = { kind: "shadow", shadow: colour, layerCoverages: Array(layers).fill(C) };
+      }
+    }
+    return verdictFor(elt, credit);
+  });
+  return {
+    elements,
+    failingAA: elements.filter((e) => !e.aa).length,
+    failingAAA: elements.filter((e) => !e.aaa).length,
+  };
+}
+
+// Re-export for the caller's convenience (parity with the studio's model).
+export type { Level };
diff --git a/pipeline/scripts/wcag/policy.ts b/pipeline/scripts/wcag/policy.ts
new file mode 100644
index 0000000..befd1f4
--- /dev/null
+++ b/pipeline/scripts/wcag/policy.ts
@@ -0,0 +1,592 @@
+// WCAG contrast POLICY layer. Semantics match weave-renderer's wcag-contrast
+// analyzer. Unit-tested with hand-derived cases in tests/wcag-policy.test.ts.
+//
+// SCOPE: the pooled-cluster policy math only — per-cluster ratios, feasibility,
+// hue-preserving recolor candidates/selection, estimated-failure numbers,
+// option_within_bar, and the class roll-up tiers. Per-frame verdict scoring
+// lives in verdicts.ts (it needs the per-frame statistics).
+//
+// Color math delegates to culori (luminance, Oklab/Oklch conversions); only
+// WCAG-specific policy formulas (ratio, thresholds, alpha compositing) are
+// written out here.
+
+import { oklch, rgb, wcagLuminance } from 'culori';
+
+export type Level = "AA" | "AAA";
+export interface Srgb8 { r: number; g: number; b: number }
+export interface Rgba extends Srgb8 { a: number }
+export interface RecCluster { color: Srgb8; weight: number }
+export type Strategy = "hue_preserving" | "anchor" | "hue_shift";
+
+export interface Fix {
+  kind: "recolor" | "halo" | "recolor_with_backing";
+  color: Srgb8;
+  strategy?: Strategy;
+  backing?: Srgb8;
+}
+
+export interface EstimatedFailure {
+  mass: number;
+  worstRatio: number;
+  massBelowFloor: number;
+  worstCluster: { color: Srgb8; weight: number } | null;
+}
+
+export interface RecOption {
+  fix: Fix;
+  estimatedFailure: EstimatedFailure;
+  guaranteed: boolean;
+  withinBar: boolean;
+}
+
+const srgb8 = (r: number, g: number, b: number): Srgb8 => ({ r, g, b });
+const sameColor = (a: Srgb8, b: Srgb8) => a.r === b.r && a.g === b.g && a.b === b.b;
+
+// ---------------------------------------------------------------------------
+// WCAG 2.2 contrast model.
+// ---------------------------------------------------------------------------
+
+export function isLargeText(fontSize: number, fontWeight: number): boolean {
+  return fontSize >= 24.0 || (fontWeight >= 700.0 && fontSize >= 18.66);
+}
+
+// WCAG relative luminance — culori. Culori linearizes at sRGB's 0.04045
+// breakpoint where WCAG's formula says 0.03928; no u8/255 channel value falls
+// between them, so 8-bit verdicts are identical either way.
+export function relativeLuminance(c: Srgb8): number {
+  return wcagLuminance(toCuloriRgb(c));
+}
+
+export function ratioFromLuminance(la: number, lb: number): number {
+  const hi = la >= lb ? la : lb;
+  const lo = la >= lb ? lb : la;
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export function contrastRatio(a: Srgb8, b: Srgb8): number {
+  return ratioFromLuminance(relativeLuminance(a), relativeLuminance(b));
+}
+
+export function threshold(level: Level, fontSize: number, fontWeight: number): number {
+  const large = isLargeText(fontSize, fontWeight);
+  if (level === "AA") return large ? 3.0 : 4.5;
+  return large ? 4.5 : 7.0;
+}
+
+export function compositeLuminance(lFg: number, a: number, lBg: number): number {
+  if (a >= 1.0) return lFg;
+  const ac = Math.min(Math.max(a, 0.0), 1.0);
+  return ac * lFg + (1.0 - ac) * lBg;
+}
+
+// ---------------------------------------------------------------------------
+// sRGB <-> Oklab <-> Oklch conversions — culori. Converters return UNCLAMPED
+// channels (out-of-gamut values survive), which the eval_oklch gamut test
+// relies on; clamping/quantization stays explicit at the call sites.
+// ---------------------------------------------------------------------------
+
+const toCuloriRgb = (c: Srgb8) => ({ mode: 'rgb' as const, r: c.r / 255.0, g: c.g / 255.0, b: c.b / 255.0 });
+
+// Srgb8 -> (L, C, H degrees). Achromatic colors have no hue (culori leaves it
+// undefined); 0 is used — every consumer multiplies it into a zero chroma.
+export function toOklch(c: Srgb8): [number, number, number] {
+  const o = oklch(toCuloriRgb(c));
+  return [o.l, o.c, o.h ?? 0.0];
+}
+
+// ---------------------------------------------------------------------------
+// Feasibility, realization, candidates, selection.
+// ---------------------------------------------------------------------------
+
+export interface FeasibleSet { dark: number | null; light: number | null }
+export const feasibleSetIsEmpty = (fs: FeasibleSet) => fs.dark === null && fs.light === null;
+
+export function targetLuminanceDarker(lBg: number, r: number, a: number): number {
+  const comp = (lBg + 0.05) / r - 0.05;
+  return (comp - (1.0 - a) * lBg) / a;
+}
+
+export function targetLuminanceLighter(lBg: number, r: number, a: number): number {
+  const comp = r * (lBg + 0.05) - 0.05;
+  return (comp - (1.0 - a) * lBg) / a;
+}
+
+export function feasibleSetAlpha(bgLums: number[], r: number, a: number): FeasibleSet {
+  let darkMax = Infinity;
+  let lightMin = -Infinity;
+  for (const lBg of bgLums) {
+    darkMax = Math.min(darkMax, targetLuminanceDarker(lBg, r, a));
+    lightMin = Math.max(lightMin, targetLuminanceLighter(lBg, r, a));
+  }
+  return {
+    dark: darkMax >= 0.0 ? Math.min(darkMax, 1.0) : null,
+    light: lightMin <= 1.0 ? Math.max(lightMin, 0.0) : null,
+  };
+}
+
+export function feasibleSet(bgLums: number[], r: number): FeasibleSet {
+  return feasibleSetAlpha(bgLums, r, 1.0);
+}
+
+export type Side = "dark" | "light";
+
+// Oklch -> (clamped WCAG luminance, in_gamut, u8 color). The gamut test runs on
+// CLAMPED channels (vacuously true); the real out-of-gamut signal is
+// realizeAtLuminance's |lum - target| > 1e-3 check — clamped luminance tops out
+// below an unreachable target.
+function evalOklch(l: number, chroma: number, hue: number): [number, boolean, Srgb8] {
+  const u = rgb({ mode: 'oklch', l, c: Math.max(chroma, 0.0), h: hue });
+  const clamp01 = (v: number) => Math.min(Math.max(v, 0.0), 1.0);
+  const red = clamp01(u.r);
+  const green = clamp01(u.g);
+  const blue = clamp01(u.b);
+  const eps = 1e-4;
+  const hiBound = 1.0 + eps;
+  const inGamut = [red, green, blue].every((v) => v >= -eps && v <= hiBound);
+  const toU8 = (v: number) => Math.round(Math.min(Math.max(v, 0.0), 1.0) * 255.0);
+  const c8 = srgb8(toU8(red), toU8(green), toU8(blue));
+  const lum = wcagLuminance({ mode: 'rgb', r: red, g: green, b: blue });
+  return [lum, inGamut, c8];
+}
+
+// Binary search on Oklch lightness (WCAG luminance is monotonic in it); null
+// when out of gamut.
+function realizeAtLuminance(target: number, hue: number, chroma: number): Srgb8 | null {
+  let lo = 0.0;
+  let hi = 1.0;
+  for (let i = 0; i < 60; i++) {
+    const mid = 0.5 * (lo + hi);
+    const [lum] = evalOklch(mid, chroma, hue);
+    if (lum < target) lo = mid;
+    else hi = mid;
+  }
+  const l = 0.5 * (lo + hi);
+  const [lum, inGamut, c8] = evalOklch(l, chroma, hue);
+  if (!inGamut || Math.abs(lum - target) > 1e-3) return null;
+  return c8;
+}
+
+// Nudge into the feasible interior until the composited ratio clears `r`
+// against every cluster.
+function realizePassingAlpha(
+  target: number, hue: number, chroma: number, side: Side,
+  bgLums: number[], r: number, a: number,
+): Srgb8 | null {
+  let t = target;
+  for (let i = 0; i < 32; i++) {
+    const c = realizeAtLuminance(t, hue, chroma);
+    if (c === null) return null;
+    const lc = relativeLuminance(c);
+    if (bgLums.every((lb) => ratioFromLuminance(compositeLuminance(lc, a, lb), lb) >= r)) {
+      return c;
+    }
+    t += side === "dark" ? -0.003 : 0.003;
+    if (!(t >= 0.0 && t <= 1.0)) break;
+  }
+  return null;
+}
+
+export function nearestBoundary(fs: FeasibleSet, lFg: number): [Side, number] | null {
+  const dark: [Side, number, number] | null = fs.dark !== null ? ["dark", fs.dark, lFg - fs.dark] : null;
+  const light: [Side, number, number] | null = fs.light !== null ? ["light", fs.light, fs.light - lFg] : null;
+  if (dark && light) return dark[2] <= light[2] ? [dark[0], dark[1]] : [light[0], light[1]];
+  if (dark) return [dark[0], dark[1]];
+  if (light) return [light[0], light[1]];
+  return null;
+}
+
+const anchor = (side: Side): Srgb8 => (side === "dark" ? srgb8(0, 0, 0) : srgb8(255, 255, 255));
+
+// Argmax over {black, white} of the composited ratio, restricted to extremes
+// clearing `r`; tie-break BLACK.
+export function solveHaloAlpha(fg: Srgb8, r: number, a: number): Srgb8 | null {
+  const black = srgb8(0, 0, 0);
+  const white = srgb8(255, 255, 255);
+  const lFg = relativeLuminance(fg);
+  const ratioOver = (halo: Srgb8) => {
+    const lHalo = relativeLuminance(halo);
+    return ratioFromLuminance(compositeLuminance(lFg, a, lHalo), lHalo);
+  };
+  const rb = ratioOver(black);
+  const rw = ratioOver(white);
+  if (rb >= r && rw >= r) return rb >= rw ? black : white;
+  if (rb >= r) return black;
+  if (rw >= r) return white;
+  return null;
+}
+
+// Anchor by Oklab lightness: light fgs keep white, dark fgs keep black.
+export function betterAnchor(fg: Srgb8): Srgb8 {
+  const [lOk] = toOklch(fg);
+  return lOk >= 0.5 ? srgb8(255, 255, 255) : srgb8(0, 0, 0);
+}
+
+// Halo for the unchanged fg, else recolor-to-anchor + backing; null iff
+// opacity-limited (no adjacent fix reaches `r` at coverage `a`).
+export function guaranteedFix(fg: Srgb8, r: number, a: number): Fix | null {
+  const halo = solveHaloAlpha(fg, r, a);
+  if (halo !== null) return { kind: "halo", color: halo };
+  const anchorC = betterAnchor(fg);
+  const backing = solveHaloAlpha(anchorC, r, a);
+  if (backing !== null) return { kind: "recolor_with_backing", color: anchorC, backing };
+  return null;
+}
+
+// Minimal hue-preserving color on the feasible side nearest l_fg, anchor
+// fallback.
+function realizeMinFeasible(
+  fg: Srgb8, bgLums: number[], fs: FeasibleSet, r: number, a: number,
+): [Srgb8, Strategy] {
+  const lFg = relativeLuminance(fg);
+  const nb = nearestBoundary(fs, lFg);
+  if (nb === null) throw new Error("non-empty feasible set has a boundary");
+  const [side, target] = nb;
+  const [, chroma, hue] = toOklch(fg);
+  const c = realizePassingAlpha(target, hue, chroma, side, bgLums, r, a);
+  return c !== null ? [c, "hue_preserving"] : [anchor(side), "anchor"];
+}
+
+// Plain numeric order (values are finite, non-negative; -0.0 is normalized
+// upstream).
+const cmp = (a: number, b: number) => (a < b ? -1 : a > b ? 1 : 0);
+const cmpRgb = (a: Srgb8, b: Srgb8) => cmp(a.r, b.r) || cmp(a.g, b.g) || cmp(a.b, b.b);
+
+interface FailurePartition { mass: number; worstRatio: number; worstIdx: number | null }
+
+// THE one place a cluster's composited ratio and its pass/fail are computed;
+// per-frame scoring lives in verdicts.ts.
+function partitionFailures(text: Srgb8, clusters: RecCluster[], r: number, a: number): FailurePartition {
+  const lText = relativeLuminance(text);
+  let mass = 0.0;
+  let worstRatio = Infinity;
+  let worstIdx: number | null = null;
+  for (let i = 0; i < clusters.length; i++) {
+    const lBg = relativeLuminance(clusters[i].color);
+    const ratio = ratioFromLuminance(compositeLuminance(lText, a, lBg), lBg);
+    if (ratio < worstRatio) {
+      worstRatio = ratio;
+      worstIdx = i;
+    }
+    if (ratio < r) mass += clusters[i].weight;
+  }
+  if (clusters.length === 0) worstRatio = 0.0;
+  return { mass, worstRatio, worstIdx };
+}
+
+export function failureMassAlpha(
+  text: Srgb8, clusters: RecCluster[], r: number, a: number,
+): [number, number, number | null] {
+  const p = partitionFailures(text, clusters, r, a);
+  return [p.mass, p.worstRatio, p.worstIdx];
+}
+
+// The `+ 0.0` normalizes -0.0.
+export function massBelowRatio(text: Srgb8, clusters: RecCluster[], floorRatio: number, a: number): number {
+  const lText = relativeLuminance(text);
+  let sum = 0.0;
+  for (const cl of clusters) {
+    const lBg = relativeLuminance(cl.color);
+    const ratio = ratioFromLuminance(compositeLuminance(lText, a, lBg), lBg);
+    if (ratio < floorRatio) sum += cl.weight;
+  }
+  return sum + 0.0;
+}
+
+function estimateAlpha(
+  text: Srgb8, clusters: RecCluster[], r: number, a: number, floorRatio: number,
+): EstimatedFailure {
+  const p = partitionFailures(text, clusters, r, a);
+  const worstCluster =
+    p.mass > 0.0 && p.worstIdx !== null
+      ? { color: clusters[p.worstIdx].color, weight: clusters[p.worstIdx].weight }
+      : null;
+  return {
+    mass: p.mass,
+    worstRatio: p.worstRatio,
+    massBelowFloor: massBelowRatio(text, clusters, floorRatio, a),
+    worstCluster,
+  };
+}
+
+// The color minimizing weighted COMPOSITED failure mass; exact over the
+// cluster representation.
+// Tie-break: mass asc, worst_ratio desc, luminance asc (darker), rgb order.
+export function bestEffortColorAlpha(
+  fg: Srgb8, clusters: RecCluster[], r: number, a: number,
+): [Srgb8, Strategy] {
+  const [, chroma, hue] = toOklch(fg);
+  const cands: [Srgb8, Strategy][] = [
+    [srgb8(0, 0, 0), "anchor"],
+    [srgb8(255, 255, 255), "anchor"],
+  ];
+  const pushBoundary = (target: number, side: Side, l: number) => {
+    if (!(target >= 0.0 && target <= 1.0)) return;
+    const c = realizePassingAlpha(target, hue, chroma, side, [l], r, a);
+    if (c !== null) {
+      cands.push([c, "hue_preserving"]);
+    } else {
+      const c0 = realizePassingAlpha(target, 0.0, 0.0, side, [l], r, a);
+      if (c0 !== null) cands.push([c0, "anchor"]);
+    }
+  };
+  for (const cl of clusters) {
+    const l = relativeLuminance(cl.color);
+    pushBoundary(targetLuminanceDarker(l, r, a), "dark", l);
+    pushBoundary(targetLuminanceLighter(l, r, a), "light", l);
+  }
+  const scored = cands.map(([c, s]) => {
+    const [mass, worstRatio] = failureMassAlpha(c, clusters, r, a);
+    return { c, s, mass, worstRatio, lum: relativeLuminance(c) };
+  });
+  scored.sort(
+    (x, y) =>
+      cmp(x.mass, y.mass) || cmp(y.worstRatio, x.worstRatio) || cmp(x.lum, y.lum) || cmpRgb(x.c, y.c),
+  );
+  return [scored[0].c, scored[0].s];
+}
+
+function bestColorWith(
+  fg: Srgb8, clusters: RecCluster[], r: number, a: number, bgLums: number[], fs: FeasibleSet,
+): [Srgb8, Strategy] {
+  return feasibleSetIsEmpty(fs)
+    ? bestEffortColorAlpha(fg, clusters, r, a)
+    : realizeMinFeasible(fg, bgLums, fs, r, a);
+}
+
+// Oklch (dL, dC) distance at the fg's fixed hue (the hue term is zero by
+// construction).
+function oklchChange(l0: number, c0: number, cand: Srgb8): number {
+  const [l1, c1] = toOklch(cand);
+  return Math.sqrt(Math.pow(l1 - l0, 2) + Math.pow(c1 - c0, 2));
+}
+
+// Fg hue FIXED; each cluster's closed-form darker/lighter boundary realized at
+// the progressive desaturation ladder C0, 0.75*C0, 0.5*C0, 0.25*C0, 0. The
+// original fg is seeded as a zero-change candidate; achromatic fgs label all
+// candidates anchor.
+export function huePreservingCandidates(
+  fg: Srgb8, clusters: RecCluster[], r: number, a: number,
+): [Srgb8, Strategy][] {
+  const [, c0, hue] = toOklch(fg);
+  const cands: [Srgb8, Strategy][] = [];
+  const achromatic = c0 < 1e-4;
+  const label = (chromaBearing: boolean): Strategy =>
+    chromaBearing && !achromatic ? "hue_preserving" : "anchor";
+  cands.push([fg, label(true)]);
+  for (const frac of [1.0, 0.75, 0.5, 0.25, 0.0]) {
+    const chroma = c0 * frac;
+    const strat = label(frac > 0.0);
+    for (const cl of clusters) {
+      const l = relativeLuminance(cl.color);
+      const targets: [number, Side][] = [
+        [targetLuminanceDarker(l, r, a), "dark"],
+        [targetLuminanceLighter(l, r, a), "light"],
+      ];
+      for (const [target, side] of targets) {
+        if (!(target >= 0.0 && target <= 1.0)) continue;
+        const c = realizePassingAlpha(target, hue, chroma, side, [l], r, a);
+        if (c !== null) cands.push([c, strat]);
+      }
+    }
+  }
+  return cands;
+}
+
+export const FLOOR_MASS_FRACTION = 0.1;
+
+// THE single acceptability predicate:
+// mass <= bar AND mass_below_floor <= bar * FLOOR_MASS_FRACTION.
+export function optionWithinBar(mass: number, massBelowFloor: number, bar: number): boolean {
+  return mass <= bar && massBelowFloor <= bar * FLOOR_MASS_FRACTION;
+}
+
+// Smallest perceptual change among acceptable candidates; deterministic total
+// order.
+function bestHuePreservingWithinBar(
+  fg: Srgb8, clusters: RecCluster[], r: number, a: number, bar: number, floorRatio: number,
+): [Srgb8, Strategy] | null {
+  const [l0, c0] = toOklch(fg);
+  const acceptable = huePreservingCandidates(fg, clusters, r, a)
+    .map(([c, strat]) => {
+      const [mass, worstRatio] = failureMassAlpha(c, clusters, r, a);
+      const mbf = massBelowRatio(c, clusters, floorRatio, a);
+      return { c, strat, change: oklchChange(l0, c0, c), mass, worstRatio, ok: optionWithinBar(mass, mbf, bar) };
+    })
+    .filter((x) => x.ok);
+  if (acceptable.length === 0) return null;
+  acceptable.sort(
+    (x, y) =>
+      cmp(x.change, y.change) || cmp(x.mass, y.mass) || cmp(y.worstRatio, x.worstRatio) || cmpRgb(x.c, y.c),
+  );
+  return [acceptable[0].c, acceptable[0].strat];
+}
+
+interface ColorChoice { lead: [Srgb8, Strategy]; alternative: [Srgb8, Strategy] | null }
+
+// Subtle hue-preserved lead within the bar on the best-effort path
+// (mass-argmin demoted to labelled alternative); unchanged minimal
+// hue-preserving lead when the feasible set is non-empty.
+export function bestChoice(
+  fg: Srgb8, clusters: RecCluster[], r: number, a: number, bar: number, floor: number,
+): ColorChoice {
+  const bgLums = clusters.map((c) => relativeLuminance(c.color));
+  const fs = feasibleSetAlpha(bgLums, r, a);
+  const defaultLead = bestColorWith(fg, clusters, r, a, bgLums, fs);
+  if (feasibleSetIsEmpty(fs)) {
+    const subtle = bestHuePreservingWithinBar(fg, clusters, r, a, bar, floor);
+    if (subtle !== null) {
+      const alternative = !sameColor(subtle[0], defaultLead[0]) ? defaultLead : null;
+      return { lead: subtle, alternative };
+    }
+  }
+  return { lead: defaultLead, alternative: null };
+}
+
+// RECOLOR options only: the lead color option, then its labelled mass-argmin
+// alternative when present.
+export function buildRecolorOptionsAlpha(
+  fg: Srgb8, a: number, clusters: RecCluster[], r: number, bar: number, floor: number,
+): RecOption[] {
+  const choice = bestChoice(fg, clusters, r, a, bar, floor);
+  const mk = (color: Srgb8, strategy: Strategy): RecOption => {
+    const estimatedFailure = estimateAlpha(color, clusters, r, a, floor);
+    return {
+      fix: { kind: "recolor", color, strategy },
+      estimatedFailure,
+      guaranteed: false,
+      withinBar: optionWithinBar(estimatedFailure.mass, estimatedFailure.massBelowFloor, bar),
+    };
+  };
+  const opts = [mk(choice.lead[0], choice.lead[1])];
+  if (choice.alternative !== null) opts.push(mk(choice.alternative[0], choice.alternative[1]));
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Effective threshold.
+// ---------------------------------------------------------------------------
+
+export function effectiveThreshold(
+  level: Level, fontSize: number, fontWeight: number, minRatio: number | null,
+): number {
+  const t = threshold(level, fontSize, fontWeight);
+  return minRatio !== null ? Math.max(t, minRatio) : t;
+}
+
+// ---------------------------------------------------------------------------
+// Class roll-up: tiers, recolor options, exceptions.
+// ---------------------------------------------------------------------------
+
+export interface RunPolicyInput {
+  id: string;
+  className: string | null;
+  fg: Srgb8;
+  fgAlpha: number;
+  requiredRatio: number;
+  bgLums: number[];
+  clusters: RecCluster[];
+  totalSamples: number;
+  indeterminate: boolean;
+  passes: boolean;
+}
+
+export interface PolicyException {
+  id: string;
+  recolorOptions: RecOption[];
+  feasibleEmpty: boolean;
+  indeterminate: boolean;
+}
+
+export interface ClassPolicyResult {
+  classKey: string;
+  tier: number;
+  recolorOptions: RecOption[];
+  exceptions: PolicyException[];
+}
+
+// Member cluster weights rescaled by sample share
+function pool(members: RunPolicyInput[]): RecCluster[] {
+  const samples = members.reduce((s, m) => s + m.totalSamples, 0);
+  const n = Math.max(members.length, 1);
+  const clusters: RecCluster[] = [];
+  for (const m of members) {
+    const share = samples > 0 ? m.totalSamples / samples : 1.0 / n;
+    for (const c of m.clusters) clusters.push({ color: c.color, weight: c.weight * share });
+  }
+  return clusters;
+}
+
+// The recolor lead is options[0].
+const colorMass = (options: RecOption[]) =>
+  options.length > 0 ? options[0].estimatedFailure.mass : Infinity;
+const colorMassBelow = (options: RecOption[]) =>
+  options.length > 0 ? options[0].estimatedFailure.massBelowFloor : Infinity;
+
+// Halo/backing options are not assembled here — tiers and exceptions do not
+// depend on them; dispositions surface them via guaranteedFix.
+function rollupClass(
+  classKey: string, members: RunPolicyInput[], bar: number, floor: number,
+): ClassPolicyResult {
+  const determinate = members.filter((m) => !m.indeterminate);
+  const indeterminate = members.filter((m) => m.indeterminate);
+
+  if (indeterminate.length === 0 && determinate.every((m) => m.passes)) {
+    return { classKey, tier: 0, recolorOptions: [], exceptions: [] };
+  }
+
+  const detFailing = determinate.some((m) => !m.passes);
+  const maxR = determinate.reduce((r, m) => Math.max(r, m.requiredRatio), 0.0);
+
+  const options =
+    determinate.length === 0 || !detFailing
+      ? []
+      : buildRecolorOptionsAlpha(
+          determinate[0].fg, determinate[0].fgAlpha, pool(determinate), maxR, bar, floor,
+        );
+  const classMass = colorMass(options);
+  const classWithinBar = optionWithinBar(classMass, colorMassBelow(options), bar);
+
+  const exceptions: PolicyException[] = [];
+  if (determinate.length >= 2 && options.length > 0) {
+    const cc = options[0].fix.color;
+    for (const m of determinate) {
+      const [mmass] = failureMassAlpha(cc, m.clusters, m.requiredRatio, m.fgAlpha);
+      const mBelow = massBelowRatio(cc, m.clusters, floor, m.fgAlpha);
+      if (!optionWithinBar(mmass, mBelow, bar)) {
+        exceptions.push({
+          id: m.id,
+          recolorOptions: buildRecolorOptionsAlpha(
+            m.fg, m.fgAlpha, m.clusters, m.requiredRatio, bar, floor,
+          ),
+          feasibleEmpty: feasibleSetIsEmpty(feasibleSetAlpha(m.bgLums, m.requiredRatio, m.fgAlpha)),
+          indeterminate: false,
+        });
+      }
+    }
+  }
+  for (const m of indeterminate) {
+    exceptions.push({ id: m.id, recolorOptions: [], feasibleEmpty: false, indeterminate: true });
+  }
+  exceptions.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const tier = indeterminate.length > 0 || !classWithinBar ? 3 : classMass === 0.0 ? 1 : 2;
+  return { classKey, tier, recolorOptions: options, exceptions };
+}
+
+// Classes keyed `.name`, class-less ids `#id`;
+// deterministic key order; members sorted by id.
+export function rollUpPolicy(
+  runs: RunPolicyInput[], bar: number, floor: number,
+): ClassPolicyResult[] {
+  const groups = new Map<string, RunPolicyInput[]>();
+  for (const r of runs) {
+    const key = r.className !== null ? `.${r.className}` : `#${r.id}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(r);
+  }
+  const keys = [...groups.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return keys.map((key) => {
+    const members = [...groups.get(key)!].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return rollupClass(key, members, bar, floor);
+  });
+}
diff --git a/pipeline/scripts/wcag/recommend-viz.ts b/pipeline/scripts/wcag/recommend-viz.ts
new file mode 100644
index 0000000..39bba38
--- /dev/null
+++ b/pipeline/scripts/wcag/recommend-viz.ts
@@ -0,0 +1,721 @@
+// WCAG recommendation STUDIO — visualization. Pure, deterministic HTML string
+// builders (no DOM, no clock, no randomness). `renderPage` frames an AGGREGATE
+// document: the run's rendered video, then two level sections (AA then AAA), each
+// a handful of option rows over per-GROUP Gaussian-splat background strips, plus a
+// per-element appendix table.
+//
+// Each strip is a soft-splat reconstruction of the group's pooled cluster
+// mixture: one radial-gradient ellipse per cluster, radii ∝ the covariance's
+// principal/secondary sigmas and opacity ∝ cluster weight, layered over the
+// weighted-mean fill — so the corpus's real spread (light wall down to dark
+// moments) reads as overlapping blobs, not one flat gray. Clusters live in COLOUR
+// space, so splat PLACEMENT is a synthetic deterministic layout, not spatial
+// truth (see splatSvg). Eigen math is local; colour math is composed from policy.ts.
+
+import { relativeLuminance, type Srgb8 } from "./policy.ts";
+import { DEFAULT_SHADOW_RECIPE } from "./wcag-choice.ts";
+import type {
+  AggregateDoc,
+  AppendixEntry,
+  GroupBlock,
+  LevelSection,
+  OptionRow,
+  PooledClusterStat,
+  VideoRef,
+} from "./recommend.ts";
+
+// ---------------------------------------------------------------------------
+// Covariance geometry (also exercised directly by the tests).
+// ---------------------------------------------------------------------------
+
+const matVec = (m: number[][], v: number[]): number[] => [
+  m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+  m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+  m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+];
+const norm3 = (v: number[]): number => Math.hypot(v[0], v[1], v[2]);
+
+// Dominant eigenvector/eigenvalue of a symmetric 3x3 (covariance) via power
+// iteration: 20 fixed iterations from the deterministic start [1,1,1]/√3;
+// eigenvalue via the Rayleigh quotient. PSD input => non-negative eigenvalue,
+// sign-stable direction.
+export function dominantEigen(cov: number[][]): { vec: number[]; value: number } {
+  let v = [1, 1, 1];
+  const n0 = norm3(v);
+  v = v.map((x) => x / n0);
+  for (let i = 0; i < 20; i++) {
+    const w = matVec(cov, v);
+    const wn = norm3(w);
+    if (wn === 0) break; // all-zero covariance (single-member cluster)
+    v = w.map((x) => x / wn);
+  }
+  const cv = matVec(cov, v);
+  const value = v[0] * cv[0] + v[1] * cv[1] + v[2] * cv[2];
+  return { vec: v, value };
+}
+
+// Principal + secondary axis sigmas of a covariance, and the principal axis's
+// rotation in the OKLAB (a,b) chroma plane. Second axis via deflation: remove the
+// dominant component (C - λ1·v1·v1ᵀ), then power-iterate again.
+export function eigenAxes(cov: number[][]): { s1: number; s2: number; angleDeg: number } {
+  const { vec: v1, value: l1 } = dominantEigen(cov);
+  const deflated = cov.map((row, i) => row.map((x, j) => x - l1 * v1[i] * v1[j]));
+  const { value: l2 } = dominantEigen(deflated);
+  return {
+    s1: Math.sqrt(Math.max(l1, 0)),
+    s2: Math.sqrt(Math.max(l2, 0)),
+    angleDeg: (Math.atan2(v1[2], v1[1]) * 180) / Math.PI, // (a,b) chroma projection
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTML helpers.
+// ---------------------------------------------------------------------------
+
+const hex2 = (v: number) => v.toString(16).padStart(2, "0");
+const toHex = (c: Srgb8) => `#${hex2(c.r)}${hex2(c.g)}${hex2(c.b)}`;
+const esc = (s: string) =>
+  s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]!));
+const ratioStr = (x: number) => `${x.toFixed(2)}:1`;
+
+// Deterministic FNV-1a string hash — seeds the synthetic splat y-jitter.
+function hashStr(s: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+const SPLAT_W = 400;
+const SPLAT_H = 60;
+const N_STRIP = 48; // target total splats per strip; per-cluster count ∝ weight
+const DOT_BASE_R = 5; // small splat radius floor
+const DOT_SIGMA_R = 12; // px of splat radius per unit OKLAB principal sigma
+const SCATTER_PX = 180; // px of positional scatter per unit OKLAB sigma (covariance -> spread)
+const DOT_OPACITY = 0.55; // near-constant: weight is encoded as COUNT, not opacity
+// R2 low-discrepancy sequence (Roberts' plastic constant) — thematically the same
+// blue-noise point picker family the sampler uses.
+const R2_G = 1.324717957244746;
+const R2_A1 = 1 / R2_G;
+const R2_A2 = 1 / (R2_G * R2_G);
+const frac = (x: number) => x - Math.floor(x);
+
+// A group's pooled cluster mixture as MANY small splats — blue-noise-scattered,
+// count ∝ weight (mass = number of dots, not opacity). IMPORTANT: clusters live
+// in COLOUR space, not screen space — so placement is a SYNTHETIC deterministic
+// layout, NOT spatial truth: each cluster has a synthetic centre (x by WCAG
+// luminance, y hash-jittered from key+index), and its N_i = round(weight·N_STRIP)
+// splats scatter around it via the R2 low-discrepancy sequence (seeded per
+// key+cluster), offset scaled by the covariance eigen-axes sigmas (principal +
+// secondary, rotated) — so covariance shows as positional SPREAD. Each splat is a
+// small radial gradient (opaque mean centre -> transparent edge) at constant
+// opacity; heaviest cluster's splats draw last. Gradient defs are shared PER
+// CLUSTER (not per splat) to keep the page small. Upstream pooling caps clusters
+// at bandCap(); a truncated tail is not shown. `key` must be unique per strip.
+export function splatSvg(bands: PooledClusterStat[], key: string): string {
+  if (bands.length === 0) {
+    return `<div class="splat splat--empty" aria-hidden="true"></div>`;
+  }
+  const wSum = bands.reduce((s, b) => s + b.weight, 0) || 1;
+  const mean = { r: 0, g: 0, b: 0 };
+  for (const b of bands) {
+    mean.r += b.color.r * b.weight;
+    mean.g += b.color.g * b.weight;
+    mean.b += b.color.b * b.weight;
+  }
+  const baseHex = toHex({ r: Math.round(mean.r / wSum), g: Math.round(mean.g / wSum), b: Math.round(mean.b / wSum) });
+  const xFor = (lum: number) => 30 + lum * (SPLAT_W - 60); // luminance 0..1 -> [30, W-30]
+  const yFor = (i: number) => 14 + ((hashStr(`${key}:${i}`) % 1000) / 1000) * (SPLAT_H - 28);
+
+  const defs: string[] = [
+    `<filter id="b-${key}" x="-20%" y="-20%" width="140%" height="140%"><feGaussianBlur stdDeviation="1.6"/></filter>`,
+  ];
+  const dots: string[] = [];
+  // Ascending weight => the heaviest cluster's splats render last (on top).
+  const order = bands.map((_, i) => i).sort((a, c) => bands[a].weight - bands[c].weight || a - c);
+  for (const i of order) {
+    const cl = bands[i];
+    const n = Math.max(1, Math.round((cl.weight / wSum) * N_STRIP));
+    const { s1, s2, angleDeg } = eigenAxes(cl.covariance);
+    const theta = (angleDeg * Math.PI) / 180;
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const cx0 = xFor(relativeLuminance(cl.color));
+    const cy0 = yFor(i);
+    const r = (DOT_BASE_R + DOT_SIGMA_R * s1).toFixed(2);
+    const gid = `g-${key}-${i}`;
+    defs.push(
+      `<radialGradient id="${gid}"><stop offset="0%" stop-color="${toHex(cl.color)}" stop-opacity="1"/><stop offset="100%" stop-color="${toHex(cl.color)}" stop-opacity="0"/></radialGradient>`,
+    );
+    const seedX = (hashStr(`${key}:${i}:x`) % 1_000_000) / 1_000_000;
+    const seedY = (hashStr(`${key}:${i}:y`) % 1_000_000) / 1_000_000;
+    for (let j = 0; j < n; j++) {
+      // Blue-noise offset in the cluster's local eigen-frame, scaled by sigma.
+      const lx = (frac(seedX + j * R2_A1) - 0.5) * 2 * SCATTER_PX * s1;
+      const ly = (frac(seedY + j * R2_A2) - 0.5) * 2 * SCATTER_PX * s2;
+      const x = (cx0 + lx * cos - ly * sin).toFixed(2);
+      const y = (cy0 + lx * sin + ly * cos).toFixed(2);
+      dots.push(`<circle cx="${x}" cy="${y}" r="${r}" fill="url(#${gid})" opacity="${DOT_OPACITY}"/>`);
+    }
+  }
+  return `<svg class="splat" viewBox="0 0 ${SPLAT_W} ${SPLAT_H}" preserveAspectRatio="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><defs>${defs.join("")}</defs><rect width="${SPLAT_W}" height="${SPLAT_H}" fill="${baseHex}"/><g filter="url(#b-${key})">${dots.join("")}</g></svg>`;
+}
+
+// Pill vocabulary follows the shipped preview's semantics (style.css .pill):
+// ink-filled = attention (a failing / above-bar verdict), outlined = pass — and
+// the pass pill carries the --lime-text accent, since lime is reserved for
+// positive state exactly as the preview reserves it for the current-position marker.
+type PillKind = "pass" | "attention" | "neutral" | "auto";
+const pill = (kind: PillKind, text: string) => `<span class="pill ${kind}">${esc(text)}</span>`;
+const verdictPill = (pass: boolean, text: string) => pill(pass ? "pass" : "attention", text);
+
+function ratingHtml(row: OptionRow): string {
+  const badges: string[] = [];
+  if (!row.available) {
+    badges.push(pill("attention", "unavailable"));
+    return `<div class="rating">${badges.join("")}</div>`;
+  }
+  if (row.kind === "colour") {
+    // A recolor's verdict is the policy acceptance (within bar), NOT the worst
+    // cluster — a within-bar colour still leaves the low-mass dark moments below
+    // the ratio, so the worst ratio is shown as context, never as the verdict.
+    if (row.withinBar !== undefined) badges.push(verdictPill(row.withinBar, row.withinBar ? "within bar" : "above bar"));
+    if (row.ratio !== undefined) badges.push(pill("neutral", `worst ${ratioStr(row.ratio)}`));
+    if (row.failingMass !== undefined) badges.push(pill("neutral", `mass ${(row.failingMass * 100).toFixed(1)}%`));
+    if (row.autoChoice) badges.push(pill("auto", "auto choice"));
+  } else {
+    // Halo / background are guaranteed: the composited ratio IS the verdict.
+    if (row.ratio !== undefined) badges.push(verdictPill(row.passes, `${ratioStr(row.ratio)} ${row.passes ? "✓" : "✗"}`));
+  }
+  return `<div class="rating">${badges.join("")}</div>`;
+}
+
+function specimenStyle(row: OptionRow): string {
+  let s = `font-size:${row.fontSize}px;font-weight:${row.fontWeight};`;
+  if (row.textHex) s += `color:${row.textHex};`; // omitted on unavailable rows (F8)
+  if (row.kind === "shadow" && row.shadowHex) {
+    s += `text-shadow:${shadowStackCss(row.shadowHex, row.recipe)};`;
+  }
+  if (row.kind === "outline" && row.shadowHex) {
+    s += `-webkit-text-stroke:1.5px ${row.shadowHex};`;
+  }
+  if (row.kind === "background" && row.backingHex) {
+    s += `background:${row.backingHex};padding:2px 12px;border-radius:7px;`;
+  }
+  return s;
+}
+
+// The solved shadow recipe as a CSS text-shadow value: `layers` centered
+// `0 0 {blur}px HEXd9` shadows (matching the applier + the falloff rating).
+function shadowStackCss(hex: string, recipe?: { layers: number; blur: number }): string {
+  const { layers, blur } = recipe ?? DEFAULT_SHADOW_RECIPE;
+  return Array.from({ length: layers }, () => `0 0 ${blur}px ${hex}d9`).join(",");
+}
+
+// Compact id list — the outlier members, or the corpus colour's within-class
+// leftovers. Capped so the row stays short; the appendix has the full table.
+function idListHtml(row: OptionRow): string {
+  const ids = row.exceptionIds;
+  if (!ids || ids.length === 0) return "";
+  const shown = ids.slice(0, 10).map((i) => `<code>${esc(i)}</code>`).join(" ");
+  const more = ids.length > 10 ? ` +${ids.length - 10} more` : "";
+  const lead =
+    row.scope === "outliers"
+      ? `${ids.length} element${ids.length === 1 ? "" : "s"}:`
+      : `leaves ${ids.length} above bar:`;
+  return `<p class="idlist">${lead} ${shown}${esc(more)} <span class="idlist-ref">(appendix)</span></p>`;
+}
+
+// The `data-group`/`data-choice`/`data-word` attributes for an available option —
+// the full choice entry + chat phrase. Shared by the studio rows AND the variants
+// tiles so both carry an identical, contract-valid payload.
+function choiceDataAttrs(row: OptionRow, level: string): string {
+  const hex = (row.kind === "shadow" || row.kind === "outline" ? row.shadowHex : row.textHex)!;
+  const entry: Record<string, unknown> = { level, group: row.scope, kind: row.kind, hex };
+  if (row.kind === "background" && row.backingHex) entry.backingHex = row.backingHex;
+  entry.selector = row.selector;
+  if (row.split) entry.split = row.split; // per-selector split for a heterogeneous group
+  if (row.kind === "shadow" && row.recipe) entry.recipe = { layers: row.recipe.layers, blur: row.recipe.blur };
+  const recipeWord = row.recipe ? ` (${row.recipe.layers}× ${row.recipe.blur}px)` : "";
+  const word = row.splitLabel
+    ? `apply ${level} ${row.scope} ${row.kind}${recipeWord} — ${row.splitLabel}`
+    : `apply ${level} ${row.scope} ${row.kind} ${hex}${recipeWord}` +
+      (row.kind === "background" && row.backingHex ? ` on ${row.backingHex}` : "");
+  return `data-group="${esc(row.scope)}" data-choice="${esc(JSON.stringify(entry))}" data-word="${esc(word)}"`;
+}
+
+// The WHOLE row is the click target for an available option — clicking (or
+// Enter/Space) IS the approval. The row carries the full choice entry + the chat
+// phrase as data-* so the inline script needs no per-row logic; unavailable rows
+// (e.g. AAA with no feasible colour) are NOT interactive and stay muted.
+function rowHtml(row: OptionRow, level: string): string {
+  const chip = `<span class="chip" style="background:${row.kind === "background" && row.backingHex ? row.backingHex : row.textHex}"></span>`;
+  const splatKey = `${level}-${row.scope}-${row.kind}`; // unique per strip (gradient ids)
+
+  let attrs = `class="row row--na"`;
+  let chosenTag = "";
+  if (row.available) {
+    attrs =
+      `class="row row--choose" role="button" tabindex="0"` +
+      ` aria-label="${esc(`Choose ${level} ${row.scope} ${row.kind}`)}"` +
+      ` ${choiceDataAttrs(row, level)}`;
+    chosenTag = `<span class="chosen-tag">✓ chosen</span>`;
+  }
+
+  return `<div ${attrs}>
+  <div class="strip">${splatSvg(row.bands, splatKey)}<span class="specimen" style="${specimenStyle(row)}">${esc(`${row.specimenLabel} · Sample Aa 123`)}</span></div>
+  <div class="rowmeta"><span class="rowlabel">${chip}${esc(row.label)}</span><div class="row-right">${ratingHtml(row)}${chosenTag}</div></div>
+  ${row.splitLabel ? `<p class="splitlabel">${esc(row.splitLabel)}</p>` : ""}
+  ${row.note ? `<p class="rownote">${esc(row.note)}</p>` : ""}
+  ${idListHtml(row)}
+</div>`;
+}
+
+function groupBlockHtml(block: GroupBlock, level: string): string {
+  return `<div class="group-block">
+  <h3 class="group-head">${esc(block.title)}</h3>
+  <div class="level-rows">
+  ${block.rows.map((r) => rowHtml(r, level)).join("\n  ")}
+  </div>
+</div>`;
+}
+
+function levelHtml(section: LevelSection): string {
+  return `<section class="level">
+  <h2 class="level-head">${esc(section.level)} <span class="level-req">needs ${ratioStr(section.corpusRequiredRatio)} · ${section.largeText ? "large" : "normal"} text</span></h2>
+  ${section.groups.map((g) => groupBlockHtml(g, section.level)).join("\n  ")}
+</section>`;
+}
+
+function appendixHtml(entries: AppendixEntry[]): string {
+  const rows = entries
+    .map(
+      (e) =>
+        `<tr><td><code>${esc(e.id)}</code></td><td><code>${esc(e.className)}</code></td><td>${e.group}</td><td class="num">${e.indeterminate ? "—" : ratioStr(e.currentRatio)}</td><td>${verdictCell(e.aa)}</td><td>${verdictCell(e.aaa)}</td></tr>`,
+    )
+    .join("\n");
+  return `<details class="appendix">
+<summary>Per-element detail — ${entries.length} failing element${entries.length === 1 ? "" : "s"}</summary>
+<div class="table-wrap"><table>
+<thead><tr><th>id</th><th>class</th><th>group</th><th class="num">current</th><th>AA</th><th>AAA</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table></div>
+</details>`;
+}
+const verdictCell = (pass: boolean) => (pass ? '<span class="tick ok">pass</span>' : '<span class="tick bad">fail</span>');
+
+// The ORIGINAL (pre-remediation) render, referenced relatively (the page lives in
+// final/ next to it). controls + preload metadata, no autoplay. When the original
+// is unavailable (post-apply, no draft render) an honest inline note stands in.
+function videoBlockHtml(video: VideoRef | null): string {
+  if (!video) return "";
+  if (video.src === null) return `<p class="video-missing">${esc(video.reason)}</p>`;
+  return `<div class="video-card">
+  <video controls preload="metadata" src="${esc(video.src)}"></video>
+  <p class="video-cap">original (before changes)</p>
+</div>`;
+}
+
+// One lean line framing the auto-choice as PROSPECTIVE ("what apply would do"),
+// plus a past measurement only when a remediated report was found.
+function applyLineHtml(doc: AggregateDoc): string {
+  const base = `The <span class="pill auto">auto choice</span> pill marks what applying would pick — nothing here is applied.`;
+  const meas = doc.measured
+    ? ` Past measurement: a prior apply took ${doc.measured.beforeFailing} → ${doc.measured.afterFailing} failing runs.`
+    : "";
+  return `<p class="apply-line">${base}${meas}</p>`;
+}
+
+const STYLE = `
+*{box-sizing:border-box}
+html,body{margin:0}
+body{background:var(--base);color:var(--ink);font-family:var(--sans);font-size:15px;line-height:1.5}
+.strip-top{display:grid;grid-template-columns:1fr auto;align-items:center;gap:14px;padding:0 20px;min-height:56px;background:var(--raised);border-bottom:1px solid var(--border-subtle);position:sticky;top:0;z-index:5}
+.wordmark{font-family:var(--heading);font-weight:500;font-size:12px;letter-spacing:.1em;text-transform:uppercase;color:var(--ink)}
+.wrap{max-width:900px;margin:0 auto;padding:28px 20px 72px}
+.page-title{font-family:var(--heading);font-weight:500;font-size:24px;letter-spacing:-.02em;margin:0 0 4px;color:var(--ink)}
+.lede{color:var(--sub);margin:0 0 24px;font-size:14px;max-width:74ch}
+.summary{display:flex;gap:24px;flex-wrap:wrap;margin:0 0 28px;padding:16px 18px;background:var(--raised);border:1px solid var(--border-subtle);border-radius:14px;box-shadow:var(--shadow)}
+.summary b{font-family:var(--heading);font-weight:500;font-size:22px;display:block;color:var(--ink);font-variant-numeric:tabular-nums}
+.summary code{font-family:var(--sans);font-size:15px}
+.summary span{color:var(--sub);font-size:11px;text-transform:uppercase;letter-spacing:.06em}
+.level{margin:0 0 26px}
+.level-head{font-family:var(--heading);font-weight:500;font-size:19px;letter-spacing:-.01em;margin:0 0 12px;display:flex;align-items:baseline;gap:10px}
+.level-req{font-family:var(--sans);font-weight:400;font-size:12.5px;color:var(--sub);text-transform:none;letter-spacing:0}
+.level-rows{display:flex;flex-direction:column;gap:10px}
+.group-block{margin:0 0 16px}
+.group-head{font-family:var(--sans);font-weight:500;font-size:13px;color:var(--sub);margin:0 0 8px;padding-bottom:6px;border-bottom:1px solid var(--border-subtle);text-transform:uppercase;letter-spacing:.05em}
+.splitlabel{font-size:12px;color:var(--ink);margin:0;padding:0 12px 10px;font-weight:500}
+.row{background:var(--raised);border:1px solid var(--border-subtle);border-radius:12px;overflow:hidden;box-shadow:var(--shadow)}
+.strip{position:relative;height:60px;display:flex;align-items:center;justify-content:center;overflow:hidden}
+.splat{position:absolute;inset:0;width:100%;height:100%;display:block}
+.splat--empty{position:absolute;inset:0;background:repeating-linear-gradient(45deg,var(--sunken) 0 8px,var(--border-subtle) 8px 16px)}
+.specimen{position:relative;z-index:1;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:94%;font-family:sans-serif}
+.video-card{max-width:420px;margin:0 0 26px;background:var(--raised);border:1px solid var(--border-subtle);border-radius:14px;box-shadow:var(--shadow);padding:12px;text-align:center}
+.video-card video{width:100%;height:auto;border-radius:10px;background:#000;display:block}
+.video-cap{margin:8px 0 2px;font-size:11px;color:var(--sub);text-transform:uppercase;letter-spacing:.06em}
+.video-missing{margin:0 0 22px;padding:10px 12px;font-size:12.5px;color:var(--sub);background:var(--sunken);border:1px solid var(--border-subtle);border-radius:10px}
+.apply-line{margin:0 0 24px;font-size:12.5px;color:var(--sub);line-height:1.6}
+.apply-line .pill{font-size:10.5px;padding:1px 8px}
+.rowmeta{display:flex;align-items:center;justify-content:space-between;gap:10px;padding:9px 12px;border-top:1px solid var(--border-subtle);flex-wrap:wrap}
+.rowlabel{font-size:13px;color:var(--ink);font-weight:500;display:flex;align-items:center;gap:8px}
+.chip{width:14px;height:14px;border-radius:4px;border:1px solid var(--border);display:inline-block;flex:none}
+.rating{display:flex;gap:6px;flex-wrap:wrap}
+.pill{font-size:11px;font-variant-numeric:tabular-nums;padding:3px 11px;border-radius:999px;display:inline-flex;align-items:center;gap:6px;font-weight:500;white-space:nowrap;border:1px solid transparent}
+.pill.attention{background:var(--ink);color:var(--base)}
+.pill.pass{background:var(--raised);color:var(--lime-text);border-color:var(--lime-text)}
+.pill.neutral{background:var(--sunken);color:var(--sub);border-color:var(--border-subtle)}
+.pill.auto{background:var(--violet-fill);color:var(--violet);border-color:var(--violet-mid)}
+.row-right{display:flex;align-items:center;gap:10px;flex-wrap:wrap;justify-content:flex-end}
+.row--choose{cursor:pointer;transition:border-color .1s,box-shadow .1s}
+.row--choose:hover{border-color:var(--ink);box-shadow:0 2px 10px rgba(12,10,9,.10)}
+.row--choose:focus-visible{outline:2px solid var(--ink);outline-offset:2px}
+.row.chosen{border-color:var(--ink);box-shadow:0 0 0 1px var(--ink)}
+.row--na{opacity:.72}
+.chosen-tag{display:none;font-size:11px;font-weight:500;padding:3px 11px;border-radius:999px;background:var(--raised);color:var(--lime-text);border:1px solid var(--lime-text);white-space:nowrap}
+.row.chosen .chosen-tag{display:inline-flex;align-items:center}
+.choose-hint{display:block;font-size:12px;color:var(--sub);padding:0 12px 10px;font-variant-numeric:tabular-nums}
+.choose-hint code{background:var(--sunken);padding:1px 6px;border-radius:5px;color:var(--ink)}
+.rownote{font-size:12.5px;color:var(--sub);margin:0;padding:0 12px 10px}
+.idlist{font-size:12px;color:var(--sub);margin:0;padding:0 12px 10px;line-height:1.9}
+.idlist code{background:var(--sunken);padding:1px 6px;border-radius:5px;color:var(--ink)}
+.idlist-ref{color:var(--xsub)}
+.appendix{margin-top:8px;background:var(--raised);border:1px solid var(--border-subtle);border-radius:12px;padding:4px 14px}
+.appendix summary{font-size:13px;font-weight:500;cursor:pointer;padding:10px 0;color:var(--ink)}
+.table-wrap{overflow-x:auto}
+.appendix table{border-collapse:collapse;width:100%;font-size:12.5px;margin:4px 0 12px}
+.appendix th{text-align:left;color:var(--sub);font-weight:500;padding:6px 10px;border-bottom:1px solid var(--border-subtle);position:sticky;top:0;background:var(--raised)}
+.appendix td{padding:6px 10px;border-bottom:1px solid var(--border-subtle)}
+.appendix td.num,.appendix th.num{text-align:right;font-variant-numeric:tabular-nums}
+.appendix code{background:var(--sunken);padding:1px 5px;border-radius:4px;color:var(--ink)}
+.tick.ok{color:var(--lime-text);font-weight:500}
+.tick.bad{color:var(--ink)}
+.foot{margin-top:26px;font-size:12px;color:var(--sub);border-top:1px solid var(--border-subtle);padding-top:14px;line-height:1.6}
+`;
+
+// Inline, CSP-friendly (addEventListener, no eval, no inline handlers) choice
+// script. The WHOLE available row is the target: a click or Enter/Space POSTs to
+// /wcag/choice over http and flips the row to a "chosen" state (unmarking the
+// group's other rows); over file:// it degrades to the exact chat-word fallback
+// shown inline, so activation is never dead. All text goes through textContent —
+// no HTML injection from data-*.
+const CHOICE_SCRIPT = `<script>
+(function(){
+  var served = location.protocol === 'http:' || location.protocol === 'https:';
+  function hint(row, prefix, code){
+    var h = row.querySelector('.choose-hint');
+    if(!h){ h = document.createElement('span'); h.className = 'choose-hint'; row.appendChild(h); }
+    h.textContent = prefix + (code ? ' ' : '');
+    if(code){ var c = document.createElement('code'); c.textContent = code; h.appendChild(c); }
+  }
+  function unmark(group){
+    var all = document.querySelectorAll('[data-choice][data-group="' + group + '"]');
+    for(var i=0;i<all.length;i++){ all[i].classList.remove('chosen'); }
+  }
+  function activate(row){
+    var raw = row.getAttribute('data-choice'), entry = JSON.parse(raw);
+    if(served){
+      fetch('/wcag/choice', { method:'POST', headers:{'content-type':'application/json'}, body: raw })
+        .then(function(r){ if(!r.ok){ return r.text().then(function(t){ throw new Error(t || ('HTTP ' + r.status)); }); }
+          unmark(entry.group); row.classList.add('chosen'); })
+        .catch(function(e){ hint(row, 'could not save: ' + e.message); });
+    } else {
+      hint(row, 'say:', row.getAttribute('data-word'));
+    }
+  }
+  var rows = document.querySelectorAll('[data-choice]');
+  for(var i=0;i<rows.length;i++){
+    rows[i].addEventListener('click', function(ev){ activate(ev.currentTarget); });
+    rows[i].addEventListener('keydown', function(ev){
+      if(ev.key === 'Enter' || ev.key === ' ' || ev.key === 'Spacebar'){ ev.preventDefault(); activate(ev.currentTarget); }
+    });
+  }
+})();
+</script>`;
+
+// VEED light ONLY (coherence with the shipped preview beats dual-theme). The
+// design tokens are inlined from preview/page/tokens.css (the SSOT); this sheet
+// only consumes them via var(). `tokensCss` is verbatim tokens.css content and
+// is part of the studio's deterministic input.
+export function renderPage(doc: AggregateDoc, tokensCss: string): string {
+  const status = doc.passed
+    ? pill("pass", "AA/AAA clean")
+    : pill("attention", `${doc.failingCount} failing`);
+  // Studio adopts Variant A: a tall large-splat Gaussian field per group block +
+  // a compact interactive tile grid (the tiles POST to /wcag/choice).
+  const body = doc.levels
+    .map(
+      (lv) => `<section class="level">
+  <h2 class="level-head">${esc(lv.level)} <span class="level-req">needs ${ratioStr(lv.corpusRequiredRatio)} · ${lv.largeText ? "large" : "normal"} text</span></h2>
+  ${lv.groups.map((g) => variantAGroup(g, lv.level)).join("\n")}
+</section>`,
+    )
+    .join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>WCAG recommendation studio · VEED</title>
+<style>
+/* Design tokens inlined from preview/page/tokens.css (SSOT) at generation time. */
+${tokensCss}
+${STYLE}
+${VARIANTS_STYLE}
+</style>
+</head>
+<body>
+<div class="strip-top">
+  <span class="wordmark">VEED · WCAG Studio</span>
+  ${status}
+</div>
+<div class="wrap">
+<h1 class="page-title">Contrast recommendations</h1>
+<p class="lede">This is a pre-decision view — pick the fix you want here before anything is applied. The failing text is rolled up into a corpus and its outliers, with a few options per group at AA then AAA, rated against the same pooled-cluster policy the gate uses.</p>
+${videoBlockHtml(doc.video)}
+<div class="summary">
+  <div><b>${doc.failingCount}</b><span>failing elements</span></div>
+  <div><b>${doc.corpusMemberCount}</b><span>corpus <code>${esc(doc.corpusClassKey)}</code></span></div>
+  <div><b>${doc.outlierMemberCount}</b><span>outliers</span></div>
+  <div><b>${ratioStr(doc.floor)}</b><span>lead floor</span></div>
+  <div><b>${(doc.bar * 100).toFixed(0)}%</b><span>mass bar</span></div>
+</div>
+${applyLineHtml(doc)}
+${body}
+${appendixHtml(doc.appendix)}
+${CHOICE_SCRIPT}
+<p class="foot">Each group's backdrop is a Gaussian field of large overlapping radial-gradient splats (one per pooled cluster, radius from the covariance) — the true background range, not one flat gray. Click a tile (or Enter/Space) to choose it; over http that POSTs to /wcag/choice, over file:// it shows the exact chat-word. RATINGS differ by treatment: a recolor is rated over the pooled clusters; a soft SHADOW is rated per cluster (the translucent shadow blended over each sampled background); an OUTLINE is background-independent (fg vs the outline colour only); the background plate is the guaranteed anchor. Specimens use the browser's generic sans-serif; page fonts are Inter/SwissNow from the VEED tokens.</p>
+</div>
+</body>
+</html>
+`;
+}
+
+// ===========================================================================
+// DESIGN VARIANTS PAGE (wcag-design-variants.html) — a STATIC design chooser:
+// the SAME data (AA level, corpus + outliers blocks) rendered in three complete
+// treatments A/B/C stacked for the user to pick. Deterministic; tiles carry the
+// clickable choice payload in markup but the page has NO live POST script.
+// Direction: tiles small (2-3 per grid row), Gaussians LARGE and actually visible.
+// ===========================================================================
+
+const FIELD_W = 400;
+const FIELD_H = 150;
+const FIELD_BASE_R = 74; // ~6x the studio dot base — a big, visible blob
+const FIELD_GAIN = 420; // px of radius per unit OKLAB sigma
+const MESH_FLOOR = 130; // px radius floor so every CSS-mesh cluster stays visible
+const MESH_GAIN = 560;
+
+// VARIANT A field: ONE large radial-gradient splat per cluster (not many dots),
+// heavily blurred and overlapping -> a continuous cloud. rx >= FIELD_BASE_R.
+export function gaussianFieldSvg(bands: PooledClusterStat[], key: string): string {
+  if (bands.length === 0) return `<div class="gfield gfield--empty" aria-hidden="true"></div>`;
+  const wMax = bands.reduce((m, b) => Math.max(m, b.weight), 0) || 1;
+  const wSum = bands.reduce((s, b) => s + b.weight, 0) || 1;
+  const mean = { r: 0, g: 0, b: 0 };
+  for (const b of bands) { mean.r += b.color.r * b.weight; mean.g += b.color.g * b.weight; mean.b += b.color.b * b.weight; }
+  const baseHex = toHex({ r: Math.round(mean.r / wSum), g: Math.round(mean.g / wSum), b: Math.round(mean.b / wSum) });
+  const defs = [`<filter id="f-${key}" x="-30%" y="-30%" width="160%" height="160%"><feGaussianBlur stdDeviation="10"/></filter>`];
+  const order = bands.map((_, i) => i).sort((a, c) => bands[a].weight - bands[c].weight || a - c);
+  const ell: string[] = [];
+  for (const i of order) {
+    const cl = bands[i];
+    const { s1, s2, angleDeg } = eigenAxes(cl.covariance);
+    const rx = (FIELD_BASE_R + FIELD_GAIN * s1).toFixed(1);
+    const ry = (FIELD_BASE_R * 0.8 + FIELD_GAIN * s2).toFixed(1);
+    const cx = ((0.1 + relativeLuminance(cl.color) * 0.8) * FIELD_W).toFixed(1);
+    const cy = ((0.15 + ((hashStr(`${key}:${i}`) % 1000) / 1000) * 0.7) * FIELD_H).toFixed(1);
+    const op = (0.32 + 0.4 * (cl.weight / wMax)).toFixed(3);
+    const gid = `fg-${key}-${i}`;
+    defs.push(`<radialGradient id="${gid}"><stop offset="0%" stop-color="${toHex(cl.color)}" stop-opacity="0.95"/><stop offset="100%" stop-color="${toHex(cl.color)}" stop-opacity="0"/></radialGradient>`);
+    ell.push(`<ellipse cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}" transform="rotate(${angleDeg.toFixed(1)} ${cx} ${cy})" fill="url(#${gid})" opacity="${op}"/>`);
+  }
+  return `<svg class="gfield" viewBox="0 0 ${FIELD_W} ${FIELD_H}" preserveAspectRatio="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><defs>${defs.join("")}</defs><rect width="${FIELD_W}" height="${FIELD_H}" fill="${baseHex}"/><g filter="url(#f-${key})">${ell.join("")}</g></svg>`;
+}
+
+// VARIANT B/C mesh: a CSS background stacking one LARGE radial-gradient per
+// cluster (weight -> 8-digit-hex opacity, x by luminance, big sigma-scaled radii
+// with a floor) over the weighted-mean base — a smooth blended mesh, no SVG.
+export function meshGradientStyle(bands: PooledClusterStat[]): string {
+  if (bands.length === 0) return "var(--sunken)";
+  const wMax = bands.reduce((m, b) => Math.max(m, b.weight), 0) || 1;
+  const wSum = bands.reduce((s, b) => s + b.weight, 0) || 1;
+  const mean = { r: 0, g: 0, b: 0 };
+  for (const b of bands) { mean.r += b.color.r * b.weight; mean.g += b.color.g * b.weight; mean.b += b.color.b * b.weight; }
+  const baseHex = toHex({ r: Math.round(mean.r / wSum), g: Math.round(mean.g / wSum), b: Math.round(mean.b / wSum) });
+  const layers = bands.map((cl, i) => {
+    const { s1, s2 } = eigenAxes(cl.covariance);
+    const rx = Math.round(MESH_FLOOR + MESH_GAIN * s1);
+    const ry = Math.round(MESH_FLOOR + MESH_GAIN * s2);
+    const x = (relativeLuminance(cl.color) * 100).toFixed(1);
+    const y = (((hashStr(`${toHex(cl.color)}:${i}`) % 1000) / 1000) * 100).toFixed(1);
+    const a = Math.round((0.4 + 0.5 * (cl.weight / wMax)) * 255).toString(16).padStart(2, "0");
+    return `radial-gradient(ellipse ${rx}px ${ry}px at ${x}% ${y}%, ${toHex(cl.color)}${a} 0%, transparent 70%)`;
+  });
+  return `${layers.join(", ")}, ${baseHex}`;
+}
+
+const kindLabel = (row: OptionRow): string =>
+  row.kind === "colour" ? "Recolor" : row.kind === "shadow" ? "Shadow" : row.kind === "outline" ? "Outline" : "Backing";
+
+// Compact specimen (fixed small size) for a variant tile/card.
+function tileSpecimenStyle(row: OptionRow): string {
+  let s = `font-size:20px;font-weight:600;`;
+  if (row.textHex) s += `color:${row.textHex};`; // omitted on unavailable rows (F8)
+  if (row.kind === "shadow" && row.shadowHex) s += `text-shadow:${shadowStackCss(row.shadowHex, row.recipe)};`;
+  if (row.kind === "outline" && row.shadowHex) s += `-webkit-text-stroke:1.2px ${row.shadowHex};`;
+  if (row.kind === "background" && row.backingHex) s += `background:${row.backingHex};padding:1px 9px;border-radius:5px;`;
+  return s;
+}
+
+// Condensed pills (verdict only) + full details as a title attr — metadata is
+// squeezed per the brief.
+function tilePills(row: OptionRow): string {
+  if (!row.available) return pill("attention", "n/a");
+  if (row.kind === "colour") return row.withinBar !== undefined ? verdictPill(row.withinBar, row.withinBar ? "within bar" : "above bar") : "";
+  return row.ratio !== undefined ? verdictPill(row.passes, ratioStr(row.ratio)) : "";
+}
+function tileDetails(row: OptionRow, level: string): string {
+  const parts = [`${level} ${row.scope} ${row.kind}`];
+  if (row.ratio !== undefined) parts.push(`ratio ${ratioStr(row.ratio)}`);
+  if (row.failingMass !== undefined) parts.push(`mass ${(row.failingMass * 100).toFixed(1)}%`);
+  if (row.withinBar !== undefined) parts.push(row.withinBar ? "within bar" : "above bar");
+  if (row.splitLabel) parts.push(row.splitLabel);
+  if (row.note) parts.push(row.note);
+  return parts.join(" · ");
+}
+function tileAttrs(row: OptionRow, level: string): string {
+  return row.available ? ` role="button" tabindex="0" ${choiceDataAttrs(row, level)}` : "";
+}
+// The shadow tile shows its solved recipe (e.g. "Shadow 2×8px"); others just the kind.
+const tileLabel = (row: OptionRow): string =>
+  row.kind === "shadow" && row.recipe ? `Shadow ${row.recipe.layers}×${row.recipe.blur}px` : kindLabel(row);
+
+// A/B share the compact grid tile (mesh mini-strip behind the specimen). The
+// chosen-tag stays hidden until the (studio-only) choice script marks it .chosen;
+// on the static variants page it never appears.
+function variantTile(row: OptionRow, level: string, tileBg: string): string {
+  return `<div class="vtile${row.available ? "" : " vtile--na"}"${tileAttrs(row, level)} title="${esc(tileDetails(row, level))}">
+    <div class="vstrip" style="background:${tileBg}"><span class="vspec" style="${tileSpecimenStyle(row)}">${esc(kindLabel(row))} Aa</span></div>
+    <div class="vmeta"><span class="vlabel">${esc(tileLabel(row))}</span>${tilePills(row)}${row.autoChoice ? pill("auto", "auto") : ""}<span class="chosen-tag">✓ chosen</span></div>
+  </div>`;
+}
+
+function variantAGroup(block: GroupBlock, level: string): string {
+  const bands = block.rows[0].bands;
+  const mesh = meshGradientStyle(bands);
+  return `<div class="vgroup">
+    <h4 class="vgroup-head">${esc(block.title)}</h4>
+    <div class="gfield-band">${gaussianFieldSvg(bands, `A-${level}-${block.scope}`)}</div>
+    <div class="vtiles">${block.rows.map((r) => variantTile(r, level, mesh)).join("")}</div>
+  </div>`;
+}
+
+function variantBGroup(block: GroupBlock, level: string): string {
+  const bands = block.rows[0].bands;
+  const mesh = meshGradientStyle(bands);
+  return `<div class="vgroup">
+    <h4 class="vgroup-head">${esc(block.title)}</h4>
+    <div class="mesh-band" style="background:${mesh}"></div>
+    <div class="vtiles">${block.rows.map((r) => variantTile(r, level, mesh)).join("")}</div>
+  </div>`;
+}
+
+function variantCGroup(block: GroupBlock, level: string): string {
+  const bands = block.rows[0].bands;
+  const mesh = meshGradientStyle(bands);
+  const cards = block.rows
+    .map(
+      (r) => `<div class="vcard${r.available ? "" : " vtile--na"}"${tileAttrs(r, level)} title="${esc(tileDetails(r, level))}">
+      <span class="vspec" style="${tileSpecimenStyle(r)}">${esc(kindLabel(r))} Aa</span>
+      <span class="vcard-meta">${tilePills(r)}</span>
+    </div>`,
+    )
+    .join("");
+  return `<div class="vgroup">
+    <h4 class="vgroup-head">${esc(block.title)}</h4>
+    <div class="vcards" style="background:${mesh}">${cards}</div>
+  </div>`;
+}
+
+const VARIANTS_STYLE = `
+.variant{margin:0 0 40px;padding:0 0 16px;border-bottom:1px solid var(--border-subtle)}
+.vhead{font-family:var(--heading);font-weight:500;font-size:22px;margin:0 0 4px;display:flex;align-items:center;gap:12px;color:var(--ink)}
+.vbadge{display:inline-flex;align-items:center;justify-content:center;width:34px;height:34px;border-radius:10px;background:var(--ink);color:var(--base);font-size:18px;font-weight:600}
+.vdesc{color:var(--sub);font-size:13.5px;margin:0 0 18px;max-width:76ch}
+.vgroup{margin:0 0 22px}
+.vgroup-head{font-size:12px;font-weight:500;color:var(--sub);text-transform:uppercase;letter-spacing:.05em;margin:0 0 8px}
+.gfield-band{height:150px;border-radius:12px;overflow:hidden;border:1px solid var(--border-subtle);margin:0 0 12px}
+.gfield{display:block;width:100%;height:100%}
+.mesh-band{height:150px;border-radius:12px;border:1px solid var(--border-subtle);margin:0 0 12px}
+.vtiles{display:grid;grid-template-columns:repeat(auto-fill,minmax(210px,1fr));gap:10px}
+.vtile{border:1px solid var(--border-subtle);border-radius:10px;overflow:hidden;background:var(--raised);transition:border-color .1s}
+.vtile[role=button]{cursor:pointer}
+.vtile[role=button]:hover{border-color:var(--ink)}
+.vtile:focus-visible{outline:2px solid var(--ink);outline-offset:2px}
+.vtile.chosen{border-color:var(--ink);box-shadow:0 0 0 1px var(--ink)}
+.vtile.chosen .chosen-tag{display:inline-flex;align-items:center}
+.vtile .choose-hint{padding:0 9px 8px}
+.vtile--na{opacity:.6}
+.vstrip{height:52px;display:flex;align-items:center;justify-content:center;overflow:hidden}
+.vspec{white-space:nowrap;font-family:sans-serif}
+.vmeta{display:flex;align-items:center;gap:6px;padding:7px 9px;border-top:1px solid var(--border-subtle);flex-wrap:wrap}
+.vlabel{font-size:12px;font-weight:500;color:var(--ink)}
+.vcards{display:flex;gap:10px;overflow-x:auto;padding:12px;border-radius:12px;border:1px solid var(--border-subtle)}
+.vcard{flex:0 0 auto;min-width:150px;background:rgba(255,255,255,.82);border:1px solid var(--border-subtle);border-radius:9px;padding:10px 12px;display:flex;flex-direction:column;gap:8px}
+.vcard[role=button]{cursor:pointer}
+.vcard[role=button]:hover{border-color:var(--ink)}
+.vcard:focus-visible{outline:2px solid var(--ink);outline-offset:2px}
+.vcard-meta{display:flex;gap:5px;flex-wrap:wrap}
+.variant .pill{font-size:10px;padding:2px 8px}
+`;
+
+// Assemble the static three-variant chooser (AA level only). No CHOICE_SCRIPT.
+export function renderVariantsPage(doc: AggregateDoc, tokensCss: string): string {
+  const aa = doc.levels[0];
+  const variants: { id: string; title: string; desc: string; render: (b: GroupBlock, l: string) => string }[] = [
+    { id: "A", title: "Compact grid + Gaussian field", desc: "Small tiles in a responsive grid; each group's backdrop is a tall SVG field of large overlapping Gaussian splats — a visible continuous cloud.", render: variantAGroup },
+    { id: "B", title: "CSS mesh-gradient", desc: "No SVG — each group strip is a single element stacking large CSS radial-gradients (one per cluster) into a smooth blended mesh.", render: variantBGroup },
+    { id: "C", title: "Horizontal strip cards", desc: "Each option a small card in one horizontal row per group, over the group's mesh backdrop; most compact vertically.", render: variantCGroup },
+  ];
+  const sections = variants
+    .map(
+      (v) => `<section class="variant" id="variant-${v.id.toLowerCase()}">
+  <h2 class="vhead"><span class="vbadge">${v.id}</span>${esc(v.title)}</h2>
+  <p class="vdesc">${esc(v.desc)}</p>
+  ${aa.groups.map((g) => v.render(g, aa.level)).join("\n")}
+</section>`,
+    )
+    .join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>WCAG design variants · VEED</title>
+<style>
+/* Design tokens inlined from preview/page/tokens.css (SSOT) at generation time. */
+${tokensCss}
+${STYLE}
+${VARIANTS_STYLE}
+</style>
+</head>
+<body>
+<div class="strip-top">
+  <span class="wordmark">VEED · WCAG Studio</span>
+  <span class="pill neutral">design variants</span>
+</div>
+<div class="wrap">
+<h1 class="page-title">Design variants</h1>
+<p class="lede">Three complete treatments of the AA recommendations (corpus + outliers) — pick the one you want. This is a static chooser: tiles carry their choice payload but nothing is applied here.</p>
+${sections}
+<p class="foot">Same data, three designs. A renders each group's background as an SVG field of large overlapping Gaussian splats; B and C stack large CSS radial-gradients (one per cluster, sized from the covariance with a visibility floor, opacity from weight) into a mesh. Tiles are condensed — verdict pills only, full details on hover. Specimens are the browser's generic sans-serif; page fonts are Inter/SwissNow from the VEED tokens.</p>
+</div>
+</body>
+</html>
+`;
+}
diff --git a/pipeline/scripts/wcag/recommend.ts b/pipeline/scripts/wcag/recommend.ts
new file mode 100644
index 0000000..4c43d7d
--- /dev/null
+++ b/pipeline/scripts/wcag/recommend.ts
@@ -0,0 +1,931 @@
+// WCAG recommendation STUDIO — an on-demand, read-only advisor that turns one
+// run's committed contrast statistics into a SHORT, AGGREGATE remediation menu:
+// the failing text is rolled up by class (the corpus + its outliers), and each
+// group gets a handful of options (a hue-preserving recolor, a halo, a backing)
+// at AA and again at AAA — 4-8 option rows total, not one section per element.
+//
+//   node --import tsx pipeline/scripts/wcag/recommend.ts --run runs/<key>
+//
+// It renders NOTHING and samples NOTHING: it reads final/contrast-statistics.json
+// + final/template.wv (re-running the analyzer ONLY to fill a missing
+// statistics file when raw samples are present), and writes
+// final/wcag-recommendations.json + wcag-recommendations.html, both
+// byte-deterministic for a fixed input. The analyzer's compliance report is
+// never read — verdicts come from verdicts.ts, policy from policy.ts.
+//
+// All contrast/feasibility/candidate math is COMPOSED from policy.ts — the
+// class roll-up, colour choice, halo, and backing all come from policy.ts; this
+// file adds the grouping, the per-group background pooling, and presentation,
+// never a second copy of the math.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  betterAnchor,
+  buildRecolorOptionsAlpha,
+  compositeLuminance,
+  effectiveThreshold,
+  isLargeText,
+  optionWithinBar,
+  ratioFromLuminance,
+  relativeLuminance,
+  rollUpPolicy,
+  solveHaloAlpha,
+  threshold,
+  type ClassPolicyResult,
+  type Level,
+  type RecCluster,
+  type RecOption,
+  type RunPolicyInput,
+  type Rgba,
+  type Srgb8,
+  type Strategy,
+} from "./policy.ts";
+import { renderPage, renderVariantsPage } from "./recommend-viz.ts";
+import {
+  parseElementClasses,
+  resolveVerdicts,
+  type ElementStat,
+  type PooledClusterStat,
+  type Statistics,
+  type VerdictResult,
+} from "./verdicts.ts";
+import { DEFAULT_BAR, DEFAULT_MIN_LEAD_RATIO } from "../wcag-pass.ts";
+
+// contrast-statistics.json types live in verdicts.ts (the consumer-contract
+// SSOT); re-exported for the viz layer.
+export type { ClusterStat, ElementStat, FrameStat, PooledClusterStat, Statistics } from "./verdicts.ts";
+
+// ---------------------------------------------------------------------------
+// Aggregate recommendation model (also the JSON output schema, `schema: 2`).
+// ---------------------------------------------------------------------------
+
+export type OptionKind = "colour" | "shadow" | "outline" | "background";
+export type GroupScope = "corpus" | "outliers";
+
+export interface OptionRow {
+  scope: GroupScope;
+  kind: OptionKind;
+  label: string;
+  available: boolean;
+  /** Specimen text colour (the recolor, or the fg for halo/background rows).
+   * Omitted on unavailable rows that have no meaningful colour. */
+  textHex?: string;
+  /** Halo colour, present on `kind: "halo"`. */
+  shadowHex?: string;
+  /** Solid backing colour, present on `kind: "background"`. */
+  backingHex?: string;
+  strategy?: Strategy;
+  /** Estimated ratio (pooled worst cluster, or composited halo/backing ratio). */
+  ratio?: number;
+  requiredRatio: number;
+  passes: boolean;
+  failingMass?: number;
+  massBelowFloor?: number;
+  withinBar?: boolean;
+  autoChoice: boolean;
+  /** Within-class exceptions the corpus colour leaves above bar (compact ids). */
+  exceptionIds?: string[];
+  note?: string;
+  /** The pooled background strip drawn behind this row. */
+  bands: PooledClusterStat[];
+  fontSize: number;
+  fontWeight: number;
+  specimenLabel: string;
+  /** CSS selector(s) this option targets (corpus class key, or the outlier id
+   * list as a comma-joined selector) — carried into the choice entry. */
+  selector: string;
+  /** Heterogeneous groups get a per-selector split (outlier halo/background,
+   * where each element's fg solves to its own halo/anchor colour). */
+  split?: { selector: string; hex: string; backingHex?: string }[];
+  /** Human summary of a split, e.g. "black halo (16) · white halo (2)". */
+  splitLabel?: string;
+  /** The solved shadow recipe (kind "shadow"): layers + blur, modeled coverage. */
+  recipe?: ShadowRecipe;
+}
+
+// One group's block within a level: a titled section (its own pooled-splat strip
+// is shown on each of its rows) holding that group's options together — corpus
+// and outliers never interleave.
+export interface GroupBlock {
+  scope: GroupScope;
+  title: string;
+  rows: OptionRow[];
+}
+
+export interface LevelSection {
+  level: Level;
+  corpusRequiredRatio: number;
+  largeText: boolean;
+  groups: GroupBlock[]; // [corpus] or [corpus, outliers]
+}
+
+export interface AppendixEntry {
+  id: string;
+  className: string;
+  group: GroupScope;
+  currentRatio: number;
+  aa: boolean;
+  aaa: boolean;
+  indeterminate: boolean;
+}
+
+// The ORIGINAL (pre-remediation) render to preview: a relative src, or an
+// explicit omission with a reason (post-apply runs whose out.mp4 is remediated
+// and have no draft render to fall back to). null = no video at all (pre-apply
+// with no render).
+export type VideoRef = { src: string } | { src: null; reason: string };
+
+export interface AggregateDoc {
+  schema: 2;
+  bar: number;
+  floor: number;
+  passed: boolean;
+  corpusClassKey: string;
+  corpusMemberCount: number;
+  outlierMemberCount: number;
+  failingCount: number;
+  levels: LevelSection[]; // [AA, AAA]
+  appendix: AppendixEntry[];
+  video: VideoRef | null;
+  /** Past measurement of a prior apply (before -> after failing counts at AA),
+   * present only when remediated statistics exist. */
+  measured: { beforeFailing: number; afterFailing: number } | null;
+}
+
+// ---------------------------------------------------------------------------
+// Small pure helpers.
+// ---------------------------------------------------------------------------
+
+const hex2 = (v: number) => v.toString(16).padStart(2, "0");
+export const toHex = (c: Srgb8) => `#${hex2(c.r)}${hex2(c.g)}${hex2(c.b)}`;
+const rgb = (c: Rgba | Srgb8): Srgb8 => ({ r: c.r, g: c.g, b: c.b });
+const sameColor = (a: Srgb8, b: Srgb8) => a.r === b.r && a.g === b.g && a.b === b.b;
+const byId = (a: { id: string }, b: { id: string }) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+const MAX_BANDS = 10; // cap the pooled strip to a legible band count
+
+// The maximum number of background bands the studio will paint per group strip.
+export const bandCap = () => MAX_BANDS;
+
+// Composited ratio of a foreground (at coverage `a`) OVER a solid colour — the
+// quantity solve_halo_alpha maximizes, recomputed to surface the achieved value.
+function compositedRatio(fg: Srgb8, a: number, behind: Srgb8): number {
+  const lb = relativeLuminance(behind);
+  return ratioFromLuminance(compositeLuminance(relativeLuminance(fg), a, lb), lb);
+}
+
+// Declared per-layer alpha of the emitted soft shadow (the `d9` in HEXd9).
+export const SHADOW_ALPHA = 0.85;
+// The recipe space the solver searches (centered halos only): layer counts and
+// blur radii (px), minimal-first (fewer layers, then smaller blur).
+const SOLVER_LAYERS = [1, 2, 3, 4];
+const SOLVER_BLURS = [4, 8, 12, 16];
+
+// --- Gaussian FALLOFF model (exact spec; the Rust analyzer mirrors this). ------
+// A&S 7.1.26 error function, EXACT op order for byte-for-byte parity; odd for x<0.
+export function erf(x: number): number {
+  const sign = x < 0 ? -1 : 1;
+  const ax = Math.abs(x);
+  const t = 1 / (1 + 0.3275911 * ax);
+  const y = 1 - (((((1.061405429 * t - 1.453152027) * t) + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-ax * ax);
+  return sign * y;
+}
+// Standard normal CDF.
+export function phi(x: number): number {
+  return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+// Effective coverage of ONE shadow layer at the letter's edge ring: a blurred
+// shadow does NOT paint the edge fully. sigma = blur/2; the ring sits ~1px past
+// the glyph plus the offset magnitude, so d_eff = 1 + |offset|; coverage there is
+// alpha·phi(-d_eff/sigma). A blur-0 layer paints nothing at the ring (C = 0).
+export function layerCoverage(alpha: number, blur: number, dx: number, dy: number): number {
+  if (blur === 0) return 0;
+  const sigma = blur / 2;
+  const dEff = 1 + Math.hypot(dx, dy);
+  return alpha * phi(-dEff / sigma);
+}
+
+// SHADOW rating (background-DEPENDENT). WCAG G18 spec (mirrored into the Rust
+// oracle in parallel): a SOFT text-shadow does NOT replace the background — for
+// EACH sample, blend the shadow over the sample ONCE PER LAYER in emitted order,
+// each layer at ITS OWN coverage `layerCoverages[k]` (from the falloff model),
+// then score the fg (composited at its OWN alpha) over that blended background.
+// Weighted mass below `r`. Moves with the clusters (unlike an outline).
+export function shadowFailure(
+  fg: Rgba,
+  shadow: Srgb8,
+  layerCoverages: number[],
+  clusters: RecCluster[],
+  r: number,
+  floorRatio: number,
+): { mass: number; worstRatio: number; massBelowFloor: number } {
+  const lShadow = relativeLuminance(shadow);
+  const lFgRaw = relativeLuminance(fg);
+  let mass = 0;
+  let massBelowFloor = 0;
+  let worst = Infinity;
+  for (const cl of clusters) {
+    let lBlendedBg = relativeLuminance(cl.color);
+    for (const C of layerCoverages) lBlendedBg = compositeLuminance(lShadow, C, lBlendedBg);
+    const lFg = compositeLuminance(lFgRaw, fg.a, lBlendedBg);
+    const ratio = ratioFromLuminance(lFg, lBlendedBg);
+    if (ratio < worst) worst = ratio;
+    if (ratio < r) mass += cl.weight;
+    if (ratio < floorRatio) massBelowFloor += cl.weight;
+  }
+  if (clusters.length === 0) worst = 0;
+  return { mass, worstRatio: worst, massBelowFloor };
+}
+
+export interface ShadowRecipe {
+  layers: number;
+  blur: number;
+  /** Per-layer coverage C at this blur (falloff model, centered). */
+  coverage: number;
+  /** Compounded effective alpha over the layers: 1-(1-C)^layers. */
+  aEff: number;
+}
+
+// PROPER-SHADOW SOLVER: the minimal centered-halo recipe (fewer layers, then
+// smaller blur) whose modeled per-cluster blended contrast clears `r` WITHIN the
+// bar (mass + mass-below-floor via option_within_bar, as for colours). Returns
+// that recipe + its rating, or null when no recipe in the space reaches `r`.
+export function solveShadowRecipe(
+  fg: Rgba,
+  shadow: Srgb8,
+  clusters: RecCluster[],
+  r: number,
+  floorRatio: number,
+  bar: number,
+): { recipe: ShadowRecipe; mass: number; worstRatio: number; massBelowFloor: number } | null {
+  for (const layers of SOLVER_LAYERS) {
+    for (const blur of SOLVER_BLURS) {
+      const C = layerCoverage(SHADOW_ALPHA, blur, 0, 0); // centered
+      const sf = shadowFailure(fg, shadow, Array(layers).fill(C), clusters, r, floorRatio);
+      if (sf.worstRatio >= r && optionWithinBar(sf.mass, sf.massBelowFloor, bar)) {
+        return { recipe: { layers, blur, coverage: C, aEff: 1 - Math.pow(1 - C, layers) }, ...sf };
+      }
+    }
+  }
+  return null;
+}
+
+// OUTLINE rating (background-INDEPENDENT). A hard outline REPLACES the letters'
+// adjacent surface, so contrast is fg (composited at its own alpha) vs the
+// outline colour ONLY — the sampled clusters play no part. [Spec mirrored into
+// the Rust oracle in parallel.]
+export function outlineRatio(fg: Rgba, outline: Srgb8): number {
+  return compositedRatio(rgb(fg), fg.a, outline);
+}
+
+// Strictest required ratio across an element's PEAK frames (animated runs vary
+// font metrics per frame; thresholds need no samples so all frames count).
+function requiredRatioFor(level: Level, elt: ElementStat): number {
+  const src = elt.frames.length ? elt.frames : [elt];
+  return src.reduce((mx, f) => Math.max(mx, effectiveThreshold(level, f.font_size, f.font_weight, null)), 0);
+}
+
+type Verdict = VerdictResult["elements"][number];
+const passesAtLevel = (v: Verdict | undefined, level: Level): boolean =>
+  v ? (level === "AAA" ? v.aaa : v.aa) : false;
+
+const isFailingAt = (elt: ElementStat, v: Verdict | undefined, level: Level): boolean =>
+  elt.indeterminate || !passesAtLevel(v, level);
+
+// ---------------------------------------------------------------------------
+// Grouping: element -> declared class, via verdicts.ts's parseElementClasses
+// (the SAME composite-key convention the gate's roll-up uses).
+// ---------------------------------------------------------------------------
+
+// roll-up key convention: classed -> `.name`, class-less -> `#id`.
+const keyForClass = (id: string, className: string | null) => (className === null ? `#${id}` : `.${className}`);
+
+// ---------------------------------------------------------------------------
+// Pooling: merge a group's element clusters by weight x sample-share (the same
+// rescale rollup.rs::pool applies) so a strip shows the FULL range the group
+// sits over, not one element's flat near-gray cluster.
+// ---------------------------------------------------------------------------
+
+function poolBands(members: ElementStat[]): PooledClusterStat[] {
+  const total = members.reduce((s, m) => s + m.total_samples, 0);
+  const n = Math.max(members.length, 1);
+  const bands: PooledClusterStat[] = [];
+  for (const m of members) {
+    const share = total > 0 ? m.total_samples / total : 1 / n;
+    for (const c of m.clusters) {
+      bands.push({ color: c.color, weight: c.weight * share, frames: c.frames, covariance: c.covariance });
+    }
+  }
+  // Weight desc, then a stable colour key — deterministic top-K.
+  bands.sort((a, b) => b.weight - a.weight || toHex(a.color).localeCompare(toHex(b.color)));
+  return bands.slice(0, MAX_BANDS);
+}
+
+// RecCluster pooling (color+weight only) for the policy math — ALL clusters, no
+// cap: the colour/halo solve must see the whole distribution.
+function poolRec(members: ElementStat[]): RecCluster[] {
+  const total = members.reduce((s, m) => s + m.total_samples, 0);
+  const n = Math.max(members.length, 1);
+  const out: RecCluster[] = [];
+  for (const m of members) {
+    const share = total > 0 ? m.total_samples / total : 1 / n;
+    for (const c of m.clusters) out.push({ color: rgb(c.color), weight: c.weight * share });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Option rows per group.
+// ---------------------------------------------------------------------------
+
+const colourName = (hex: string): string => (hex === "#000000" ? "black" : hex === "#ffffff" ? "white" : hex);
+const hexToSrgb = (h: string): Srgb8 => ({ r: parseInt(h.slice(1, 3), 16), g: parseInt(h.slice(3, 5), 16), b: parseInt(h.slice(5, 7), 16) });
+
+// Outliers' SHADOW / OUTLINE / BACKGROUND rows (heterogeneous fgs -> each row
+// SPLITS by the solved colour, carried as a per-selector `split`).
+// - OUTLINE (hard stroke) is background-INDEPENDENT: fg vs the outline colour.
+// - SHADOW (soft text-shadow) is background-DEPENDENT: rated per pooled cluster
+//   (the translucent shadow blended over the sampled backgrounds).
+function outlierAnchorRows(
+  members: ElementStat[],
+  level: Level,
+  outReq: number,
+  bands: PooledClusterStat[],
+  repOut: ElementStat,
+  bar: number,
+  floor: number,
+): { shadow: OptionRow; outline: OptionRow; background: OptionRow } {
+  const repFgHex = toHex(rgb(repOut.fg));
+  const recClusters = poolRec(members);
+  const base = {
+    scope: "outliers" as GroupScope,
+    requiredRatio: outReq,
+    bands,
+    fontSize: repOut.font_size,
+    fontWeight: repOut.font_weight,
+    specimenLabel: "Outliers",
+    autoChoice: false,
+  };
+
+  // Per-element solved black/white colour, grouped by colour (shared by SHADOW
+  // and OUTLINE — same colours, different ratings).
+  const colGroups = new Map<string, string[]>();
+  let outlineWorst = Infinity;
+  let unsolved = 0;
+  for (const e of members) {
+    const h = solveHaloAlpha(rgb(e.fg), requiredRatioFor(level, e), e.steady_alpha);
+    if (!h) { unsolved++; continue; }
+    const hx = toHex(h);
+    (colGroups.get(hx) ?? colGroups.set(hx, []).get(hx)!).push(e.id);
+    outlineWorst = Math.min(outlineWorst, outlineRatio(e.fg, h));
+  }
+  const entries = [...colGroups.entries()]
+    .map(([hex, ids]) => ({ hex, ids: ids.slice().sort(), count: ids.length }))
+    .sort((a, b) => b.count - a.count || a.hex.localeCompare(b.hex));
+  const ok = entries.length > 0;
+  const split = entries.map((e) => ({ selector: e.ids.map((id) => `#${id}`).join(", "), hex: e.hex }));
+  const selectorAll = split.map((s) => s.selector).join(", ");
+  const dominant = entries[0]?.hex;
+
+  // OUTLINE — background-independent (fg vs colour), worst across elements.
+  const outline: OptionRow = ok
+    ? {
+        ...base,
+        kind: "outline",
+        label: "Outline (text-stroke, per element)",
+        available: true,
+        textHex: repFgHex,
+        shadowHex: dominant,
+        ratio: outlineWorst,
+        passes: true,
+        selector: selectorAll,
+        split,
+        splitLabel: entries.map((e) => `${colourName(e.hex)} outline (${e.count})`).join(" · "),
+        note: "the outline replaces the sampled backgrounds — rated fg vs outline colour only (background-independent)." + (unsolved ? ` ${unsolved} element(s) opacity-limited.` : ""),
+      }
+    : { ...base, kind: "outline", label: "Outline (text-stroke, per element)", available: false, textHex: repFgHex, passes: false, selector: "", note: "opacity-limited: no element's outline reaches its required ratio." };
+
+  // SHADOW — the SOLVER over the pooled outlier clusters (dominant colour); the
+  // split carries every element's colour. Rated by the Gaussian falloff model.
+  const outlierShadow = ok && dominant ? solveShadowRecipe(repOut.fg, hexToSrgb(dominant), recClusters, outReq, floor, bar) : null;
+  const shadow: OptionRow = outlierShadow
+    ? {
+        ...base,
+        kind: "shadow",
+        label: `Soft shadow · ${outlierShadow.recipe.layers}× ${outlierShadow.recipe.blur}px (per element)`,
+        available: true,
+        textHex: repFgHex,
+        shadowHex: dominant,
+        ratio: outlierShadow.worstRatio,
+        passes: true,
+        failingMass: outlierShadow.mass,
+        massBelowFloor: outlierShadow.massBelowFloor,
+        withinBar: true,
+        selector: selectorAll,
+        split,
+        splitLabel: entries.map((e) => `${colourName(e.hex)} shadow (${e.count})`).join(" · "),
+        recipe: outlierShadow.recipe,
+        note: `proper soft shadow: ${outlierShadow.recipe.layers}× centered 0 0 ${outlierShadow.recipe.blur}px (Gaussian falloff) — rated per sampled background, NOT background-independent.`,
+      }
+    : { ...base, kind: "shadow", label: "Soft shadow (per element)", available: false, textHex: repFgHex, passes: false, selector: "", note: ok ? `no shadow recipe achieves ${outReq.toFixed(2)}:1 over the outlier backgrounds.` : "opacity-limited: no shadow colour." };
+
+  // BACKGROUND: recolor to the fg's anchor + a solid plate, per element.
+  const bgGroups = new Map<string, { ids: string[]; anchor: string; backing: string }>();
+  let bgWorst = Infinity;
+  let bgUnsolved = 0;
+  for (const e of members) {
+    const anchor = betterAnchor(rgb(e.fg));
+    const backing = solveHaloAlpha(anchor, requiredRatioFor(level, e), e.steady_alpha);
+    if (!backing) { bgUnsolved++; continue; }
+    const key = `${toHex(anchor)}|${toHex(backing)}`;
+    const g = bgGroups.get(key) ?? bgGroups.set(key, { ids: [], anchor: toHex(anchor), backing: toHex(backing) }).get(key)!;
+    g.ids.push(e.id);
+    bgWorst = Math.min(bgWorst, compositedRatio(anchor, e.steady_alpha, backing));
+  }
+  const bgEntries = [...bgGroups.values()]
+    .map((g) => ({ ...g, ids: g.ids.slice().sort(), count: g.ids.length }))
+    .sort((a, b) => b.count - a.count || a.anchor.localeCompare(b.anchor));
+  const bgOk = bgEntries.length > 0;
+  const bgSplit = bgEntries.map((e) => ({ selector: e.ids.map((id) => `#${id}`).join(", "), hex: e.anchor, backingHex: e.backing }));
+  // Unavailable rows take the proper unavailable shape (no textHex/backingHex) so
+  // the specimen never emits `color:undefined` (F8).
+  const background: OptionRow = bgOk
+    ? {
+        ...base,
+        kind: "background",
+        label: "Background plate (per element)",
+        available: true,
+        textHex: bgEntries[0].anchor,
+        backingHex: bgEntries[0].backing,
+        ratio: bgWorst,
+        passes: true,
+        selector: bgSplit.map((s) => s.selector).join(", "),
+        split: bgSplit,
+        splitLabel: bgEntries.map((e) => `${colourName(e.anchor)} on ${colourName(e.backing)} (${e.count})`).join(" · "),
+        note: "guaranteed fix: recolor each element to its anchor and paint a solid plate behind it." + (bgUnsolved ? ` ${bgUnsolved} element(s) opacity-limited.` : ""),
+      }
+    : {
+        ...base,
+        kind: "background",
+        label: "Background plate (per element)",
+        available: false,
+        passes: false,
+        selector: "",
+        note: "opacity-limited: even an anchor over a solid plate cannot reach the required ratio.",
+      };
+
+  return { shadow, outline, background };
+}
+
+// The three option rows for one group at one level: COLOUR (hue-preserving
+// recolor over the pooled clusters), HALO (shadow), BACKGROUND (recolor to an
+// anchor + solid backing). `colourOpt` is the group's roll-up recolor lead.
+function groupRows(args: {
+  scope: GroupScope;
+  level: Level;
+  members: ElementStat[]; // determinate members whose clusters/font drive the group
+  repElt: ElementStat; // the representative (roll-up basis) element
+  requiredRatio: number;
+  colourOpt: RecOption | null;
+  bands: PooledClusterStat[];
+  recClusters: RecCluster[]; // full pooled clusters for the SHADOW per-cluster rating
+  bar: number;
+  floor: number;
+  exceptionIds?: string[];
+  autoColourEligible: boolean; // AA corpus colour keeps the auto-choice badge
+  specimenLabel: string;
+  selector: string;
+}): OptionRow[] {
+  const { scope, level, repElt, requiredRatio, colourOpt, bands, recClusters, bar, floor, exceptionIds, autoColourEligible } = args;
+  const fg = rgb(repElt.fg);
+  const a = repElt.steady_alpha;
+  const fontSize = repElt.font_size;
+  const fontWeight = repElt.font_weight;
+  const base = { scope, requiredRatio, bands, fontSize, fontWeight, specimenLabel: args.specimenLabel, selector: args.selector };
+  const rows: OptionRow[] = [];
+
+  // COLOUR
+  if (colourOpt) {
+    const est = colourOpt.estimatedFailure;
+    rows.push({
+      ...base,
+      kind: "colour",
+      label: `${scope === "corpus" ? "Corpus" : "Outliers"} recolor · ${colourOpt.fix.strategy ?? "anchor"}`,
+      available: true,
+      textHex: toHex(colourOpt.fix.color),
+      strategy: colourOpt.fix.strategy,
+      ratio: est.worstRatio,
+      passes: est.worstRatio >= requiredRatio,
+      failingMass: est.mass,
+      massBelowFloor: est.massBelowFloor,
+      withinBar: colourOpt.withinBar,
+      autoChoice: autoColourEligible && colourOpt.withinBar,
+      exceptionIds: exceptionIds && exceptionIds.length ? exceptionIds : undefined,
+      note: colourOpt.withinBar
+        ? undefined
+        : `no within-bar hue-preserving colour at ${level} (the mid-gray backgrounds cap the reachable ratio); best effort shown.`,
+    });
+  } else {
+    rows.push({
+      ...base,
+      kind: "colour",
+      label: `${scope === "corpus" ? "Corpus" : "Outliers"} recolor`,
+      available: false,
+      textHex: toHex(fg),
+      passes: false,
+      autoChoice: false,
+      note: "no feasible recolor for this group (no sampled background).",
+    });
+  }
+
+  // The black/white treatment colour (both shadow and outline use it).
+  const halo = solveHaloAlpha(fg, requiredRatio, a);
+
+  // SHADOW (soft text-shadow) — the SOLVER proposes the minimal recipe whose
+  // MODELED (falloff) per-cluster blended contrast clears the ratio within bar.
+  const shadowRow = halo ? solveShadowRecipe(repElt.fg, halo, recClusters, requiredRatio, floor, bar) : null;
+  if (shadowRow) {
+    const rc = shadowRow.recipe;
+    rows.push({
+      ...base,
+      kind: "shadow",
+      label: `Soft shadow · ${rc.layers}× ${rc.blur}px`,
+      available: true,
+      textHex: toHex(fg),
+      shadowHex: toHex(halo!),
+      ratio: shadowRow.worstRatio,
+      passes: true,
+      failingMass: shadowRow.mass,
+      massBelowFloor: shadowRow.massBelowFloor,
+      withinBar: true,
+      autoChoice: false,
+      recipe: rc,
+      note: `proper soft shadow: ${rc.layers}× centered 0 0 ${rc.blur}px (Gaussian falloff, per-layer coverage ${rc.coverage.toFixed(3)}, a_eff ${rc.aEff.toFixed(3)}) — rated per sampled background, NOT background-independent.`,
+    });
+  } else {
+    rows.push({ ...base, kind: "shadow", label: "Soft shadow", available: false, textHex: toHex(fg), passes: false, autoChoice: false, note: halo ? `no shadow recipe achieves ${requiredRatio.toFixed(2)}:1 over the sampled backgrounds (Gaussian falloff model).` : `opacity-limited: no black/white shadow colour at alpha ${a.toFixed(3)}.` });
+  }
+
+  // OUTLINE (hard stroke) — background-INDEPENDENT: rated fg vs the outline
+  // colour ONLY; the outline replaces the sampled backgrounds.
+  if (halo) {
+    rows.push({
+      ...base,
+      kind: "outline",
+      label: "Outline (text-stroke)",
+      available: true,
+      textHex: toHex(fg),
+      shadowHex: toHex(halo),
+      ratio: outlineRatio(repElt.fg, halo),
+      passes: true,
+      autoChoice: false,
+      note: "the outline replaces the sampled backgrounds — rated fg vs outline colour only (background-independent).",
+    });
+  } else {
+    rows.push({ ...base, kind: "outline", label: "Outline (text-stroke)", available: false, textHex: toHex(fg), passes: false, autoChoice: false, note: `opacity-limited: no black/white outline colour reaches ${requiredRatio.toFixed(2)}:1 at alpha ${a.toFixed(3)}.` });
+  }
+
+  // BACKGROUND (recolor_with_backing)
+  const anchor = betterAnchor(fg);
+  const backing = solveHaloAlpha(anchor, requiredRatio, a);
+  rows.push(
+    backing
+      ? {
+          ...base,
+          kind: "background",
+          label: "Background plate (recolor + backing)",
+          available: true,
+          textHex: toHex(anchor),
+          backingHex: toHex(backing),
+          ratio: compositedRatio(anchor, a, backing),
+          passes: true,
+          autoChoice: false,
+          note: "guaranteed fix: recolor the text to the anchor and paint a solid plate behind it.",
+        }
+      : {
+          ...base,
+          kind: "background",
+          label: "Background plate (recolor + backing)",
+          available: false,
+          textHex: toHex(anchor),
+          passes: false,
+          autoChoice: false,
+          note: `opacity-limited: even an anchor over a solid plate cannot reach ${requiredRatio.toFixed(2)}:1 at alpha ${a.toFixed(3)}.`,
+        },
+  );
+
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// The aggregate build.
+// ---------------------------------------------------------------------------
+
+export function buildAggregate(
+  stats: Statistics,
+  templateText: string,
+  opts: { video?: VideoRef | null; remediatedStats?: Statistics | null } = {},
+): AggregateDoc {
+  const bar = DEFAULT_BAR;
+  const floor = DEFAULT_MIN_LEAD_RATIO;
+  const verdicts = resolveVerdicts(stats);
+  const runById = new Map(verdicts.elements.map((v) => [v.id, v]));
+  const classMap = parseElementClasses(templateText);
+  const scored = stats.elements;
+  const classOf = (id: string) => classMap.get(id) ?? null;
+  const keyOf = (id: string) => keyForClass(id, classOf(id));
+
+  // Group scored elements by roll-up key; the corpus is the largest group
+  // (ties: most pooled samples, then key order).
+  const groups = new Map<string, ElementStat[]>();
+  for (const e of scored) {
+    const k = keyOf(e.id);
+    (groups.get(k) ?? groups.set(k, []).get(k)!).push(e);
+  }
+  const corpusKey = [...groups.entries()].sort((a, b) => {
+    const [ka, ea] = a;
+    const [kb, eb] = b;
+    return (
+      eb.length - ea.length ||
+      eb.reduce((s, m) => s + m.total_samples, 0) - ea.reduce((s, m) => s + m.total_samples, 0) ||
+      ka.localeCompare(kb)
+    );
+  })[0][0];
+  const corpusMembers = (groups.get(corpusKey) ?? []).slice().sort(byId);
+
+  // Build the per-level policy inputs once per level and roll up.
+  const buildRuns = (level: Level): RunPolicyInput[] =>
+    scored.map((e) => ({
+      id: e.id,
+      className: classOf(e.id),
+      fg: rgb(e.fg),
+      fgAlpha: e.steady_alpha,
+      requiredRatio: requiredRatioFor(level, e),
+      bgLums: e.clusters.map((c) => relativeLuminance(c.color)),
+      clusters: e.clusters.map((c) => ({ color: rgb(c.color), weight: c.weight })),
+      totalSamples: e.total_samples,
+      indeterminate: e.indeterminate,
+      passes: passesAtLevel(runById.get(e.id), level),
+    }));
+
+  const corpusStrip = poolBands(corpusMembers.filter((e) => !e.indeterminate));
+
+  const buildLevel = (level: Level): LevelSection => {
+    const rollup: ClassPolicyResult[] = rollUpPolicy(buildRuns(level), bar, floor);
+    const corpusResult = rollup.find((r) => r.classKey === corpusKey) ?? null;
+    const corpusDeterminate = corpusMembers.filter((e) => !e.indeterminate);
+    const repElt = corpusDeterminate[0] ?? corpusMembers[0];
+    const corpusReq = corpusDeterminate.reduce((mx, e) => Math.max(mx, requiredRatioFor(level, e)), 0) || requiredRatioFor(level, repElt);
+    const corpusColour = corpusResult?.recolorOptions?.[0] ?? null;
+    const withinClassExceptions = (corpusResult?.exceptions ?? []).filter((x) => !x.indeterminate).map((x) => x.id);
+
+    // CORPUS rows: [colour, shadow, outline, background].
+    const [corpusColourRow, corpusShadowRow, corpusOutlineRow, corpusBgRow] = groupRows({
+      scope: "corpus",
+      level,
+      members: corpusDeterminate,
+      repElt,
+      requiredRatio: corpusReq,
+      colourOpt: corpusColour,
+      bands: corpusStrip,
+      recClusters: poolRec(corpusDeterminate),
+      bar,
+      floor,
+      exceptionIds: withinClassExceptions,
+      autoColourEligible: level === "AA",
+      specimenLabel: "Corpus",
+      selector: corpusKey, // the class key is already a valid CSS selector (.w / #id)
+    });
+
+    // OUTLIERS = corpus within-class exceptions + all failing members of OTHER
+    // classes (elements the corpus colour does not serve). One group, one COLOUR
+    // row — the halo/background rows are the same anchor treatment for everyone.
+    const exceptionSet = new Set(withinClassExceptions);
+    const outlierMembers = scored
+      .filter(
+        (e) =>
+          !e.indeterminate &&
+          isFailingAt(e, runById.get(e.id), level) &&
+          (exceptionSet.has(e.id) || keyOf(e.id) !== corpusKey),
+      )
+      .sort(byId);
+
+    // Two SEPARATED group blocks — corpus first, then outliers (never interleaved).
+    const groups: GroupBlock[] = [
+      {
+        scope: "corpus",
+        title: `Main captions (corpus ${corpusKey})`,
+        rows: [corpusColourRow, corpusShadowRow, corpusOutlineRow, corpusBgRow],
+      },
+    ];
+
+    if (outlierMembers.length > 0) {
+      const repOut = outlierMembers
+        .slice()
+        .sort((a, b) => b.total_samples - a.total_samples || byId(a, b))[0];
+      const outReq = outlierMembers.reduce((mx, e) => Math.max(mx, requiredRatioFor(level, e)), 0);
+      const outlierBands = poolBands(outlierMembers);
+      const outColour = buildRecolorOptionsAlpha(rgb(repOut.fg), repOut.steady_alpha, poolRec(outlierMembers), outReq, bar, floor)[0] ?? null;
+      const sameAsCorpus = !!(corpusColour && outColour && sameColor(outColour.fix.color, corpusColour.fix.color));
+      // The COLOUR row is the honest drastic recolor (often above bar for the
+      // messy outlier backgrounds); halo/background are the background-independent
+      // alternatives that make the drastic recolor unnecessary.
+      const outlierColourRow = groupRows({
+        scope: "outliers",
+        level,
+        members: outlierMembers,
+        repElt: repOut,
+        requiredRatio: outReq,
+        colourOpt: outColour,
+        bands: outlierBands,
+        recClusters: poolRec(outlierMembers),
+        bar,
+        floor,
+        exceptionIds: outlierMembers.map((e) => e.id),
+        autoColourEligible: false,
+        specimenLabel: "Outliers",
+        selector: outlierMembers.map((e) => `#${e.id}`).join(", "),
+      }).find((r) => r.kind === "colour")!;
+      if (sameAsCorpus && outlierColourRow.note === undefined) {
+        outlierColourRow.note = "same colour as the corpus — these outliers can take the corpus recolor.";
+      }
+      const { shadow, outline, background } = outlierAnchorRows(outlierMembers, level, outReq, outlierBands, repOut, bar, floor);
+      groups.push({
+        scope: "outliers",
+        title: `Outliers (${outlierMembers.length} element${outlierMembers.length === 1 ? "" : "s"})`,
+        rows: [outlierColourRow, shadow, outline, background],
+      });
+    }
+
+    return {
+      level,
+      corpusRequiredRatio: corpusReq,
+      largeText: isLargeText(repElt.font_size, repElt.font_weight),
+      groups,
+    };
+  };
+
+  const levels = [buildLevel("AA"), buildLevel("AAA")];
+
+  // Appendix: every failing scored element (id, class, group, current ratio).
+  const outlierIds = new Set<string>();
+  for (const lv of levels) for (const g of lv.groups) for (const r of g.rows) if (r.scope === "outliers" && r.exceptionIds) for (const id of r.exceptionIds) outlierIds.add(id);
+  const failing = scored
+    .filter((e) => isFailingAt(e, runById.get(e.id), "AA") || isFailingAt(e, runById.get(e.id), "AAA"))
+    .sort(byId);
+  const appendix: AppendixEntry[] = failing.map((e) => {
+    const v = runById.get(e.id);
+    const inCorpus = keyOf(e.id) === corpusKey && !outlierIds.has(e.id);
+    return {
+      id: e.id,
+      className: keyOf(e.id),
+      group: inCorpus ? "corpus" : "outliers",
+      currentRatio: v ? v.worstFrameRatio : 0,
+      aa: v ? v.aa : false,
+      aaa: v ? v.aaa : false,
+      indeterminate: e.indeterminate,
+    };
+  });
+
+  const outlierMemberCount = appendix.filter((a) => a.group === "outliers").length;
+  return {
+    schema: 2,
+    bar,
+    floor,
+    passed: verdicts.failingAA === 0,
+    corpusClassKey: corpusKey,
+    corpusMemberCount: appendix.length - outlierMemberCount,
+    outlierMemberCount,
+    failingCount: appendix.length,
+    levels,
+    appendix,
+    video: opts.video ?? null,
+    measured: opts.remediatedStats
+      ? { beforeFailing: verdicts.failingAA, afterFailing: resolveVerdicts(opts.remediatedStats).failingAA }
+      : null,
+  };
+}
+
+// Count the option rows across both level sections (the page-length budget).
+export const countOptionRows = (doc: AggregateDoc): number =>
+  doc.levels.reduce((n, lv) => n + lv.groups.reduce((m, g) => m + g.rows.length, 0), 0);
+
+// Pick the ORIGINAL (pre-remediation) render to preview. Pure over a file-exists
+// predicate so it is unit-testable. `postApply` = template.draft.wv exists,
+// meaning out.mp4 / out.silent.mp4 are the REMEDIATED renders, not the original.
+export function resolveVideo(has: (f: string) => boolean, postApply: boolean): VideoRef | null {
+  if (postApply) {
+    if (has("out.draft.silent.mp4")) return { src: "out.draft.silent.mp4" };
+    return { src: null, reason: "original render not available — current renders reflect applied changes" };
+  }
+  if (has("out.mp4")) return { src: "out.mp4" };
+  if (has("out.silent.mp4")) return { src: "out.silent.mp4" };
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Page assembly + IO layer (the IO parts are not exercised by the unit tests).
+// ---------------------------------------------------------------------------
+
+// The shared design-token SSOT, resolved relative to this module (repo-root
+// preview/page/tokens.css). Its content is part of the studio's input.
+export const TOKENS_CSS_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../../preview/page/tokens.css",
+);
+export function readTokensCss(): string {
+  return readFileSync(TOKENS_CSS_PATH, "utf8");
+}
+
+function readJson<T>(p: string): T {
+  return JSON.parse(readFileSync(p, "utf8")) as T;
+}
+
+// Fill a missing statistics file by RE-RUNNING the analyzer over existing raw
+// samples (never sampling/rendering here). Statistics only — the analyzer's
+// unused report goes to stdout, silenced; exit 1 (failing runs present) is a
+// valid outcome.
+function regenerateStatistics(finalDir: string, statsPath: string): void {
+  const req = createRequire(import.meta.url);
+  const { WCAG_CONTRAST_BIN } = req("../../../config.ts");
+  const samples = path.join(finalDir, "wcag-contrast-samples.json");
+  const r = spawnSync(WCAG_CONTRAST_BIN, [samples, "--statistics", statsPath], {
+    stdio: ["ignore", "ignore", "inherit"],
+  });
+  if (r.error) throw new Error(`recommend: failed to spawn analyzer: ${r.error.message}`);
+  if (r.status !== 0 && r.status !== 1) {
+    throw new Error(`recommend: analyzer exited ${r.status ?? `signal ${r.signal}`}`);
+  }
+}
+
+export function runStudio(runDir: string): { jsonPath: string; htmlPath: string; variantsPath: string; doc: AggregateDoc } {
+  const finalDir = path.join(runDir, "final");
+  const statsPath = path.join(finalDir, "contrast-statistics.json");
+  const samplesPath = path.join(finalDir, "wcag-contrast-samples.json");
+  const templatePath = path.join(finalDir, "template.wv");
+
+  if (!existsSync(statsPath)) {
+    if (!existsSync(samplesPath)) {
+      throw new Error(
+        `recommend: no contrast-statistics.json and no wcag-contrast-samples.json in ${finalDir} — run the WCAG pass first:\n  node --import tsx pipeline/scripts/wcag-pass.ts --run ${runDir}`,
+      );
+    }
+    regenerateStatistics(finalDir, statsPath);
+  }
+  if (!existsSync(templatePath)) {
+    throw new Error(`recommend: template.wv missing in ${finalDir} — cannot roll up by class. Re-run the WCAG pass.`);
+  }
+
+  const stats = readJson<Statistics>(statsPath);
+  const templateText = readFileSync(templatePath, "utf8");
+
+  // The studio is a PRE-DECISION view: the preview must be the ORIGINAL,
+  // unremediated render. If template.draft.wv exists the run is post-apply and
+  // out.mp4 / out.silent.mp4 are the REMEDIATED renders — fall back to the draft
+  // silent render, else omit with an honest reason. Otherwise out.mp4 IS original.
+  const has = (f: string) => existsSync(path.join(finalDir, f));
+  const postApply = has("template.draft.wv");
+  const video = resolveVideo(has, postApply);
+
+  const remediatedPath = path.join(finalDir, "contrast-statistics.remediated.json");
+  const remediatedStats = existsSync(remediatedPath) ? readJson<Statistics>(remediatedPath) : null;
+
+  const doc = buildAggregate(stats, templateText, { video, remediatedStats });
+  const tokensCss = readTokensCss();
+  const jsonPath = path.join(finalDir, "wcag-recommendations.json");
+  const htmlPath = path.join(finalDir, "wcag-recommendations.html");
+  const variantsPath = path.join(finalDir, "wcag-design-variants.html");
+  writeFileSync(jsonPath, JSON.stringify(doc, null, 2) + "\n");
+  writeFileSync(htmlPath, renderPage(doc, tokensCss));
+  writeFileSync(variantsPath, renderVariantsPage(doc, tokensCss)); // static design chooser
+  return { jsonPath, htmlPath, variantsPath, doc };
+}
+
+function isMainModule(argvPath: string | undefined, moduleUrl: string): boolean {
+  return !!argvPath && path.resolve(argvPath) === fileURLToPath(moduleUrl);
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  const i = process.argv.indexOf("--run");
+  const runDir = i >= 0 ? process.argv[i + 1] : undefined;
+  if (!runDir) {
+    console.error("usage: node --import tsx pipeline/scripts/wcag/recommend.ts --run runs/<key>");
+    process.exit(1);
+  }
+  try {
+    const { jsonPath, htmlPath, variantsPath, doc } = runStudio(runDir);
+    console.log(
+      `[recommend] ${doc.failingCount} failing element(s): corpus ${doc.corpusClassKey} (${doc.corpusMemberCount}) + ${doc.outlierMemberCount} outlier(s); ${countOptionRows(doc)} option rows.`,
+    );
+    console.log(`[recommend] wrote ${jsonPath}`);
+    console.log(`[recommend] wrote ${htmlPath}`);
+    console.log(`[recommend] wrote ${variantsPath}`);
+    process.exit(0);
+  } catch (e: any) {
+    console.error(String(e?.message ?? e));
+    process.exit(1);
+  }
+}
diff --git a/pipeline/scripts/wcag/remediate.ts b/pipeline/scripts/wcag/remediate.ts
new file mode 100644
index 0000000..3c7d80a
--- /dev/null
+++ b/pipeline/scripts/wcag/remediate.ts
@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// WCAG remediation applier — applies a remediation PLAN (computed by
+// wcag-pass.ts from the contrast statistics + the TS policy layer) to a
+// template directory:
+//
+//   node pipeline/scripts/wcag/remediate.ts \
+//       (--plan wcag-remediation-plan.json | --choice wcag-choice.json) \
+//       --template-dir <dir>
+//
+// POLICY: the automatic path (--plan) applies COLORS ONLY — the plan's rules
+// are within-bar recolors. Halo / recolor+backing recommendations are NEVER
+// auto-applied; they arrive as plan notes and surface as CSS comments for human
+// review. A USER-CHOSEN option (--choice) is different: the click/chat pick IS
+// the human approval, so chosen options apply beyond colours-only (shadow /
+// outline / background). The applier makes no policy decisions of its own.
+//
+// Outputs a SIBLING runnable template dir `<dir>.wcag-remediated/` (source dir
+// is never touched; sibling depth keeps relative asset paths resolving —
+// veed-engine-cli only accepts template directories) containing:
+//   - template.wv|template.html — copy with an injected
+//     `<style id="wcag-remediation">` block (re-running REPLACES the block)
+//   - wcag-remediation.css — the same rules as a standalone inspectable file,
+//     with per-rule evidence comments and a comment for every recommendation
+//     that could NOT be applied
+//   - every other file of the source dir, copied as-is
+//
+// The injected block is appended LAST inside <head>, so its same-specificity
+// rules win the cascade's source-order tie-break against author declarations.
+//
+// Runs under plain `node` (native .ts type-stripping, >=22.18) — no tsx.
+
+import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import process from "node:process";
+
+import { DEFAULT_SHADOW_RECIPE, parseChoiceFile, type ChoiceFile } from "./wcag-choice.ts";
+
+export const REMEDIATION_BLOCK_ID = "wcag-remediation";
+
+/** sRGB bytes → lowercase 6-digit CSS hex. Exported as the SSOT formatter —
+ * tests must import this, never mirror the formula. */
+export const hex = (c: { r: number; g: number; b: number }): string =>
+  "#" + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("");
+
+/** One applied colour rule. `massPct` / `worstRatio` are evidence for the CSS
+ * comment (estimated failing mass %, worst per-cluster ratio of the new colour). */
+export interface PlanRule {
+  selector: string;
+  hex: string;
+  massPct: number;
+  worstRatio: number;
+}
+
+/** The applier's whole input contract. `notes` carry every recommendation that
+ * is NOT applied (halo/backing/no-colour/indeterminate), verbatim from the
+ * gate's dispositions — emitted as comments so nothing failing goes unlisted. */
+export interface RemediationPlan {
+  level: "AA";
+  rules: PlanRule[];
+  notes: string[];
+}
+
+export function parsePlanFile(raw: unknown): RemediationPlan {
+  const p = raw as RemediationPlan;
+  if (!p || p.level !== "AA" || !Array.isArray(p.rules) || !Array.isArray(p.notes)) {
+    throw new Error("wcag-remediation-plan: expected { level: 'AA', rules: [], notes: [] }");
+  }
+  for (const r of p.rules) {
+    if (!r.selector || !/^#[0-9a-f]{6}$/.test(r.hex)) {
+      throw new Error(`wcag-remediation-plan: bad rule ${JSON.stringify(r)} (need selector + 6-digit lowercase hex)`);
+    }
+  }
+  return p;
+}
+
+/** The full remediation stylesheet for a plan. Colors only. */
+export function buildPlanCss(plan: RemediationPlan): string {
+  const lines: string[] = [
+    `/* WCAG remediation — generated by pipeline/scripts/wcag/remediate.ts`,
+    `   level ${plan.level}, automatic hue-preserving colour set, colours only.`,
+    `   Evidence per rule below; unapplied recommendations left as comments. */`,
+  ];
+  for (const r of plan.rules) {
+    lines.push(
+      `/* ${r.selector}: recolor (estimated failure ${r.massPct.toFixed(1)}%, worst ${r.worstRatio.toFixed(2)}:1) */`,
+      `${r.selector} { color: ${r.hex}; }`,
+    );
+  }
+  for (const n of plan.notes) {
+    lines.push(`/* not applied — ${n} */`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Inject (or REPLACE — idempotent) the remediation style block. Placed before
+ * `</head>` so it follows the author's styles in the cascade; falls back to
+ * before `</body>`, else appends.
+ */
+export function injectRemediationBlock(html: string, css: string): string {
+  const block = `<style id="${REMEDIATION_BLOCK_ID}">\n${css}</style>`;
+  const existing = new RegExp(
+    `<style id="${REMEDIATION_BLOCK_ID}">[\\s\\S]*?</style>`,
+  );
+  if (existing.test(html)) return html.replace(existing, block);
+  for (const anchor of ["</head>", "</body>"]) {
+    const i = html.indexOf(anchor);
+    if (i >= 0) return html.slice(0, i) + block + "\n" + html.slice(i);
+  }
+  return html + "\n" + block + "\n";
+}
+
+/**
+ * The remediation stylesheet for USER-CHOSEN options (the --choice path). The
+ * click in the studio (or the chat pick) IS the human approval, so this applies
+ * chosen options beyond colours-only: colour -> `color`, shadow ->
+ * `text-shadow` stack, outline -> `-webkit-text-stroke`, background ->
+ * `color` + `background-color`. Selectors are carried in each entry, so no
+ * re-derivation happens here.
+ */
+export function buildChoiceCss(file: ChoiceFile): string {
+  const lines: string[] = [
+    `/* WCAG remediation — generated by pipeline/scripts/wcag/remediate.ts --choice.`,
+    `   User-chosen via the studio or chat (the pick is the approval; shadow/outline/`,
+    `   background are unlocked by an explicit choice — colours-only is the no-choice default). */`,
+  ];
+  for (const c of file.chosen) {
+    // A heterogeneous group (outlier shadow/background) carries a per-selector
+    // `split`; otherwise the single `selector` is the one part.
+    const parts =
+      c.split && c.split.length > 0
+        ? c.split
+        : c.selector
+          ? [{ selector: c.selector, hex: c.hex, backingHex: c.backingHex }]
+          : null;
+    if (!parts) throw new Error(`wcag-choice: ${c.level} ${c.group} ${c.kind} has no selector — cannot apply`);
+    lines.push(
+      `/* ${parts[0].selector}: user-chosen — ${c.level} ${c.group} ${c.kind}${c.split ? ` (${c.split.length}-way split)` : ""} */`,
+    );
+    for (const p of parts) {
+      if (c.kind === "colour") {
+        lines.push(`${p.selector} { color: ${p.hex}; }`);
+      } else if (c.kind === "shadow") {
+        // Soft-shadow STACK from the solved recipe: `layers` centered `0 0 {blur}px`
+        // shadows, same colour at the modelled coverage alpha (0.85 -> hex d9).
+        const { layers, blur } = c.recipe ?? DEFAULT_SHADOW_RECIPE;
+        const stack = Array.from({ length: layers }, () => `0 0 ${blur}px ${p.hex}d9`).join(", ");
+        lines.push(`${p.selector} { text-shadow: ${stack}; }`);
+      } else if (c.kind === "outline") {
+        lines.push(`${p.selector} { -webkit-text-stroke: 1.5px ${p.hex}; }`);
+      } else {
+        lines.push(`${p.selector} { color: ${p.hex}; background-color: ${p.backingHex}; }`);
+      }
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+function usage(msg?: string): never {
+  if (msg) console.error(`remediate: ${msg}`);
+  console.error(
+    "usage: node pipeline/scripts/wcag/remediate.ts (--plan <wcag-remediation-plan.json> | --choice <wcag-choice.json>) --template-dir <dir>",
+  );
+  process.exit(2);
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  let planPath = "";
+  let choicePath = "";
+  let templateDir = "";
+  for (let i = 0; i < args.length; i++) {
+    const next = () => {
+      const v = args[++i];
+      if (v === undefined || v === "") usage(`${args[i - 1]} requires a value`);
+      return v;
+    };
+    switch (args[i]) {
+      case "--plan": planPath = next(); break;
+      case "--choice": choicePath = next(); break;
+      case "--template-dir": templateDir = next(); break;
+      default: usage(`unknown argument '${args[i]}'`);
+    }
+  }
+  if (!templateDir) usage("--template-dir is required");
+  if (planPath && choicePath) usage("--plan and --choice are mutually exclusive");
+  if (!planPath && !choicePath) usage("one of --plan or --choice is required");
+
+  const css = choicePath
+    ? buildChoiceCss(parseChoiceFile(JSON.parse(readFileSync(choicePath, "utf8"))))
+    : buildPlanCss(parsePlanFile(JSON.parse(readFileSync(planPath, "utf8"))));
+
+  const srcDir = resolve(templateDir);
+  const templateName = ["template.wv", "template.html"].find((n) =>
+    existsSync(join(srcDir, n)),
+  );
+  if (!templateName) usage(`no template.wv or template.html in ${srcDir}`);
+
+  const outDir = join(dirname(srcDir), `${basename(srcDir)}.wcag-remediated`);
+  rmSync(outDir, { recursive: true, force: true });
+  cpSync(srcDir, outDir, { recursive: true });
+
+  const html = readFileSync(join(srcDir, templateName), "utf8");
+  writeFileSync(join(outDir, templateName), injectRemediationBlock(html, css));
+  writeFileSync(join(outDir, "wcag-remediation.css"), css);
+
+  const ruleCount = (css.match(/^\S.* \{ /gm) ?? []).length;
+  const noteCount = (css.match(/not applied — /g) ?? []).length;
+  const how = choicePath ? "user-chosen rule(s) applied" : "color rule(s) applied";
+  console.log(
+    `wcag-remediation: ${ruleCount} ${how}, ${noteCount} recommendation(s) left for human review -> ${outDir}`,
+  );
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename)) {
+  main();
+}
diff --git a/pipeline/scripts/wcag/verdicts.ts b/pipeline/scripts/wcag/verdicts.ts
new file mode 100644
index 0000000..b819d95
--- /dev/null
+++ b/pipeline/scripts/wcag/verdicts.ts
@@ -0,0 +1,161 @@
+// STATISTICS-NATIVE verdict resolver — scores WCAG AA/AAA run verdicts from the
+// analyzer's policy-free `contrast-statistics.json`. The statistics carry ONLY
+// the peak-plateau frames; each sampled peak frame is scored with ITS OWN fg /
+// font metrics against its own clusters, and the run passes a level iff EVERY
+// sampled peak frame clears that frame's threshold AND no peak frame is
+// unsampled. Unit-tested in tests/wcag-verdicts.test.ts.
+//
+// Also home of the `contrast-statistics.json` consumer types (field names are
+// the analyzer's serialized output, schema version 1) and the template class
+// parser the roll-up grouping uses.
+
+import {
+  compositeLuminance,
+  effectiveThreshold,
+  ratioFromLuminance,
+  relativeLuminance,
+  type Rgba,
+  type Srgb8,
+} from "./policy.ts";
+
+// ---------------------------------------------------------------------------
+// contrast-statistics.json shape.
+// ---------------------------------------------------------------------------
+
+export interface ClusterStat {
+  color: Srgb8;
+  weight: number;
+  covariance: number[][]; // OKLAB sample covariance, row-major [[f64;3];3]
+}
+export interface PooledClusterStat extends ClusterStat {
+  frames: number[];
+}
+export interface FrameStat {
+  frame: number;
+  fg: Rgba;
+  font_size: number;
+  font_weight: number;
+  unsampled: boolean;
+  shadows?: unknown[];
+  clusters: ClusterStat[];
+}
+export interface ElementStat {
+  id: string;
+  rect: { x: number; y: number; w: number; h: number };
+  font_size: number;
+  font_weight: number;
+  shadows?: unknown[];
+  steady_alpha: number;
+  fg: Rgba;
+  total_samples: number;
+  total_frames: number;
+  unscored_transient_frames: number;
+  sampled_transient_frames: number;
+  indeterminate: boolean;
+  unsampled_frames?: { n: number; of: number };
+  clusters: PooledClusterStat[];
+  frames: FrameStat[];
+}
+export interface Statistics {
+  version: number;
+  fps: number;
+  selection?: string;
+  audit_density_fps?: number;
+  budget_overflow_frames: number;
+  elements: ElementStat[];
+}
+
+// ---------------------------------------------------------------------------
+// Grouping: element -> declared class, from the template (the SAME source the
+// analyzer's roll-up used).
+// ---------------------------------------------------------------------------
+
+// Parse `id -> composite class key` (null when the element has no class attribute)
+// from the weave/HTML template. An element is keyed by the SORTED, dot-joined
+// set of ALL its class tokens — class="w fade" => "fade.w" — so multi-class
+// elements group by their full class set, never by the first token alone
+// (leading dot added by the caller).
+export function parseElementClasses(templateText: string): Map<string, string | null> {
+  const out = new Map<string, string | null>();
+  for (const m of templateText.matchAll(/<[a-zA-Z][^>]*>/g)) {
+    const tag = m[0];
+    const id = /\bid="([^"]*)"/.exec(tag)?.[1];
+    if (id === undefined) continue;
+    const cls = /\bclass="([^"]*)"/.exec(tag)?.[1];
+    const tokens = cls ? cls.trim().split(/\s+/).filter((t) => t.length > 0) : [];
+    out.set(id, tokens.length ? [...tokens].sort().join(".") : null);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Uncredited per-element verdicts.
+// ---------------------------------------------------------------------------
+
+export interface ElementVerdict {
+  id: string;
+  aa: boolean;
+  aaa: boolean;
+  indeterminate: boolean;
+  /** Worst per-(peak-)frame ratio; 0 when nothing could be scored. */
+  worstFrameRatio: number;
+}
+
+export interface VerdictResult {
+  elements: ElementVerdict[];
+  failingAA: number;
+  failingAAA: number;
+  indeterminateCount: number;
+}
+
+// Ratio of a frame's fg (composited at its own alpha) over one background
+// cluster — the same math as policy.ts's pooled loop, applied per frame.
+function frameClusterRatio(fg: Rgba, clusterColor: Srgb8): number {
+  const lBg = relativeLuminance(clusterColor);
+  const lFg = compositeLuminance(relativeLuminance(fg), fg.a, lBg);
+  return ratioFromLuminance(lFg, lBg);
+}
+
+// Worst cluster ratio on one frame; 0 when the frame sampled no clusters.
+function frameWorstRatio(f: FrameStat): number {
+  let worst = Infinity;
+  for (const cl of f.clusters) {
+    const ratio = frameClusterRatio(f.fg, cl.color);
+    if (ratio < worst) worst = ratio;
+  }
+  return f.clusters.length === 0 ? 0 : worst;
+}
+
+// Per-element verdict: every sampled peak frame must clear its OWN per-frame
+// threshold (frame fg + frame font metrics), and any unsampled peak frame fails
+// the run outright (its background is unknown).
+function verdictFor(elt: ElementStat, minRatio: number | null): ElementVerdict {
+  const sampled = elt.frames.filter((f) => !f.unsampled);
+  const anyUnsampled = elt.frames.some((f) => f.unsampled) || (elt.unsampled_frames?.n ?? 0) > 0;
+  if (elt.indeterminate || sampled.length === 0) {
+    return { id: elt.id, aa: false, aaa: false, indeterminate: elt.indeterminate, worstFrameRatio: 0 };
+  }
+  let worst = Infinity;
+  let aa = !anyUnsampled;
+  let aaa = !anyUnsampled;
+  for (const f of sampled) {
+    const w = frameWorstRatio(f);
+    if (w < effectiveThreshold("AA", f.font_size, f.font_weight, minRatio)) aa = false;
+    if (w < effectiveThreshold("AAA", f.font_size, f.font_weight, minRatio)) aaa = false;
+    if (w < worst) worst = w;
+  }
+  return { id: elt.id, aa, aaa, indeterminate: elt.indeterminate, worstFrameRatio: worst === Infinity ? 0 : worst };
+}
+
+// THE entry point: uncredited verdicts for every element, straight from the
+// statistics. `minRatio` mirrors the analyzer's --min-ratio (null = level
+// thresholds only, the default).
+export function resolveVerdicts(statistics: Statistics, minRatio: number | null = null): VerdictResult {
+  const elements = statistics.elements.map((e) => verdictFor(e, minRatio));
+  return {
+    elements,
+    failingAA: elements.filter((e) => !e.aa).length,
+    failingAAA: elements.filter((e) => !e.aaa).length,
+    indeterminateCount: elements.filter((e) => e.indeterminate).length,
+  };
+}
diff --git a/pipeline/scripts/wcag/wcag-choice.ts b/pipeline/scripts/wcag/wcag-choice.ts
new file mode 100644
index 0000000..1dc75f8
--- /dev/null
+++ b/pipeline/scripts/wcag/wcag-choice.ts
@@ -0,0 +1,118 @@
+// wcag-choice.json — the PINNED contract for user-chosen remediations, shared by
+// the studio page (emits entries), the preview server (validates + persists), and
+// the applier (reads + applies). One record per run at runs/<key>/final/.
+//
+// USER DECISION: a clicked choice ALWAYS takes effect — the click is the human
+// approval, so a chosen option is applied even when it is not a colours-only
+// recolor (halo / background). Colours-only stays the applier's DEFAULT (the
+// report path with no --choice); the click is what unlocks halo/background.
+//
+//   { "schema": 1, "chosen": [ { level, group, kind, hex, backingHex?, selector? } ] }
+//
+// Dedup key is `group` (corpus | outliers): last click on a group replaces its
+// entry, so there are at most two chosen entries.
+
+export type ChoiceLevel = "AA" | "AAA";
+export type ChoiceGroup = "corpus" | "outliers";
+export type ChoiceKind = "colour" | "shadow" | "outline" | "background";
+
+export interface ChoiceEntry {
+  level: ChoiceLevel;
+  group: ChoiceGroup;
+  kind: ChoiceKind;
+  /** Text colour (colour recolor / halo colour / background text anchor). #rrggbb. */
+  hex: string;
+  /** Solid plate colour — REQUIRED for kind "background". #rrggbb. */
+  backingHex?: string;
+  /** CSS selector(s) the choice applies to (corpus class key, or the outlier id
+   * list as a comma-joined selector). Carried so the applier needs no re-derivation. */
+  selector?: string;
+  /** Per-selector split for a HETEROGENEOUS group (outlier halo/background, where
+   * each element's fg solves to its OWN halo/anchor colour). When present the
+   * applier emits one rule per split part instead of a single rule for `selector`.
+   * `hex` = the applied text colour (halo colour, or the background text anchor);
+   * `backingHex` = the plate colour (background only). */
+  split?: { selector: string; hex: string; backingHex?: string }[];
+  /** The solved SHADOW recipe (kind "shadow" only): the applier emits `layers`
+   * stacked `0 0 {blur}px` shadows of `hex` at the shadow alpha. */
+  recipe?: { layers: number; blur: number };
+}
+
+export interface ChoiceFile {
+  schema: 1;
+  chosen: ChoiceEntry[];
+}
+
+// SSOT fallback recipe for a shadow choice that carries no `recipe` (an older or
+// hand-written entry). Consumers (applier, credited resolver, studio specimens)
+// import this — never hard-code the pair — so the emitted CSS, the credited
+// rating, and the preview can never drift apart.
+export const DEFAULT_SHADOW_RECIPE: { layers: number; blur: number } = { layers: 3, blur: 8 };
+
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const LEVELS: readonly string[] = ["AA", "AAA"];
+const GROUPS: readonly string[] = ["corpus", "outliers"];
+const KINDS: readonly string[] = ["colour", "shadow", "outline", "background"];
+
+// Validate ONE entry against the contract. Returns an error string (loud, names
+// the offending field) or null when valid. Rejects unknown level/group/kind and
+// malformed hex; a background choice must carry a valid backingHex.
+export function validateChoiceEntry(x: unknown): string | null {
+  if (typeof x !== "object" || x === null) return "entry must be an object";
+  const e = x as Record<string, unknown>;
+  if (!LEVELS.includes(e.level as string)) return `invalid level ${JSON.stringify(e.level)} (AA|AAA)`;
+  if (!GROUPS.includes(e.group as string)) return `invalid group ${JSON.stringify(e.group)} (corpus|outliers)`;
+  if (!KINDS.includes(e.kind as string)) return `invalid kind ${JSON.stringify(e.kind)} (colour|shadow|outline|background)`;
+  if (typeof e.hex !== "string" || !HEX.test(e.hex)) return `invalid hex ${JSON.stringify(e.hex)} (#rrggbb)`;
+  if (e.kind === "background") {
+    if (typeof e.backingHex !== "string" || !HEX.test(e.backingHex)) {
+      return `background choice requires backingHex (#rrggbb), got ${JSON.stringify(e.backingHex)}`;
+    }
+  } else if (e.backingHex !== undefined && (typeof e.backingHex !== "string" || !HEX.test(e.backingHex))) {
+    return `invalid backingHex ${JSON.stringify(e.backingHex)} (#rrggbb)`;
+  }
+  if (e.selector !== undefined && typeof e.selector !== "string") return "selector must be a string";
+  if (e.split !== undefined) {
+    if (!Array.isArray(e.split) || e.split.length === 0) return "split must be a non-empty array";
+    for (let i = 0; i < e.split.length; i++) {
+      const p = e.split[i] as Record<string, unknown>;
+      if (typeof p !== "object" || p === null) return `split[${i}] must be an object`;
+      if (typeof p.selector !== "string" || p.selector.length === 0) return `split[${i}] needs a selector`;
+      if (typeof p.hex !== "string" || !HEX.test(p.hex)) return `split[${i}] invalid hex ${JSON.stringify(p.hex)}`;
+      if (e.kind === "background") {
+        if (typeof p.backingHex !== "string" || !HEX.test(p.backingHex)) return `split[${i}] background needs backingHex`;
+      } else if (p.backingHex !== undefined && (typeof p.backingHex !== "string" || !HEX.test(p.backingHex))) {
+        return `split[${i}] invalid backingHex`;
+      }
+    }
+  }
+  if (e.recipe !== undefined) {
+    const rc = e.recipe as Record<string, unknown>;
+    if (typeof rc !== "object" || rc === null) return "recipe must be an object";
+    if (!Number.isInteger(rc.layers) || (rc.layers as number) < 1) return `recipe.layers must be a positive integer, got ${JSON.stringify(rc.layers)}`;
+    if (typeof rc.blur !== "number" || !(rc.blur as number > 0)) return `recipe.blur must be a positive number, got ${JSON.stringify(rc.blur)}`;
+  }
+  return null;
+}
+
+export const emptyChoiceFile = (): ChoiceFile => ({ schema: 1, chosen: [] });
+
+// Read-modify-write ONE entry, last-write-wins per group (drops any prior entry
+// for the same group, then appends). Pure — the server does the IO around it.
+export function upsertChoice(file: ChoiceFile, entry: ChoiceEntry): ChoiceFile {
+  return { schema: 1, chosen: [...file.chosen.filter((c) => c.group !== entry.group), entry] };
+}
+
+// Parse + fully validate a whole choice file (the applier's entry point). Throws
+// loudly on any schema/shape violation.
+export function parseChoiceFile(raw: unknown): ChoiceFile {
+  if (typeof raw !== "object" || raw === null) throw new Error("wcag-choice: not a JSON object");
+  const f = raw as Record<string, unknown>;
+  if (f.schema !== 1) throw new Error(`wcag-choice: unsupported schema ${JSON.stringify(f.schema)} (expected 1)`);
+  if (!Array.isArray(f.chosen)) throw new Error("wcag-choice: 'chosen' must be an array");
+  f.chosen.forEach((e, i) => {
+    const err = validateChoiceEntry(e);
+    if (err) throw new Error(`wcag-choice: chosen[${i}] ${err}`);
+  });
+  return { schema: 1, chosen: f.chosen as ChoiceEntry[] };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6a60004..3e5aabb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -7,7 +7,14 @@ settings:
 importers:
 
   .:
+    dependencies:
+      culori:
+        specifier: ^4.0.2
+        version: 4.0.2
     devDependencies:
+      '@types/culori':
+        specifier: ^4.0.1
+        version: 4.0.1
       '@types/node':
         specifier: ^22.0.0
         version: 22.20.0
@@ -176,6 +183,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@types/culori@4.0.1':
+    resolution: {integrity: sha512-43M51r/22CjhbOXyGT361GZ9vncSVQ39u62x5eJdBQFviI8zWp2X5jzqg7k4M6PVgDQAClpy2bUe2dtwEgEDVQ==}
+
   '@types/node@22.20.0':
     resolution: {integrity: sha512-QWlFW2wf3nTjC13/DqRnBpR4ZO36VJH/JVBkA/vcnmbTBNQIlnObqyqZE1tUR7+Ni23Lda8R1BxMfbXRpCUx5g==}
 
@@ -299,6 +309,10 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  culori@4.0.2:
+    resolution: {integrity: sha512-1+BhOB8ahCn4O0cep0Sh2l9KCOfOdY+BXJnKMHFFzDEouSr/el18QwXEMRlOj9UY5nCeA8UN3a/82rUWRBeyBw==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   esbuild@0.27.7:
     resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
     engines: {node: '>=18'}
@@ -408,6 +422,8 @@ snapshots:
   '@esbuild/win32-x64@0.27.7':
     optional: true
 
+  '@types/culori@4.0.1': {}
+
   '@types/node@22.20.0':
     dependencies:
       undici-types: 6.21.0
@@ -472,6 +488,8 @@ snapshots:
   '@typescript/typescript-win32-x64@7.0.2':
     optional: true
 
+  culori@4.0.2: {}
+
   esbuild@0.27.7:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.27.7
diff --git a/preview/page/app.js b/preview/page/app.js
index 7ec3fe7..003b606 100644
--- a/preview/page/app.js
+++ b/preview/page/app.js
@@ -2,7 +2,7 @@
 // sync · timeline · player · transport + keyboard · plumbing/boot. The preview is read-only
 // in V1: watch the footage while the style cooks, follow the transcript, grab the render.
 // Pure logic lives in helpers.mjs (tested from node); everything here touches the DOM.
-import { chunkIndexAtTime, cueBlockGeometry, fitWidth, focalFraction, nextCueTime, prevCueTime, refocusScrollDelta } from './helpers.mjs';
+import { chunkIndexAtTime, cueBlockGeometry, fitWidth, focalFraction, nextCueTime, prevCueTime, rearmDecoder, refocusScrollDelta } from './helpers.mjs';
 
 // ---- elements + state ----
 const $ = (id) => document.getElementById(id);
@@ -406,6 +406,10 @@ document.addEventListener('keydown', (e) => {
   if (e.key === 'ArrowDown') { e.preventDefault(); gotoNextCue(); }
 });
 
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') rearmDecoder(player);
+});
+
 // ---- state plumbing + boot ----
 let lastRendered = ''; // duplicate SSE frames are no-ops; skip them
 
diff --git a/preview/page/helpers.d.mts b/preview/page/helpers.d.mts
index 932037e..abe2d35 100644
--- a/preview/page/helpers.d.mts
+++ b/preview/page/helpers.d.mts
@@ -22,6 +22,7 @@ export function refocusScrollDelta(
   canvasSize: number,
   fraction: number,
 ): number;
+export function rearmDecoder(video: HTMLVideoElement, userAgent?: string): boolean;
 export function cueBlockGeometry(
   chunk: CueChunk,
   durationSec: number | undefined,
diff --git a/preview/page/helpers.mjs b/preview/page/helpers.mjs
index dece1b0..a6ee7bc 100644
--- a/preview/page/helpers.mjs
+++ b/preview/page/helpers.mjs
@@ -44,6 +44,25 @@ export function refocusScrollDelta(viewportCentre, canvasStart, canvasSize, frac
   return canvasStart + fraction * canvasSize - viewportCentre;
 }
 
+// Safari can suspend a paused media decoder when the page is backgrounded. Reloading the
+// media resource re-arms it, which makes subsequent paused seeks paint the requested frame.
+// Do not do this in Chromium/Firefox: reloading a video is disruptive and their decoders do
+// not need the workaround.
+export function rearmDecoder(video, userAgent = globalThis.navigator?.userAgent ?? '') {
+  if (!/Safari/i.test(userAgent) || /Chrome|Chromium|CriOS|FxiOS|EdgiOS|OPiOS|Android/i.test(userAgent)) {
+    return false;
+  }
+  const currentTime = video.currentTime;
+  const restoreTime = () => {
+    if (Number.isFinite(currentTime)) {
+      video.currentTime = Math.min(currentTime, video.duration || currentTime);
+    }
+  };
+  video.addEventListener('loadedmetadata', restoreTime, { once: true });
+  video.load();
+  return true;
+}
+
 // Position of one cue's block on the timeline track, as percentages of the run duration.
 export function cueBlockGeometry(chunk, durationSec) {
   if (!durationSec || durationSec <= 0) return null;
diff --git a/preview/page/style.css b/preview/page/style.css
index 5e81c9b..126cdcb 100644
--- a/preview/page/style.css
+++ b/preview/page/style.css
@@ -5,37 +5,7 @@
  * app frame: full-bleed, panels meet at hairlines, transport docked. Fonts mirror the
  * product: Inter from Google Fonts exactly like apps/frontend/index.html, SwissNow from
  * VEED's own CDN; display swap keeps the offline system fallback. */
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap"); /* only the weights this page uses */
-:root {
-  --sunken: #f5f5f4;   /* background-sunken · stone-100 */
-  --base: #fafaf9;     /* background-base · stone-50 */
-  --raised: #ffffff;   /* background-raised · white */
-  --border: #d6d3d1;   /* border-default · stone-300 */
-  --border-subtle: #e7e5e4; /* border-subtle · stone-200 */
-  --ink: #0c0a09;      /* text-default · stone-950 */
-  --sub: #79716b;      /* text-subtle · stone-500 */
-  --xsub: #a6a09b;     /* stone-400 (their x-subtle is too faint for UI text) */
-  --lime-text: #5ea500;   /* text-brand · lime-600 */
-  --lime-soft: rgba(154, 230, 0, 0.18); /* lime-400 wash */
-  --violet: #8b5cf6;      /* the editor's subtitle-lane hue (timeline blocks) */
-  --violet-mid: #a78bfa;
-  --violet-fill: #ede9fe;
-  --shadow: 0 1px 2px rgba(12, 10, 9, 0.05), 0 2px 8px rgba(12, 10, 9, 0.05);
-  --sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; /* --font-body */
-  --heading: "SwissNow", "Inter", -apple-system, sans-serif;                  /* --font-heading */
-}
-/* Brand faces from VEED's public CDN, same files the editor loads (shared-ui fonts.css).
- * font-display: swap → offline just falls back to the system stack. */
-@font-face {
-  font-family: "SwissNow";
-  src: url("https://static-assets.veed.io/fonts/SwissNow/SwissNow-Regular.woff2") format("woff2");
-  font-style: normal; font-weight: 400; font-display: swap;
-}
-@font-face {
-  font-family: "SwissNow";
-  src: url("https://static-assets.veed.io/fonts/SwissNow/SwissNow-Medium.woff2") format("woff2");
-  font-style: normal; font-weight: 500; font-display: swap;
-}
+@import url("tokens.css"); /* shared VEED design tokens (SSOT) — extracted from here, see tokens.css + internal/doc/PAGES.md */
 * { box-sizing: border-box; }
 [hidden] { display: none !important; } /* author display rules must never defeat the hidden attribute */
 .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
diff --git a/preview/page/tokens.css b/preview/page/tokens.css
new file mode 100644
index 0000000..665480f
--- /dev/null
+++ b/preview/page/tokens.css
@@ -0,0 +1,35 @@
+/* VEED page design tokens — SINGLE SOURCE OF TRUTH for every user-facing HTML page this repo
+ * generates (the preview page, the WCAG recommendation studio, future reports). Extracted
+ * verbatim from preview/page/style.css; values follow the Brand Guidelines 2026 ramps. Any
+ * generated page must inline or link THIS file — never reinvent tokens. See internal/doc/PAGES.md. */
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap"); /* only the weights this page uses */
+:root {
+  --sunken: #f5f5f4;   /* background-sunken · stone-100 */
+  --base: #fafaf9;     /* background-base · stone-50 */
+  --raised: #ffffff;   /* background-raised · white */
+  --border: #d6d3d1;   /* border-default · stone-300 */
+  --border-subtle: #e7e5e4; /* border-subtle · stone-200 */
+  --ink: #0c0a09;      /* text-default · stone-950 */
+  --sub: #79716b;      /* text-subtle · stone-500 */
+  --xsub: #a6a09b;     /* stone-400 (their x-subtle is too faint for UI text) */
+  --lime-text: #5ea500;   /* text-brand · lime-600 */
+  --lime-soft: rgba(154, 230, 0, 0.18); /* lime-400 wash */
+  --violet: #8b5cf6;      /* the editor's subtitle-lane hue (timeline blocks) */
+  --violet-mid: #a78bfa;
+  --violet-fill: #ede9fe;
+  --shadow: 0 1px 2px rgba(12, 10, 9, 0.05), 0 2px 8px rgba(12, 10, 9, 0.05);
+  --sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; /* --font-body */
+  --heading: "SwissNow", "Inter", -apple-system, sans-serif;                  /* --font-heading */
+}
+/* Brand faces from VEED's public CDN, same files the editor loads (shared-ui fonts.css).
+ * font-display: swap → offline just falls back to the system stack. */
+@font-face {
+  font-family: "SwissNow";
+  src: url("https://static-assets.veed.io/fonts/SwissNow/SwissNow-Regular.woff2") format("woff2");
+  font-style: normal; font-weight: 400; font-display: swap;
+}
+@font-face {
+  font-family: "SwissNow";
+  src: url("https://static-assets.veed.io/fonts/SwissNow/SwissNow-Medium.woff2") format("woff2");
+  font-style: normal; font-weight: 500; font-display: swap;
+}
diff --git a/preview/server.ts b/preview/server.ts
index e2d8a83..2a722a0 100644
--- a/preview/server.ts
+++ b/preview/server.ts
@@ -4,9 +4,9 @@
 //   node --import tsx preview/server.ts runs/<key>
 // Env: VEED_PREVIEW_PORT (default 8978; falls back to an ephemeral port if busy),
 //      VEED_PREVIEW_NO_OPEN=1 (print the URL, don't open the browser).
-import { createServer, type Server, type ServerResponse } from 'node:http';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { createReadStream } from 'node:fs';
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, stat, writeFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { basename, dirname, join } from 'node:path';
 import { pipeline } from 'node:stream';
@@ -14,6 +14,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { readRunState } from './state.ts';
 import { planRange } from './media.ts';
 import { makeHub, makeRunDirWatcher, type Hub } from './events.ts';
+import {
+  emptyChoiceFile,
+  parseChoiceFile,
+  upsertChoice,
+  validateChoiceEntry,
+  type ChoiceFile,
+} from '../pipeline/scripts/wcag/wcag-choice.ts';
 
 const PAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'page');
 const PAGE_ASSETS: Record<string, { file: string; type: string }> = {
@@ -21,6 +28,7 @@ const PAGE_ASSETS: Record<string, { file: string; type: string }> = {
   '/app.js': { file: 'app.js', type: 'text/javascript; charset=utf-8' },
   '/helpers.mjs': { file: 'helpers.mjs', type: 'text/javascript; charset=utf-8' },
   '/style.css': { file: 'style.css', type: 'text/css; charset=utf-8' },
+  '/tokens.css': { file: 'tokens.css', type: 'text/css; charset=utf-8' }, // style.css @imports the shared token SSOT
 };
 
 function boundPort(server: Server): number {
@@ -57,6 +65,23 @@ async function streamMedia(res: ServerResponse, path: string, rangeHeader: strin
   pipeline(createReadStream(path, { start: plan.start, end: plan.end }), res, () => {});
 }
 
+// Collect a small request body (the choice POST). Caps at 64 KiB — a choice
+// entry is tiny; anything larger is a malformed/abusive request.
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (chunk) => {
+      data += chunk;
+      if (data.length > 65536) {
+        reject(new Error('request body too large'));
+        req.destroy();
+      }
+    });
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}
+
 export async function createPreviewServer(
   runDir: string,
   opts: { port?: number; openBrowser?: boolean } = {},
@@ -110,6 +135,58 @@ export async function createPreviewServer(
         await streamMedia(res, join(runDir, 'final', 'out.mp4'), req.headers.range);
         return;
       }
+      // ---- WCAG recommendation studio (pre-decision picker) ----------------
+      // Canonical URL is /wcag/ — the page's relative asset URLs (the video)
+      // resolve against the trailing slash; at /wcag they'd hit the root.
+      if (req.method === 'GET' && path === '/wcag') {
+        res.writeHead(301, { location: '/wcag/' });
+        res.end();
+        return;
+      }
+      if (req.method === 'GET' && (path === '/wcag/' || path === '/wcag/variants')) {
+        const file = path === '/wcag/variants' ? 'wcag-design-variants.html' : 'wcag-recommendations.html';
+        try {
+          const body = await readFile(join(runDir, 'final', file));
+          res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-length': body.length, 'cache-control': 'no-store' });
+          res.end(body);
+        } catch {
+          json(res, 404, { error: 'no recommendations yet — run pipeline/scripts/wcag/recommend.ts first' });
+        }
+        return;
+      }
+      if (req.method === 'POST' && path === '/wcag/choice') {
+        let entry: unknown;
+        try {
+          entry = JSON.parse(await readBody(req));
+        } catch {
+          json(res, 400, { error: 'invalid JSON body' });
+          return;
+        }
+        const err = validateChoiceEntry(entry);
+        if (err) {
+          json(res, 400, { error: err }); // reject unknown kinds / malformed hex loudly
+          return;
+        }
+        // Read-modify-write, last-write-wins per group. A malformed existing file
+        // is replaced (the server owns this file); a valid one is preserved.
+        const choicePath = join(runDir, 'final', 'wcag-choice.json');
+        let file: ChoiceFile = emptyChoiceFile();
+        try {
+          file = parseChoiceFile(JSON.parse(await readFile(choicePath, 'utf8')));
+        } catch { /* missing or corrupt -> start fresh */ }
+        const next = upsertChoice(file, entry as Parameters<typeof upsertChoice>[1]);
+        await writeFile(choicePath, JSON.stringify(next, null, 2) + '\n');
+        json(res, 200, next);
+        return;
+      }
+      // The page references its original render relatively (e.g. out.draft.silent.mp4).
+      if (req.method === 'GET' && path.startsWith('/wcag/')) {
+        const name = path.slice('/wcag/'.length);
+        if (/^[\w.-]+\.mp4$/.test(name)) {
+          await streamMedia(res, join(runDir, 'final', name), req.headers.range);
+          return;
+        }
+      }
       json(res, 404, { error: 'not found' });
     } catch (e) {
       json(res, 500, { error: e instanceof Error ? e.message : 'internal error' });
diff --git a/veed/allowances.ts b/veed/allowances.ts
new file mode 100644
index 0000000..40f2226
--- /dev/null
+++ b/veed/allowances.ts
@@ -0,0 +1,31 @@
+// What a workspace has left to spend.
+//
+// This is account-level, not feature-level: the same report answers "can this workspace afford it?" for
+// anything that bills, so it lives beside the workspace resolution rather than inside any one client.
+//
+// The workspace travels as a HEADER here rather than in the path, which is why VeedHttp.getJson takes
+// headers at all — a route that scopes itself out-of-band is the exception the transport has to allow.
+import { type VeedHttp, unwrap } from './api.ts';
+
+// The four buckets that make up an allowance. Reachable with a plain user token; the workspace
+// travels as a header rather than in the path.
+const BUCKETS = ['ALLOWANCE', 'FEATURE_BALANCE', 'OPEN_BALANCE', 'REVENUECAT_BALANCE'] as const;
+
+// A workspace holds TWO separate allowances, measured in different units, and a feature can draw on
+// either: TEXT_TO_SPEECH is billed in SECONDS, AI_PLAYGROUND_CREDITS in credits. They are never summed —
+// reporting one of them as "the balance" understates what a workspace can and cannot afford.
+export interface Allowances {
+  aiPlaygroundCredits: number;
+  textToSpeechSeconds: number;
+}
+
+export async function getAllowances(http: VeedHttp, workspaceId: string): Promise<Allowances> {
+  const report = await http.getJson<{ data?: Record<string, Record<string, { amount?: number }>> }>(
+    '/usage-events/report',
+    { workspaceId },
+  );
+  const data = unwrap<Record<string, Record<string, { amount?: number }>>>(report);
+  const sum = (meter: string): number =>
+    BUCKETS.reduce((total, bucket) => total + (data[bucket]?.[meter]?.amount ?? 0), 0);
+  return { aiPlaygroundCredits: sum('AI_PLAYGROUND_CREDITS'), textToSpeechSeconds: sum('TEXT_TO_SPEECH') };
+}
diff --git a/veed/api.ts b/veed/api.ts
index 3878532..f9ff241 100644
--- a/veed/api.ts
+++ b/veed/api.ts
@@ -8,7 +8,9 @@ export const VEED_ORIGIN = (process.env.VEED_ORIGIN ?? 'https://www.veed.io').re
 export const VEED_API_BASE = (process.env.VEED_API_BASE ?? `${VEED_ORIGIN}/api/v1`).replace(/\/$/, '');
 
 export interface VeedHttp {
-  getJson<T>(path: string): Promise<T>;
+  // `headers` is for the few routes that take their scope out-of-band: the usage report reads the
+  // workspace from a header rather than from the path or the body.
+  getJson<T>(path: string, headers?: Record<string, string>): Promise<T>;
   // Like getJson but resolves null on a 404, for routes where 404 is a state
   // (GET /asset/:id only serves UPLOADED assets), not an error.
   getJsonOrNull<T>(path: string): Promise<T | null>;
diff --git a/veed/go.ts b/veed/go.ts
index 167edcf..056e85b 100644
--- a/veed/go.ts
+++ b/veed/go.ts
@@ -47,14 +47,16 @@ async function main(): Promise<void> {
   // typo. Checked the other way round, a mistyped flag surfaces as "no VEED login found" on any machine
   // that happens not to be logged in, which sends someone off fixing the wrong thing.
   //
-  // Strict: this command takes a list of files, so a bare token is expected, but anything that looks
-  // like a flag is one and must be recognised. A mistyped flag used to be resolved as a path and then
-  // reported as a missing video, which names the wrong problem.
-  const { positionals: videoArgs } = parseFlags({
+  // Transcription BILLS a workspace, so it has to be nameable — without this an account with several
+  // could only ever use whichever one the listing put first. Strict, with the videos as positionals: a
+  // mistyped flag used to be resolved as a path and then reported as a missing video, which names the
+  // wrong problem.
+  const { values, positionals: videoArgs } = parseFlags({
     args: process.argv.slice(2),
-    options: {},
+    options: { workspace: { type: 'string' } },
     allowPositionals: true,
   });
+  const workspaceId = values.workspace;
   if (videoArgs.length === 0) {
     console.error('usage: node --import tsx veed/go.ts <video.mp4> [...]');
     process.exit(1);
@@ -88,7 +90,7 @@ async function main(): Promise<void> {
     console.log(`[veed-transcribe] ${video}`);
     const transcript = await transcribeWithVeed(
       { http, readVideoBytes, log: (m) => console.log(`  ${m}`) },
-      { videoPath: video },
+      { videoPath: video, workspaceId },
     );
     const out = join(outDir, 'transcript.json');
     await writeFile(out, JSON.stringify(transcript, null, 2));
diff --git a/veed/http.ts b/veed/http.ts
index 3adc627..90d9f35 100644
--- a/veed/http.ts
+++ b/veed/http.ts
@@ -11,9 +11,9 @@ export function realHttp(token: string): VeedHttp {
   // seeds the GCS resumable session); Node's fetch doesn't add one itself.
   const base = { authorization: `Bearer ${token}`, origin: VEED_ORIGIN };
   return {
-    async getJson<T>(path: string): Promise<T> {
+    async getJson<T>(path: string, headers?: Record<string, string>): Promise<T> {
       const res = await fetch(VEED_API_BASE + path, {
-        headers: { ...base, accept: 'application/json' },
+        headers: { ...base, accept: 'application/json', ...headers },
         signal: AbortSignal.timeout(JSON_TIMEOUT_MS),
       });
       if (!res.ok) throw new Error(`GET ${path} -> ${res.status} ${(await res.text().catch(() => '')).slice(0, 300)}`);
diff --git a/veed/orchestrate.ts b/veed/orchestrate.ts
index de39cf4..b752020 100644
--- a/veed/orchestrate.ts
+++ b/veed/orchestrate.ts
@@ -3,12 +3,12 @@
 // injected so the call sequence is testable offline (see orchestrate.test.ts). go.ts wires the real ones.
 import type { VeedHttp } from './api.ts';
 import {
-  listWorkspaces,
   createUploadableAsset,
   getAsset,
   startTranscription,
   getSubtitle,
 } from './api.ts';
+import { describeChoice, formatWorkspaceTable, resolveWorkspace } from './workspace.ts';
 import { mapVeedTranscript } from './transcript-mapper.ts';
 import type { Transcript } from './transcript-mapper.ts';
 
@@ -49,14 +49,27 @@ export async function transcribeWithVeed(deps: TranscribeDeps, opts: TranscribeO
     throw new Error(`VEED: ${label} did not finish after ${maxAttempts} polls (${pollIntervalMs}ms each)`);
   }
 
-  // 1. resolve a workspace (the asset + transcription need a real owner)
+  // 1. resolve a workspace (the asset + transcription need a real owner, and transcription BILLS it).
+  // This used to take workspaces[0] silently, which meant an account with several was charged wherever
+  // the listing happened to order first. The shared resolver picks only when there is nothing to pick,
+  // and says which either way — see veed/workspace.ts.
   let workspaceId = opts.workspaceId;
   if (!workspaceId) {
-    const workspaces = await listWorkspaces(http);
-    if (workspaces.length === 0) throw new Error('VEED: account has no workspace to own the asset');
-    workspaceId = workspaces[0].id;
+    const resolution = await resolveWorkspace({ http });
+    if (resolution.kind === 'must-choose') {
+      throw new Error(
+        'VEED: this account has several workspaces and transcription bills one of them, so it will not be ' +
+        `picked for you. Re-run naming it, for example --workspace ${resolution.workspaces[0].id}:\n` +
+        `${formatWorkspaceTable(resolution.workspaces)}`,
+      );
+    }
+    workspaceId = resolution.workspace.id;
+    log(describeChoice(resolution.workspace, resolution.source));
+  } else {
+    log(`workspace ${workspaceId}`);
   }
-  log(`workspace ${workspaceId}`);
+
+  const billedWorkspaceId: string = workspaceId;
 
   // 2. mint a signed upload URL, then PUT the bytes to GCS. The upload is UNSCOPED: the asset is
   // owned by its creator, and no project is involved anywhere in this flow. The transcribe route
@@ -88,7 +101,7 @@ export async function transcribeWithVeed(deps: TranscribeDeps, opts: TranscribeO
   // 4. start transcription, billed to the workspace resolved above.
   const started = await startTranscription(http, {
     assetId: uploadable.asset.id,
-    workspaceId,
+    workspaceId: billedWorkspaceId,
     videoUrl: cdnUrl,
   });
   log(`transcription ${started.id} (${started.status})`);
diff --git a/veed/workspace.ts b/veed/workspace.ts
new file mode 100644
index 0000000..0ad5ba0
--- /dev/null
+++ b/veed/workspace.ts
@@ -0,0 +1,109 @@
+// Which VEED workspace a run bills, resolved in ONE place.
+//
+// A workspace is an account-level billing decision, and more than one thing spends against it:
+// transcription draws VEED credits today, and anything else that bills will draw its own. So the question
+// is answered here, once, rather than by each caller in its own way — transcription used to silently take
+// the first workspace the listing returned, which is exactly how a user ends up billed somewhere they
+// never named.
+//
+// The rule: an explicit choice wins; otherwise, if the account holds exactly ONE workspace there is
+// nothing to decide, so take it and SAY which — informing is not the same as choosing for someone. Only a
+// genuine ambiguity, several workspaces and no answer, is a question.
+import { type VeedHttp, listWorkspaces } from './api.ts';
+import { getAllowances } from './allowances.ts';
+
+export interface WorkspaceCredits {
+  id: string;
+  name: string;
+  // null when the allowance call failed. A workspace nobody could price is still one the user may own and
+  // may want to spend from, so it is shown rather than hidden — and an unreadable balance is never read as
+  // an empty one.
+  credits: number | null;
+  ttsSeconds: number | null;
+}
+
+export type WorkspaceSource = 'flag' | 'only-one';
+
+export type Resolution =
+  | { kind: 'resolved'; workspace: WorkspaceCredits; source: WorkspaceSource }
+  // Several to choose between and nobody has chosen: the caller asks, this never guesses.
+  | { kind: 'must-choose'; workspaces: WorkspaceCredits[] };
+
+// Every workspace with both allowances, for the one case that needs the comparison: asking the user to
+// choose. Balances are best-effort — an unreadable one is shown as unknown, never as zero, and never
+// blocks a run, because it is not evidence of an empty workspace.
+export async function listWorkspacesWithCredits(http: VeedHttp): Promise<WorkspaceCredits[]> {
+  const workspaces = await listWorkspaces(http);
+  if (workspaces.length === 0) throw new Error('no VEED workspaces on this account — nothing can be billed');
+  return Promise.all(workspaces.map((w) => priced(http, w.id, w.name ?? w.id)));
+}
+
+async function priced(http: VeedHttp, id: string, name: string): Promise<WorkspaceCredits> {
+  try {
+    const a = await getAllowances(http, id);
+    return { id, name, credits: a.aiPlaygroundCredits, ttsSeconds: a.textToSpeechSeconds };
+  } catch {
+    return { id, name, credits: null, ttsSeconds: null };
+  }
+}
+
+export async function resolveWorkspace(opts: {
+  http: VeedHttp;
+  // Named on the command line; wins over everything, and is not second-guessed against the listing.
+  explicit?: string;
+}): Promise<Resolution> {
+  const named = opts.explicit;
+  const source: WorkspaceSource = 'flag';
+  const workspaces = await listWorkspaces(opts.http);
+  if (workspaces.length === 0) throw new Error('no VEED workspaces on this account — nothing can be billed');
+
+  // Price only what the answer depends on. A named workspace needs ONE balance; an account with several
+  // and no answer needs all of them, because that is the comparison the user is being asked to make.
+  if (named) {
+    // An id the caller named is taken as given even if the listing does not show it: the listing can fail
+    // partially, and refusing a workspace the user explicitly asked for would be a worse error than
+    // letting the first scoped call report the server's own message.
+    const name = workspaces.find((w) => w.id === named)?.name ?? named;
+    return { kind: 'resolved', workspace: await priced(opts.http, named, name), source };
+  }
+  if (workspaces.length === 1) {
+    const only = workspaces[0];
+    return { kind: 'resolved', workspace: await priced(opts.http, only.id, only.name ?? only.id), source: 'only-one' };
+  }
+  return { kind: 'must-choose', workspaces: await Promise.all(workspaces.map((w) => priced(opts.http, w.id, w.name ?? w.id))) };
+}
+
+// True when not one balance could be read — usually an expired login rather than empty workspaces. Worth
+// saying only where the user is being asked to choose between them on price.
+export function allUnpriced(workspaces: WorkspaceCredits[]): boolean {
+  return workspaces.length > 0 && workspaces.every((w) => w.credits === null);
+}
+
+// What the user reads before naming the workspace they want billed. Both allowances, because a run can be
+// stopped by either of them.
+export function formatWorkspaceTable(workspaces: WorkspaceCredits[]): string {
+  const w = (pick: (x: WorkspaceCredits) => string, min: number): number =>
+    Math.max(min, ...workspaces.map((x) => pick(x).length));
+  const credits = (x: WorkspaceCredits): string => (x.credits === null ? 'unknown' : String(x.credits));
+  const tts = (x: WorkspaceCredits): string => (x.ttsSeconds === null ? 'unknown' : `${x.ttsSeconds}s`);
+  const idW = w((x) => x.id, 2);
+  const nameW = w((x) => x.name, 4);
+  const creditW = w(credits, 7);
+  const row = (a: string, b: string, c: string, d: string): string =>
+    `  ${a.padEnd(idW)}  ${b.padEnd(nameW)}  ${c.padStart(creditW)}  ${d}`;
+  return [
+    row('ID', 'NAME', 'CREDITS', 'TEXT-TO-SPEECH'),
+    ...workspaces.map((x) => row(x.id, x.name, credits(x), tts(x))),
+  ].join('\n');
+}
+
+// The one-liner a run prints once it knows whose credits it is about to use. Says which workspace, what it
+// holds, and — when nobody chose it — why it did not ask.
+export function describeChoice(workspace: WorkspaceCredits, source: WorkspaceSource): string {
+  const held = workspace.credits === null
+    ? 'balance unavailable'
+    : `${workspace.credits} AI Playground credits` +
+      (workspace.ttsSeconds === null ? '' : `, ${workspace.ttsSeconds}s text-to-speech`);
+  const why = source === 'only-one' ? ' — the only workspace on this account, so nothing was asked' : '';
+  return `billing workspace ${workspace.name} (${workspace.id}) — ${held}${why}`;
+}