Bureaucat — Build Small Hackathon submission (Qwen3-VL-8B, ZeroGPU, gr.Server)

.git-hooks/pre-commit

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Pre-commit hook: block staging of text files containing Swedish personnummer patterns.
+# Installed via: git config core.hooksPath .git-hooks
+#
+# WHAT IT SCANS: text files with these extensions staged for commit:
+#   .py .txt .md .json .csv .yaml .yml .toml .sh
+#
+# WHAT IT DOES NOT SCAN: image files (PNG, JPG, etc.).
+#   Image redaction is a MANUAL VISUAL gate — verify PNG/JPG files by eye before committing.
+#
+# Pattern covers:
+#   10-digit: YYMMDD-XXXX (e.g., 901215-1234)
+#   12-digit: YYYYMMDD-XXXX (e.g., 19901215-1234)
+#   Plus-separator (100+ years): YYMMDD+XXXX
+#   Samordningsnummer: same formats; day-part 61-91 is not distinguished (any match blocked)
+
+set -euo pipefail
+
+# Patterns (regex alternation):
+#   [0-9]{6}[+-][0-9]{4}  — 10-digit form with hyphen or plus
+#   [0-9]{8}-[0-9]{4}     — 12-digit full-year form with hyphen
+PATTERN='[0-9]{6}[+-][0-9]{4}|[0-9]{8}-[0-9]{4}'
+
+# Get staged text files (added, copied, modified, renamed — not deleted)
+staged_files=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null | \
+  grep -E '\.(py|txt|md|json|csv|yaml|yml|toml|sh)$' || true)
+
+if [ -z "$staged_files" ]; then
+  exit 0
+fi
+
+# Determine scan backend: prefer grep -P (PCRE); fall back to python3 if unavailable.
+# macOS BSD grep may not support -P; the fallback ensures portability.
+#
+# The probe MUST actually exercise a digit-dash-digit match, or it silently
+# always-fails and never selects grep. We build the probe digits at runtime via
+# printf so this hook file never contains a literal personnummer (which would
+# otherwise self-trip the hook when the hook itself is committed).
+_grep_supports_P() {
+  local six="123456" four="7890"
+  printf '%s-%s\n' "$six" "$four" | grep -qP '[0-9]{6}-[0-9]{4}' 2>/dev/null
+}
+
+# Scan convention (MUST match _scan_file_python): exit 0 = CLEAN (no PII),
+# exit non-zero = PII FOUND. `grep -qP` exits 0 when it FINDS a match, so it is
+# negated here to align the two backends — otherwise the loop guard below would
+# be inverted for the grep path (the CR-01 bug).
+_scan_file_grep() {
+  local f="$1"
+  ! grep -qP "$PATTERN" "$f" 2>/dev/null
+}
+
+_scan_file_python() {
+  local f="$1"
+  python3 - "$f" <<'PYEOF'
+import re, sys
+pattern = re.compile(r'[0-9]{6}[+-][0-9]{4}|[0-9]{8}-[0-9]{4}')
+with open(sys.argv[1], errors='replace') as fh:
+    sys.exit(0 if not pattern.search(fh.read()) else 1)
+PYEOF
+}
+
+_get_matches_grep() {
+  local f="$1"
+  grep -nP "$PATTERN" "$f" 2>/dev/null | head -3 || true
+}
+
+_get_matches_python() {
+  local f="$1"
+  python3 - "$f" <<'PYEOF'
+import re, sys
+pattern = re.compile(r'[0-9]{6}[+-][0-9]{4}|[0-9]{8}-[0-9]{4}')
+with open(sys.argv[1], errors='replace') as fh:
+    for i, line in enumerate(fh, 1):
+        if pattern.search(line):
+            print(f"{i}:{line.rstrip()}")
+PYEOF
+}
+
+# Select backend once
+if _grep_supports_P; then
+  SCAN_CMD=_scan_file_grep
+  MATCH_CMD=_get_matches_grep
+else
+  SCAN_CMD=_scan_file_python
+  MATCH_CMD=_get_matches_python
+fi
+
+found=0
+while IFS= read -r file; do
+  if [ -f "$file" ] && ! $SCAN_CMD "$file"; then
+    echo "ERROR: Possible personnummer found in: $file"
+    $MATCH_CMD "$file"
+    found=1
+  fi
+done <<< "$staged_files"
+
+if [ "$found" -eq 1 ]; then
+  echo ""
+  echo "COMMIT BLOCKED: Remove or redact personnummer patterns before committing."
+  echo "Pattern matched: YYMMDD-XXXX, YYYYMMDD-XXXX, or YYMMDD+XXXX"
+  echo ""
+  echo "NOTE: Image files (PNG/JPG) are NOT scanned — verify PNG/JPG redaction visually."
+  echo "      Real letters must live in data/letters/private/ (gitignored), never in public/."
+  exit 1
+fi
+
+exit 0

.gitattributes

@@ -0,0 +1,40 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Audio / video demo assets (kept out of the runtime, but LFS if ever added)
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.mov filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+data/letters/private/
+*.token
+.claude/
+.DS_Store
+**/.DS_Store
+# Scratch/working notes never meant for the public Space
+data/letters/public/sample-invoice-ocr.png

README.md

@@ -0,0 +1,91 @@
+---
+title: Bureaucat
+emoji: 🐱
+colorFrom: pink
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.16.0
+python_version: "3.12"
+app_file: app.py
+pinned: false
+license: apache-2.0
+short_description: The cat that reads scary Swedish letters for you
+tags:
+  - track:backyard
+  - achievement:offgrid
+  - achievement:offbrand
+  - achievement:fieldnotes
+  - build-small-hackathon
+  - backyard-ai
+  - off-the-grid
+  - off-brand
+  - field-notes
+  - zerogpu
+  - vision-language-model
+  - sweden
+models:
+  - Qwen/Qwen3-VL-8B-Instruct
+---
+
+**🔗 Submission:** [Demo video & launch post on LinkedIn](https://www.linkedin.com/posts/ravinarayansingh_buildsmallhackathon-gradio-huggingface-ugcPost-7472036424997974017-l0HA/) — the demo video is embedded in this post.
+
+# 🐱 Bureaucat
+
+**The cat that reads scary Swedish letters so you don't have to.**
+
+You moved to Sweden. One day a thick envelope arrives from **Skatteverket**. Or **Försäkringskassan**. Or — heart rate rising — **Migrationsverket**. It's in formal bureaucratic Swedish, it mentions an amount and a date, and you have no idea if it means *"FYI, everything is fine"* or *"pay 15,600 kr in 30 days or lose your housing allowance."*
+
+Bureaucat reads the letter for you and tells you, at a glance and accurately:
+
+- **How worried to be** — a 1–5 severity verdict driving a **Panic Meter** and a reacting cat-civil-servant mascot
+- **The short version** — what the letter says, in plain English
+- **Why you got it** — which authority, and what triggered it
+- **What you need to do** — a checklist of required actions
+- **Deadlines & money** — every deadline, amount, and reference number **quoted verbatim from the letter, never invented**
+
+## 🏡 Backyard AI: built for a real person — me
+
+I'm an expat in Sweden. Every letter in the example gallery is a type of letter that has actually landed in my mailbox: tax decisions (slutskattebesked), benefit completion requests (komplettering), residence-permit document requests, CSN repayment demands, vårdcentral appointment summons. The first user test was me, on my own mail. The app is stateless by design — nothing is stored, nothing leaves the Space.
+
+## 🤏 Small model, honest fit
+
+One model does everything — OCR, reasoning, and explanation in a single pass:
+
+| | |
+|---|---|
+| Model | [`Qwen/Qwen3-VL-8B-Instruct`](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct) (~9B params — well under the 32B cap) |
+| Decoding | **Greedy** (`do_sample=False`) — deterministic output for an accuracy-critical tool |
+| Inference | Entirely in this Space on ZeroGPU. **No cloud APIs.** |
+
+The model was chosen by a bake-off, not vibes: Qwen2.5-VL-7B vs Qwen3-VL-8B on a gold set of five synthetic Swedish authority letters with an automated evaluation harness (`eval/run_eval.py`). The smaller 7B model dropped reference numbers (3/5 pass); the 8B passed 5/5 with **zero invented values and 100% recall** — so per "smallest model that passes," the 8B won.
+
+## 🛡️ The anti-hallucination contract
+
+Inventing a deadline is the single worst failure this app can have. So:
+
+1. The model first **transcribes** the letter, then extracts — every value in "Deadlines & money" must be a **verbatim substring of its own transcription**, checked by a pure-Python grounding pass (no second model call).
+2. If a value isn't in the letter, the answer is **"None found."** — never a guess.
+3. The eval gate (zero invented values, 100% recall, severity parseable, beginner-mode invariance) runs on every gold letter, plus **adversarial fixtures**: a blurry photo, a grocery receipt, and a non-Swedish letter must all be *refused*, not analyzed.
+
+## 👇 How to use it
+
+**Upload a saved file** — a photo (JPEG/PNG) or a PDF of your letter, multi-page supported. Bureaucat does **not** use your camera or take live photos; snap the letter with your phone first, then upload the image or PDF here. One upload uses one short ZeroGPU call.
+
+The example gallery at the bottom of the app contains **pre-computed analyses** — tap any of the five letters and the full result loads instantly at **zero GPU cost**, no upload needed.
+
+*Why synthetic examples?* Real authority letters are full of personal data (names, personnummer, amounts) and can't be published — and the official "example" documents authorities publish are info sheets without the personalized deadlines/amounts that make a letter scary. So the gallery letters are **faithful synthetic recreations** of the five letter types, with realistic Swedish layouts, diacritics, and values — built so nobody's real mail ends up in a public repo. Every letter shown in the app and in the demo video is one of these synthetic mock-ups — I tested Bureaucat privately on my own real Swedish mail, which never gets published.
+
+## 🏅 Badges claimed
+
+- **Off the Grid** — no cloud APIs; the 9B VLM runs entirely in this Space
+- **Off-Brand** — custom frontend via `gr.Server`
+- **Field Notes** — build report: what greedy decoding revealed that sampling had masked
+
+## ⚖️ Privacy & disclaimer
+
+- **Stateless:** letters are processed in-memory and never stored. Still — redact your personnummer before uploading if you can.
+- **Not legal advice.** Bureaucat helps you understand a letter; always verify deadlines against the original and contact the authority if unsure.
+
+---
+
+*Built by an expat, for expats, with one small cat-shaped model.* 🐾

app.py

@@ -0,0 +1,1626 @@
+import os
+
+# MPS lacks a few VLM ops in bf16; let those individual ops fall back to CPU
+# instead of hard-crashing. Must be set BEFORE torch is imported.
+os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
+
+import json
+import time
+from pathlib import Path
+
+import gradio as gr
+import pypdfium2 as pdfium  # PDF → PIL render, server-side (INPUT-02, no system binary needed)
+import spaces  # ZeroGPU decorator; a harmless no-op when running locally
+import torch
+from transformers import (
+    AutoProcessor,
+    Qwen3VLForConditionalGeneration,
+    # Actual class name in transformers 5.10.2 is Qwen2_5_VLForConditionalGeneration
+    # Aliased to Qwen2_5VLForConditionalGeneration to match the bake-off contract.
+    Qwen2_5_VLForConditionalGeneration as Qwen2_5VLForConditionalGeneration,
+)
+
+# eval/grounded.py is stdlib-only; importing it never triggers model loading.
+# Used to drive the verifying mascot state (D2-05) — pure Python check, no GPU.
+from eval.grounded import check_no_invention  # noqa: F401  (used in Phase 2 UI plan)
+
+# ---------------------------------------------------------------------------
+# Device / dtype — SPACE_ID sentinel (D-02 ratified 2026-06-05)
+# The is_available() CUDA check is NOT reliable at module scope on ZeroGPU:
+# CUDA emulation is active at import time but that check may return False.
+# SPACE_ID is set on all HF Spaces; absent locally → MPS or CPU.
+# ---------------------------------------------------------------------------
+if os.getenv("SPACE_ID"):
+    DEVICE = "cuda"
+elif torch.backends.mps.is_available():
+    DEVICE = "mps"
+else:
+    DEVICE = "cpu"
+
+DTYPE = torch.float32 if DEVICE == "cpu" else torch.bfloat16
+print(f"[Bureaucat] device={DEVICE}  dtype={DTYPE}")
+
+# ---------------------------------------------------------------------------
+# Model-agnostic bake-off loader (D-16)
+# Switch between candidates by setting BUREAUCAT_MODEL env var.
+# IMAGE_PATCH_SIZE: 16 for Qwen3-VL (patch_size=16), 14 for Qwen2.5-VL.
+# ---------------------------------------------------------------------------
+MODEL_VARIANTS = {
+    "qwen3": {
+        "model_id": "Qwen/Qwen3-VL-8B-Instruct",
+        "model_class": Qwen3VLForConditionalGeneration,
+        "image_patch_size": 16,
+    },
+    "qwen25": {
+        "model_id": "Qwen/Qwen2.5-VL-7B-Instruct",
+        "model_class": Qwen2_5VLForConditionalGeneration,
+        "image_patch_size": 14,
+    },
+}
+
+# LOCKED MODEL (MODEL-01, Plan 01-04 bake-off, 2026-06-05): "qwen3" = Qwen3-VL-8B-Instruct.
+# Verdict: on the calibrated 5-letter gold gate, qwen3 passed 5/5 (zero invented values,
+# 100% recall both standard+beginner, severity parseable everywhere); the smaller
+# Qwen2.5-VL-7B passed only 3/5 (dropped case/dossier reference numbers on the standard
+# pass). "Smallest model that passes wins" → the smaller model does not pass, so qwen3 is
+# locked. Default read from env so the harness can still drive qwen25; the Space does NOT
+# set BUREAUCAT_MODEL → production runs qwen3.
+MODEL_VARIANT = os.getenv("BUREAUCAT_MODEL", "qwen3")
+
+# Resolve patch size once at module scope so run_inference can reference it.
+IMAGE_PATCH_SIZE = MODEL_VARIANTS[MODEL_VARIANT]["image_patch_size"]
+
+# Max new tokens: raised 1200 -> 1600 (Phase 3, MODEL-01 amendment 2026-06-06). The
+# Phase-1 lock at 1200 was established under stochastic sampling and a single output
+# language. The Phase-3 5x5 multilingual matrix surfaced truncation on the token-heaviest
+# combination (Hindi + beginner mode: Devanagari is token-dense and beginner mode adds
+# inline explanations) — csn-aterkrav hit exactly 1200 mid-output and dropped the SEVERITY
+# line. Under greedy decoding (see run_inference_multi) that worst case lands at ~1068
+# tokens, so 1600 gives comfortable (~530-token) headroom across all five languages.
+# Latency note: more tokens => longer generation; the D-03 <40s ZeroGPU budget (DEFERRED)
+# must be re-checked on the Space now that the ceiling is higher.
+MAX_NEW_TOKENS = 1600
+
+# ---------------------------------------------------------------------------
+# Page-cap constants for multi-image input (INPUT-01)
+# DEFERRED tuning targets (D-03): the <40s ZeroGPU latency check is not measurable
+# on local Apple MPS. Tune after measuring real inference time on the dev Space.
+# ---------------------------------------------------------------------------
+MAX_PAGES_SOFT = 3   # Warn user above this count (soft advisory threshold)
+MAX_PAGES_HARD = 5   # Hard cap: truncate to this many pages before inference
+
+# Vision-token budget (single knob — keep processor + per-image content in sync).
+# LOCKED at 1280×28×28 ≈ 1M px: a 1024×28×28 speed experiment (2026-06-12)
+# FAILED the eval gate — 4/5 gold recall and the non-Swedish fixture was
+# analyzed instead of refused. Any change MUST re-pass the full gate
+# (python -m eval.run_eval --model qwen3) before shipping.
+MIN_PIXELS = 256 * 28 * 28    # ~200K pixel budget floor (OCR-safe)
+MAX_PIXELS = 1280 * 28 * 28   # ~1M pixel budget ceiling (doc images)
+
+
+def pdf_to_images(pdf_bytes: bytes, max_pages: int = MAX_PAGES_HARD, dpi: int = 200) -> list:
+    """
+    Render the first ≤max_pages pages of a PDF to PIL Images at the given DPI.
+
+    Accepts bytes only — never a filesystem path (D3-09 in-memory constraint / T-03-05
+    path-traversal mitigation). 200 DPI renders A4 to ~1654×2339 px, within the
+    qwen-vl-utils max_pixels budget of 1280×28×28 ≈ 1M px (D3-10).
+
+    Returns a list[PIL.Image.Image] (possibly empty if the PDF has no pages).
+    Raises PdfiumError on corrupt / malformed input (caller wraps in try/except).
+    """
+    pdf = pdfium.PdfDocument(pdf_bytes)
+    images = []
+    for i in range(min(len(pdf), max_pages)):
+        images.append(pdf[i].render(scale=dpi / 72.0).to_pil())
+    return images
+
+
+def load_model(variant: str):
+    """
+    Load model + processor for the given variant key ("qwen3" or "qwen25").
+
+    Applies:
+    - AutoProcessor with pixel budget controls
+    - attn_implementation="sdpa" (safe built-in, avoids flash-attn dependency)
+    - dtype=DTYPE (keeps working baseline kwarg; NOT torch_dtype)
+    - unconditional .to(DEVICE) — ZeroGPU emulation layer requires .to(), not
+      the accelerate multi-device dispatch path
+    - model.eval()
+
+    Returns (model, processor).
+    """
+    v = MODEL_VARIANTS[variant]
+    model_id = v["model_id"]
+    model_class = v["model_class"]
+
+    print(f"[Bureaucat] loading {model_id} ...")
+    print("[Bureaucat] (first run downloads weights to ~/.cache/huggingface)")
+
+    proc = AutoProcessor.from_pretrained(
+        model_id,
+        min_pixels=MIN_PIXELS,
+        max_pixels=MAX_PIXELS,
+    )
+    mdl = model_class.from_pretrained(
+        model_id,
+        dtype=DTYPE,
+        attn_implementation="sdpa",
+    )
+    mdl = mdl.to(DEVICE)
+    mdl.eval()
+    print("[Bureaucat] model ready.")
+    return mdl, proc
+
+
+# ---------------------------------------------------------------------------
+# TEST ESCAPE HATCH
+# When BUREAUCAT_NO_MODEL is set (e.g. by unit tests), skip the heavy load.
+# The Space and the bake-off do NOT set this var, so the D-02 module-scope
+# cuda load still happens in production.
+# ---------------------------------------------------------------------------
+if os.getenv("BUREAUCAT_NO_MODEL"):
+    model = None
+    processor = None
+else:
+    model, processor = load_model(MODEL_VARIANT)
+
+# ---------------------------------------------------------------------------
+# Output schema + parser (D-04–D-08)
+# ---------------------------------------------------------------------------
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class StructuredResult:
+    transcription: str         # raw verbatim OCR; used by eval harness (D-04)
+    quip: str                  # "Bureaucat says:" value (D-07)
+    tldr: str
+    why: str
+    actions: str
+    deadlines: str
+    severity: Optional[int]    # None if output truncated (D-06)
+    raw: str                   # full raw model output
+    doctype: str = "letter"    # DOCTYPE sentinel: letter | unreadable | not_letter | non_swedish (D3-01)
+
+
+SECTION_ANCHORS = [
+    ("tldr",      r"##\s*TL;?DR"),
+    ("why",       r"##\s*Why you got this"),
+    ("actions",   r"##\s*What you need to do"),
+    ("deadlines", r"##\s*Deadlines\s*&\s*money"),
+]
+
+
+def _split_sections(text: str) -> dict:
+    """Split body text into four sections by fixed Markdown heading anchors (D-05)."""
+    result = {}
+    for i, (key, pattern) in enumerate(SECTION_ANCHORS):
+        m = re.search(pattern, text, re.IGNORECASE)
+        if not m:
+            continue
+        start = m.end()
+        if i + 1 < len(SECTION_ANCHORS):
+            next_m = re.search(SECTION_ANCHORS[i + 1][1], text, re.IGNORECASE)
+            end = next_m.start() if next_m else len(text)
+        else:
+            end = len(text)
+        result[key] = text[start:end].strip()
+    return result
+
+
+DOCTYPE_RE = re.compile(
+    r'^DOCTYPE:\s*(letter|unreadable|not_letter|non_swedish)',
+    re.MULTILINE | re.IGNORECASE,
+)
+
+
+def parse_output(raw: str) -> StructuredResult:
+    """
+    Parse raw model output into a StructuredResult.
+
+    Language-invariant: anchors on fixed English sentinels regardless of
+    the prose language. Never raises — returns empty fields and severity=None
+    on malformed/truncated output (T-02-02).
+
+    DOCTYPE sentinel (D3-01): extracted after <transcription> block, before section
+    split. Regex accepts only the four enumerated tokens; any other/absent value
+    defaults to "letter" (D3-02 lean-toward-analyzing).
+    """
+    if not raw:
+        return StructuredResult(
+            transcription="", quip="", tldr="", why="",
+            actions="", deadlines="", severity=None, raw=raw,
+            doctype="letter",
+        )
+
+    # 1. Extract and strip the <transcription> block (D-04).
+    transcription = ""
+    trans_match = re.search(
+        r"<transcription>(.*?)</transcription>",
+        raw, re.DOTALL | re.IGNORECASE
+    )
+    if trans_match:
+        transcription = trans_match.group(1).strip()
+    after_trans = re.sub(
+        r"<transcription>.*?</transcription>", "", raw,
+        flags=re.DOTALL | re.IGNORECASE
+    ).strip()
+
+    # 2. Parse DOCTYPE: first matching DOCTYPE line (D3-01). Accepts only the four
+    # enumerated tokens; defaults to "letter" if absent or unrecognised (D3-02).
+    doctype_m = DOCTYPE_RE.search(after_trans)
+    doctype = doctype_m.group(1).lower() if doctype_m else "letter"
+    # Strip the DOCTYPE line from body so it does not leak into section text.
+    after_trans = re.sub(
+        r'^DOCTYPE:\s*\S+\s*\n?', "", after_trans, flags=re.MULTILINE | re.IGNORECASE
+    ).strip()
+
+    # 3. Parse severity: LAST matching SEVERITY: N line (D-06). The schema puts
+    # SEVERITY on the final line; taking the last match means a stray earlier
+    # "SEVERITY:" mention in prose never mis-drives the Panic Meter (WR-02).
+    severity = None
+    sev_matches = re.findall(r"SEVERITY:\s*([1-5])\s*$", after_trans, re.MULTILINE)
+    if sev_matches:
+        severity = int(sev_matches[-1])
+    body = re.sub(r"\nSEVERITY:\s*[1-5]\s*$", "", after_trans, flags=re.MULTILINE).strip()
+
+    # 4. Parse the "Bureaucat says:" quip (D-07).
+    quip = ""
+    quip_match = re.search(r"Bureaucat says:\s*(.+?)(?:\n|$)", body)
+    if quip_match:
+        quip = quip_match.group(1).strip()
+
+    # 5. Split four sections by fixed English headings (D-05, Pitfall 3).
+    sections = _split_sections(body)
+
+    return StructuredResult(
+        transcription=transcription,
+        quip=quip,
+        tldr=sections.get("tldr", ""),
+        why=sections.get("why", ""),
+        actions=sections.get("actions", ""),
+        deadlines=sections.get("deadlines", ""),
+        severity=severity,
+        raw=raw,
+        doctype=doctype,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prompt (D-04–D-08)
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """\
+You are Bureaucat, an assistant that helps expats understand Swedish official letters.
+
+IMPORTANT — output format rules (do not deviate):
+1. First, write a full verbatim OCR transcription of the letter wrapped in XML tags:
+   <transcription>
+   [exact text of the letter, every word, number, date]
+   </transcription>
+2. Immediately after </transcription>, classify the document. Write exactly this line
+   (always in English, never translated, machine-parsed — do not translate it):
+   DOCTYPE: [letter|unreadable|not_letter|non_swedish]
+   Valid values:
+   - letter = readable Swedish authority or institutional document (analysable)
+   - unreadable = too blurry, dark, or low-resolution to read reliably
+   - not_letter = readable image but NOT a letter (e.g. photo, receipt, form, ID card)
+   - non_swedish = document's PRIMARY language is not Swedish
+     (a mostly-Swedish letter with embedded English phrases is still: letter)
+   When uncertain, use: letter
+   IMPORTANT: if DOCTYPE is not "letter", you MUST:
+   - Still write the "Bureaucat says:" quip line (in-voice, playful, one-liner)
+   - Still write the DOCTYPE line
+   - SKIP the four ## sections (TL;DR, Why you got this, What you need to do, Deadlines & money)
+   - SKIP the SEVERITY line
+3. Then write exactly this line (always in English, always playful):
+   Bureaucat says: [your witty one-liner about this letter]
+4. If DOCTYPE is "letter", write the four sections using EXACTLY these English headings:
+   ## TL;DR
+   ## Why you got this
+   ## What you need to do
+   ## Deadlines & money
+   (In "Deadlines & money" you MUST list EVERY date, EVERY amount of money, AND
+    EVERY reference number found anywhere in the letter. Reference numbers include
+    case numbers (ärendenummer), file/dossier numbers (dossiernummer), booking
+    numbers (bokningsnummer), and OCR/payment numbers — list them here EVEN IF the
+    letter has no payment or deadline. Never leave a reference number out of this
+    section.
+    Write one item per line. Start each line with the verbatim value from the letter,
+    then add a dash and your interpretation. Examples:
+    - 15 juni 2026 — last day to file your tax return
+    - 1 234 kr — amount to pay
+    - 9988776 — case number (ärendenummer)
+    Only write "None found." if the letter contains no dates, amounts, OR reference
+    numbers of any kind.)
+5. If DOCTYPE is "letter", add a last line, always in English, never translated:
+   SEVERITY: [1-5]
+   Rate how worried the reader should be using the FULL 1-5 range. Do NOT default
+   to 3 — most letters are NOT a 3. Pick the single number that best fits THIS
+   letter's real-world stakes:
+   - 1 = purely informational; nothing to do, no deadline, no money owed
+         (a confirmation, a receipt, an FYI notice)
+   - 2 = minor or routine action, low stakes, soft/distant or no hard deadline
+         (book or attend a routine appointment, a small optional fee)
+   - 3 = a genuine task with a clear deadline OR a modest amount to pay; manageable
+   - 4 = a significant amount owed, OR a firm deadline whose miss has real
+         consequences (a repayment demand, a required document submission)
+   - 5 = urgent and high-stakes: a large sum, an imminent deadline, or a severe
+         consequence such as rejection, debt collection, eviction, or loss of a
+         permit / residence status
+   Hard rules (these OVERRIDE any instinct to pick 3):
+   - If the letter warns of rejection, having to leave Sweden, losing a permit,
+     residence status, or benefit, debt collection, or eviction → SEVERITY 5.
+   - If the letter demands repayment of a specific sum, or sets a firm deadline
+     to submit documents or the case is closed/denied → SEVERITY at least 4.
+   - Use 3 only for a routine task with a clear but low-consequence deadline.
+   - Use 1-2 for informational notices and routine appointments with no real risk.
+
+Write all prose in the language requested in the user's message. Keep the four
+section headings, the DOCTYPE line, and the SEVERITY line in English, never translated.
+Quote all extracted values (dates, amounts, reference numbers) verbatim as they
+appear in the letter — never invent, approximate, or omit them.
+If something is unclear, say so. Do not invent details."""
+
+
+def build_user_prompt(language: str, beginner_mode: bool) -> str:
+    """
+    Build the per-call user prompt.
+
+    beginner_mode adds ONLY inline-explanation guidance within prose — it never
+    adds/removes sections or alters the SEVERITY line or transcription block (D-08).
+    """
+    # Reference-completeness reminder lives in the BASE prompt (both modes). The Phase-3
+    # 5x5 matrix surfaced the model dropping a clearly-labelled reference number from
+    # "Deadlines & money" — writing "None found." with e.g. "Ärendenummer: 9988776" sitting
+    # in the transcription. Under greedy decoding this is deterministic (sampling had merely
+    # masked it). The model's *default* is to omit references it doesn't tie to a deadline or
+    # amount; this reminder re-anchors the Finding-3 completeness rule per-call without
+    # touching the SYSTEM_PROMPT. It is mode-independent (standard mode failed too), so it
+    # belongs in the base prompt, not the beginner branch. NOTE: this is a prompt-level
+    # mitigation of a genuine model fragility — a deterministic transcription→Deadlines
+    # cross-check is the more robust follow-up (tracked for the user).
+    prompt = (
+        f"Please analyse this letter and respond in {language}."
+        "\n\nBefore you write the 'Deadlines & money' section, re-scan the full "
+        "transcription and list EVERY date, EVERY amount, AND EVERY reference number "
+        "(ärendenummer, dossiernummer, bokningsnummer, OCR-nummer) that appears anywhere "
+        "in the letter — each on its own line, verbatim. A reference number must be listed "
+        "even when it has no associated deadline or amount. Only write 'None found.' if "
+        "there is truly no date, amount, or reference number of any kind in the letter."
+    )
+    if beginner_mode:
+        prompt += (
+            "\n\nBeginner mode: within each section's prose, add brief "
+            "parenthetical explanations of Swedish institutions or terms "
+            "(e.g. Skatteverket, personnummer, OCR-nummer, etc.). "
+            "Do not add new sections."
+        )
+    return prompt
+
+
+# ---------------------------------------------------------------------------
+# Inference — primary multi-image path + backward-compat single-image wrapper
+# ---------------------------------------------------------------------------
+
+def run_inference_multi(
+    images: list,
+    language: str,
+    beginner_mode: bool,
+    mdl,
+    proc,
+    image_patch_size: int,
+) -> StructuredResult:
+    """
+    Encode-generate-parse for one or more images in a single inference call.
+
+    This is the single shared inference path for both the eval harness and the
+    Gradio UI (INPUT-01 multi-page).  run_inference() delegates here so there
+    is exactly one code path — no drift between harness and app.
+
+    process_vision_info is imported lazily so importing app under
+    BUREAUCAT_NO_MODEL=1 never requires qwen_vl_utils.
+    """
+    from qwen_vl_utils import process_vision_info  # lazy: not needed for parse_output tests
+
+    image_content = [
+        {
+            "type": "image",
+            "image": img,
+            "min_pixels": MIN_PIXELS,
+            "max_pixels": MAX_PIXELS,
+        }
+        for img in images
+    ]
+    messages = [
+        {"role": "system", "content": [{"type": "text", "text": SYSTEM_PROMPT}]},
+        {"role": "user", "content": image_content + [
+            {"type": "text", "text": build_user_prompt(language, beginner_mode)},
+        ]},
+    ]
+
+    chat_text = proc.apply_chat_template(
+        messages, tokenize=False, add_generation_prompt=True
+    )
+    image_inputs, video_inputs = process_vision_info(
+        messages, image_patch_size=image_patch_size
+    )
+    inputs = proc(
+        text=[chat_text],
+        images=image_inputs,
+        videos=video_inputs,
+        do_resize=False,
+        return_tensors="pt",
+    ).to(DEVICE)
+    inputs.pop("token_type_ids", None)  # Required for Qwen3-VL; harmless on Qwen2.5-VL
+
+    # Sanity log: if the image didn't become pixel tensors, the model is
+    # "reading" a blank page — that would look like plausible nonsense, not an error.
+    pv = inputs.get("pixel_values")
+    if pv is None:
+        return StructuredResult(
+            transcription="", quip="", tldr="", why="", actions="", deadlines="",
+            severity=None, raw="ERROR: pixel_values missing from inputs",
+        )
+    print(f"[Bureaucat] pixel_values={tuple(pv.shape)}")
+
+    # Greedy decoding (do_sample=False), pinned deliberately (MODEL-01 amendment,
+    # Phase 3). The shipped Qwen3-VL generation_config defaults to do_sample=true /
+    # temperature=0.7 / top_p=0.8 / top_k=20 — i.e. stochastic sampling. For a tool
+    # whose core promise is faithful, never-invented extraction, sampling is the wrong
+    # regime: it makes the same letter yield different outputs run-to-run (the source of
+    # the Phase-3 matrix's intermittent beginner-mode failures) and raises invention risk.
+    # Greedy is deterministic and follows the fixed output-format rules more faithfully.
+    # NOTE: repetition_penalty / no_repeat_ngram_size are NOT applied to the primary
+    # pass — they regressed the gold gate (5/5 → 0/5: no_repeat_ngram_size kills the
+    # legitimately-repeating "- value — label" deadline list, emptying whole sections in
+    # beginner mode) and the adversarial refusal pass. Pure greedy stays the primary path.
+    with torch.no_grad():
+        out_ids = mdl.generate(
+            **inputs,
+            max_new_tokens=MAX_NEW_TOKENS,
+            do_sample=False,
+        )
+
+    trimmed = [o[len(i):] for i, o in zip(inputs["input_ids"], out_ids)]
+    raw_text = proc.batch_decode(
+        trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+    )[0]
+    result = parse_output(raw_text)
+
+    # SEVERITY-recovery fallback (gate-safe by construction). On very dense real letters
+    # (long reference-number lists), pure greedy can fall into a degenerate repetition loop
+    # in "Deadlines & money" and exhaust the token budget BEFORE emitting the trailing
+    # SEVERITY line → severity=None → the Panic Meter shows "unclear" on an otherwise
+    # perfectly-read letter. When that happens (letter parsed WITH content but no severity),
+    # make ONE tiny, bounded text-only follow-up call asking only for the severity, scored
+    # from the transcription the model already produced. It is capped at a handful of tokens
+    # so it physically cannot loop (no long list to emit) — unlike a full re-generation,
+    # which on the densest letters loops again. This never runs on the gold set (those always
+    # emit SEVERITY on pass one), so it cannot affect the eval gate.
+    if (
+        result.doctype == "letter"
+        and result.severity is None
+        and (result.tldr or result.why or result.actions or result.deadlines)
+    ):
+        print("[Bureaucat] SEVERITY missing (dense-letter loop) — bounded severity-only retry")
+        result.severity = _recover_severity(result, mdl, proc)
+        if result.severity is not None:
+            print(f"[Bureaucat] recovered severity={result.severity}")
+
+    return result
+
+
+# Compact rubric for the severity-only recovery call — mirrors the SYSTEM_PROMPT scale
+# and hard rules so a recovered severity matches what the primary pass would have produced.
+SEVERITY_ONLY_PROMPT = """You rate how worried the reader of a Swedish authority letter should be, on a 1-5 scale. Use the FULL range; do NOT default to 3.
+- 1 = purely informational; nothing to do, no deadline, no money owed (a refund, a confirmation, an FYI)
+- 2 = minor or routine action, low stakes (a routine appointment, a small fee)
+- 3 = a genuine task with a clear deadline OR a modest amount to pay; manageable
+- 4 = a significant amount owed, OR a firm deadline whose miss has real consequences (a repayment demand, a required document submission)
+- 5 = urgent and high-stakes: a large sum, an imminent deadline, or a severe consequence (rejection, debt collection, eviction, loss of a permit / residence status)
+Hard rules: warns of rejection / leaving Sweden / losing a permit or benefit / debt collection / eviction → 5. Demands repayment of a specific sum, or a firm deadline to submit documents or the case is closed → at least 4.
+Reply with EXACTLY one line and nothing else: SEVERITY: [1-5]"""
+
+
+def _recover_severity(result, mdl, proc) -> Optional[int]:
+    """Bounded, loop-proof text-only severity classification from already-extracted text.
+
+    Uses the model's own transcription (falling back to the parsed sections) as context.
+    Returns an int 1-5, or None if the model still does not emit a parseable line.
+    """
+    context = result.transcription.strip()
+    if not context:
+        context = "\n\n".join(
+            s for s in (result.tldr, result.why, result.actions, result.deadlines) if s
+        ).strip()
+    if not context:
+        return None
+
+    messages = [
+        {"role": "system", "content": [{"type": "text", "text": SEVERITY_ONLY_PROMPT}]},
+        {"role": "user", "content": [{"type": "text", "text": (
+            "Swedish authority letter (already transcribed):\n\n"
+            + context
+            + "\n\nOutput only: SEVERITY: [1-5]"
+        )}]},
+    ]
+    chat_text = proc.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    sev_inputs = proc(text=[chat_text], return_tensors="pt").to(DEVICE)
+    sev_inputs.pop("token_type_ids", None)
+    with torch.no_grad():
+        sev_ids = mdl.generate(**sev_inputs, max_new_tokens=12, do_sample=False)
+    sev_trimmed = [o[len(i):] for i, o in zip(sev_inputs["input_ids"], sev_ids)]
+    sev_raw = proc.batch_decode(sev_trimmed, skip_special_tokens=True)[0]
+    m = re.search(r"SEVERITY:\s*([1-5])", sev_raw)
+    if not m:
+        m = re.search(r"\b([1-5])\b", sev_raw)  # last-ditch: a bare digit
+    return int(m.group(1)) if m else None
+
+
+def run_inference(
+    image,
+    language: str,
+    beginner_mode: bool,
+    mdl,
+    proc,
+    image_patch_size: int,
+) -> StructuredResult:
+    """
+    Single-image entry point — delegates to run_inference_multi([image], ...).
+
+    Preserved for backward compatibility so eval/run_eval.py calls (lines 329, 335)
+    continue to work without modification. Guarantees a single shared code path.
+    """
+    return run_inference_multi([image], language, beginner_mode, mdl, proc, image_patch_size)
+
+
+# Accurate short duration = better queue priority; visitors only have 3.5 min/day.
+# duration=55: placeholder until measured on dev Space (D-03).
+@spaces.GPU(duration=55)
+def decode(files, language, beginner_mode) -> StructuredResult:
+    """
+    Gradio entry point — accepts a gr.File payload: list[str] of temp file paths.
+
+    With file_count="multiple" and type="filepath" (Gradio 6.16.0, confirmed),
+    Gradio passes a list of temporary file paths (strings) or None when no file
+    has been uploaded yet.
+
+    Dispatches per file:
+    - *.pdf  → read to bytes immediately (T-03-05 path-traversal mitigation), render
+              via pdf_to_images(); a corrupt/malformed PDF catches PdfiumError and
+              returns doctype="unreadable" so it routes through the slice-1 refusal
+              path (confused mascot, no crash) — T-03-04.
+    - other  → Image.open(path).convert("RGB") as before.
+
+    All rendered pages are concatenated and capped at MAX_PAGES_HARD before
+    being passed to run_inference_multi (unchanged).
+    """
+    if not files:
+        return StructuredResult(
+            transcription="", quip="", tldr="", why="",
+            actions="", deadlines="", severity=None,
+            raw="Please upload or photograph a letter first.",
+        )
+
+    from PIL import Image as _PILImage
+    from io import BytesIO as _BytesIO
+
+    images: list = []
+    for path in files:
+        if path is None:
+            continue
+        # Read to bytes immediately — never trust or retain the temp path (T-03-05).
+        # Detect type by CONTENT, not filename: the custom gr.Server frontend uploads
+        # via gradio_client, which lands files as extensionless "blob" temp files, so
+        # endswith(".pdf") alone misses every real PDF (→ "No valid images found." on
+        # the error card). Sniff the %PDF magic bytes instead; extension is a fallback.
+        try:
+            with open(path, "rb") as fh:
+                data = fh.read()
+        except Exception:
+            continue
+        is_pdf = data[:5].startswith(b"%PDF") or path.lower().endswith(".pdf")
+        if is_pdf:
+            try:
+                page_images = pdf_to_images(data)
+                images.extend(page_images)
+            except Exception:
+                # Any PDF parse failure (corrupt, malicious, truncated) → refusal.
+                return StructuredResult(
+                    transcription="", quip="", tldr="", why="",
+                    actions="", deadlines="", severity=None,
+                    doctype="unreadable",
+                    raw="Could not read the PDF. Please try a different file.",
+                )
+        else:
+            try:
+                images.append(_PILImage.open(_BytesIO(data)).convert("RGB"))
+            except Exception:
+                continue  # skip unreadable image files; process remaining pages
+
+    if not images:
+        return StructuredResult(
+            transcription="", quip="", tldr="", why="",
+            actions="", deadlines="", severity=None,
+            raw="No valid images found.",
+        )
+
+    # Hard page cap — truncate before inference (DEFERRED tuning target D-03)
+    if len(images) > MAX_PAGES_HARD:
+        images = images[:MAX_PAGES_HARD]
+
+    return run_inference_multi(images, language, beginner_mode, model, processor, IMAGE_PATCH_SIZE)
+
+
+import html as _html
+
+
+# ---------------------------------------------------------------------------
+# Example gallery — pre-computed results for zero-GPU demo (UI-01)
+# Each entry: slug, display label, source image path, cached result JSON path.
+# Paths are hardcoded constants (T-02-04-01 mitigation: no user-supplied path).
+# ---------------------------------------------------------------------------
+
+# Ordered ascending by severity so the gallery tells a left→right story:
+# all-clear (refund) → routine → action-needed → money owed → urgent.
+EXAMPLE_LETTERS = [
+    {
+        "slug": "skatteverket-slutskattebesked",
+        "label": "Skatteverket — tax refund, good news (severity 1)",
+        "image": "data/letters/public/skatteverket-slutskattebesked.png",
+        "cached": "data/gallery/skatteverket-slutskattebesked-result.json",
+    },
+    {
+        "slug": "vardcentral-kallelse",
+        "label": "Vårdcentral — appointment reminder (severity 2)",
+        "image": "data/letters/public/vardcentral-kallelse.png",
+        "cached": "data/gallery/vardcentral-kallelse-result.json",
+    },
+    {
+        "slug": "forsakringskassan-komplettering",
+        "label": "Försäkringskassan — submit documents (severity 3)",
+        "image": "data/letters/public/forsakringskassan-komplettering.png",
+        "cached": "data/gallery/forsakringskassan-komplettering-result.json",
+    },
+    {
+        "slug": "csn-aterkrav",
+        "label": "CSN — student-aid repayment demand (severity 4)",
+        "image": "data/letters/public/csn-aterkrav.png",
+        "cached": "data/gallery/csn-aterkrav-result.json",
+    },
+    {
+        "slug": "migrationsverket-uppehallstillstand",
+        "label": "Migrationsverket — residence permit at risk (severity 5)",
+        "image": "data/letters/public/migrationsverket-uppehallstillstand.png",
+        "cached": "data/gallery/migrationsverket-uppehallstillstand-result.json",
+    },
+]
+
+
+def load_example(evt: gr.SelectData) -> tuple:
+    """
+    Zero-GPU gallery loader — reads cached JSON from disk, returns full render tuple.
+
+    NOT decorated with @spaces.GPU. Never calls the model.
+    Security: evt.index selects from a hardcoded EXAMPLE_LETTERS list (T-02-04-01:
+    no user-supplied path string — load_example is immune to path traversal).
+
+    Returns the same 7-element tuple as render_result() so gallery.select() and
+    the decode .then() chain share identical output bindings.
+    """
+    entry = EXAMPLE_LETTERS[evt.index]
+    data = json.loads(Path(entry["cached"]).read_text(encoding="utf-8"))
+    result = StructuredResult(**data)
+    # Always render in English (gallery examples are pre-computed in English)
+    return render_result(result, "English")
+
+
+# ---------------------------------------------------------------------------
+# Pure-Python UI renderer functions (no GPU, no model loading)
+# ---------------------------------------------------------------------------
+
+def render_quip(quip: str) -> str:
+    """
+    Render the Bureaucat quip line as a Markdown string.
+
+    Returns empty string if quip is blank (hides the component).
+    The "Bureaucat says:" prefix is prepended HERE at render time — parse_output
+    already strips the prefix from the stored .quip field (line 220), so never
+    add it at parse time or you get "Bureaucat says: Bureaucat says: …".
+    """
+    if not quip or not quip.strip():
+        return ""
+    escaped_quip = _html.escape(quip.strip())
+    return f'**Bureaucat says:** *{escaped_quip}*'
+
+
+def render_deadlines_html(deadlines: str) -> str:
+    """
+    Render the Deadlines & money section as an HTML string (for gr.HTML).
+
+    Uses gr.HTML (not gr.Markdown) because Markdown sanitization strips <mark>
+    and inline style= attributes (RESEARCH Pitfall 2, T-02-02-01 mitigated).
+
+    Model text in pills is HTML-escaped before wrapping (T-02-02-01).
+
+    If deadlines is empty or "None found." → returns plain body text, no pill.
+    Otherwise: each "- VALUE — interpretation" line becomes a <li> with the
+    verbatim value highlighted in a warm amber <mark> pill.
+
+    Pill spec (UI-SPEC §Deadlines & Money Card):
+      background: #FFF3CD, color: #8B6914, padding: 4px, border-radius: 4px
+    """
+    if not deadlines or not deadlines.strip():
+        return "<p>None found.</p>"
+
+    # Check for "None found" (case-insensitive)
+    if re.match(r"\s*none found\.?\s*$", deadlines, re.IGNORECASE):
+        return f"<p>{_html.escape(deadlines.strip())}</p>"
+
+    lines = deadlines.strip().splitlines()
+    items = []
+    has_pill_line = False
+
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        # Strip leading bullet markers (-, *, •)
+        stripped = re.sub(r"^[-*•]\s*", "", line).strip()
+        if not stripped:
+            continue
+
+        # Check for "None found" lines
+        if re.match(r"none found\.?$", stripped, re.IGNORECASE):
+            items.append(f"<li>{_html.escape(stripped)}</li>")
+            continue
+
+        # Split on first interpretation separator (same convention as extract_values_from_section)
+        sep_match = re.search(r"\s+[—–\-]\s+", stripped)
+        if sep_match:
+            value_raw = stripped[: sep_match.start()].strip()
+            interpretation_raw = stripped[sep_match.end():].strip()
+            value_esc = _html.escape(value_raw)
+            interp_esc = _html.escape(interpretation_raw)
+            pill = (
+                f'<mark style="background:#FFF3CD;color:#8B6914;'
+                f'padding:4px;border-radius:4px">{value_esc}</mark>'
+            )
+            items.append(f"<li>{pill} &mdash; {interp_esc}</li>")
+            has_pill_line = True
+        else:
+            # No separator — render as plain text pill (value = whole line)
+            value_esc = _html.escape(stripped)
+            pill = (
+                f'<mark style="background:#FFF3CD;color:#8B6914;'
+                f'padding:4px;border-radius:4px">{value_esc}</mark>'
+            )
+            items.append(f"<li>{pill}</li>")
+            has_pill_line = True
+
+    if not items:
+        return "<p>None found.</p>"
+
+    if not has_pill_line:
+        # Only "None found" lines — render as plain paragraph(s)
+        return "<p>" + " ".join(
+            _html.escape(re.sub(r"^[-*•]\s*", "", l.strip()).strip())
+            for l in lines if l.strip()
+        ) + "</p>"
+
+    return (
+        '<ul style="list-style:none;padding:0;margin:0">'
+        + "".join(items)
+        + "</ul>"
+    )
+
+
+def render_footer() -> str:
+    """
+    Always-visible footer HTML containing both required trust statements.
+
+    TRUST-01: privacy note (nothing stored, no external APIs)
+    TRUST-05: legal disclaimer (not legal advice)
+    """
+    return (
+        '<div class="bcat-footer">'
+        "<p>Everything runs on a small model inside this Space. "
+        "Nothing is sent to external APIs. "
+        "Nothing is stored after your session ends.</p>"
+        "<p>Bureaucat explains letters — it does not give legal advice. "
+        "For legal matters, consult a qualified professional.</p>"
+        "</div>"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Mascot assets map — Phase 2 wires 6 states; Phase 3 adds confused/wrong_document
+# ---------------------------------------------------------------------------
+
+MASCOT_ASSETS = {
+    "idle":           "assets/mascot/idle.png",
+    "reading":        "assets/mascot/reading.png",
+    "verifying":      "assets/mascot/verifying.png",
+    "allclear":       "assets/mascot/allclear.png",
+    "deadline":       "assets/mascot/deadline.png",
+    "money":          "assets/mascot/money.png",
+    "confused":       "assets/mascot/confused.png",       # Phase 3: unreadable input
+    "wrong_document": "assets/mascot/wrong_document.png", # Phase 3: not_letter / non_swedish
+}
+
+# Result-state detection regexes (D2-06 — do not change without plan approval)
+# Money: numeric amount followed by kr / SEK / currency symbol
+_MONEY_RE = re.compile(r'\d[\d\s]*(?:kr|SEK|€|\$|£)', re.IGNORECASE)
+# Date: "dd Month yyyy" (Swedish month names) OR ISO "yyyy-mm-dd"
+_DATE_RE = re.compile(
+    r'\b\d{1,2}\s+(?:jan|feb|mar|apr|maj|jun|jul|aug|sep|okt|nov|dec)\w*\s+\d{4}\b'
+    r'|\b\d{4}-\d{2}-\d{2}\b',
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Renderers — Plan 03 fills bodies
+# (wired in Plan 02 so the .then() chain is complete; implementations in Plan 03)
+# ---------------------------------------------------------------------------
+
+_SEVERITY_COLORS = {
+    1: "#27AE60",
+    2: "#8BC34A",
+    3: "#F39C12",
+    4: "#E67E22",
+    5: "#C0392B",
+}
+
+_SEVERITY_LABELS = {
+    1: "1 — Informational",
+    2: "2 — Low concern",
+    3: "3 — Action needed",
+    4: "4 — Urgent",
+    5: "5 — Act immediately",
+}
+
+
+def render_panic_meter(severity) -> str:
+    """Return HTML for the Panic Meter — a color-coded *verdict badge* (FUN-01).
+
+    severity int 1-5: solid color-tinted badge showing a big "{N}/5" + the
+    word label. This deliberately is NOT a horizontal fill bar — a fill bar
+    reads as a progress/loading bar (UAT feedback, 2026-06-06).
+    severity None: gray "Result unavailable" badge.
+    Never color-only (accessibility, UI-SPEC line 92): the badge always shows
+    the integer and the word, and the aria-label carries "{N} — {word}".
+    """
+    if severity is None:
+        return (
+            '<div class="panic-badge panic-badge--none" role="status" '
+            'style="border-color:#9E9E9E" '
+            'aria-label="Result unavailable — try re-uploading">'
+            '<div class="panic-badge__word">Result unavailable — try re-uploading</div>'
+            "</div>"
+        )
+    color = _SEVERITY_COLORS.get(severity, "#9E9E9E")
+    label = _SEVERITY_LABELS.get(severity, f"{severity}")   # e.g. "3 — Action needed"
+    word = label.split("—", 1)[1].strip() if "—" in label else label
+    return (
+        f'<div class="panic-badge severity-{severity}" role="status" '
+        f'style="background:{color}" '
+        f'aria-label="Panic level: {label}">'
+        f'<div class="panic-badge__num">{severity}<span class="panic-badge__denom">/5</span></div>'
+        f'<div class="panic-badge__word">{word}</div>'
+        f"</div>"
+    )
+
+
+def render_panic_placeholder() -> str:
+    """Neutral initial state for the panic area (before any analysis) so it
+    never reads as an empty/stalled progress bar (UAT feedback, 2026-06-06)."""
+    return (
+        '<div class="panic-badge panic-badge--placeholder" role="status">'
+        '<div class="panic-badge__word">🐾 Feed me a letter and I\'ll tell you how worried to be</div>'
+        "</div>"
+    )
+
+
+def render_mascot(state: str) -> str:
+    """Return HTML for the mascot gr.HTML component (img tag + CSS class).
+
+    CSS class mascot-{state} drives keyframe animation (CSS-only, no JS).
+    Unknown state falls back to idle asset.
+    """
+    src = MASCOT_ASSETS.get(state, MASCOT_ASSETS["idle"])
+    # Gradio 6 serves allowed_paths files under /gradio_api/file= (the bare
+    # `file=` route from older Gradio 404s on 6.x). Leading slash → resolves
+    # from server root regardless of page path. allowed_paths=["assets"] at launch.
+    return (
+        f'<img src="/gradio_api/file={src}" '
+        f'class="mascot-img mascot-{state}" '
+        f'alt="Bureaucat is {state}" />'
+    )
+
+
+def select_result_state(result) -> str:
+    """Return the mascot result state based on StructuredResult content (D2-06).
+
+    Severity 1 is genuinely good / no-stakes news (e.g. a tax REFUND) → the happy
+    "allclear" cat, which also drives the celebratory screen effects. This takes
+    priority over content: a refund has a money amount but is NOT alarming, so it
+    must not get the "money" (shocked) cat.
+
+    Otherwise content-priority: money > deadline > allclear.
+    "none found" in deadlines text short-circuits to allclear immediately.
+    """
+    if getattr(result, "severity", None) == 1:
+        return "allclear"
+    deadlines_text = result.deadlines or ""
+    if "none found" in deadlines_text.lower():
+        return "allclear"
+    if _MONEY_RE.search(deadlines_text):
+        return "money"
+    if _DATE_RE.search(deadlines_text):
+        return "deadline"
+    return "allclear"
+
+
+# ---------------------------------------------------------------------------
+# Legacy helper kept for backward compat (replaced by structured render path)
+# ---------------------------------------------------------------------------
+
+def _render_result(result: StructuredResult) -> str:
+    """Extract displayable text from StructuredResult for the Markdown pane."""
+    return result.raw or "No output generated."
+
+
+# ---------------------------------------------------------------------------
+# CSS — Global styles (brand palette, card styles, RTL text-align rule)
+# Applied via demo.launch(css=GLOBAL_CSS) so it covers the full page.
+# DO NOT pass css= to gr.Blocks() — that emits a UserWarning in Gradio 6.x.
+# The [dir="rtl"] rule supplies the text-align half of the RTL contract
+# (UI-SPEC §Typography line 62) when gr.Markdown's rtl prop sets dir="rtl".
+# ---------------------------------------------------------------------------
+
+GLOBAL_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Fredoka:wght@400;500;600;700&family=Baloo+2:wght@600;700;800&display=swap');
+.gradio-container { max-width: 1040px !important; margin: 0 auto !important; }
+/* Page background is set per-mode via the theme (.set body_background_fill*)
+   — NOT hardcoded here, which was the dark-mode break (light body + light theme text). */
+
+/* Hero header — chunky, cartoon, a little bouncy */
+.bcat-hero { display: flex; align-items: center; gap: 16px; padding: 14px 4px 6px; }
+.bcat-hero__emoji { font-size: 54px; line-height: 1; animation: bcat-bounce 2.2s ease-in-out infinite; transform-origin: bottom center; }
+.bcat-hero__title { font-family: "Baloo 2", "Fredoka", sans-serif; font-size: 42px; font-weight: 800; letter-spacing: -0.01em; margin: 0; line-height: 1; background: linear-gradient(90deg, #E91E63, #84CC16); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; }
+.bcat-hero__tag { font-size: 16px; color: var(--body-text-color-subdued); margin: 4px 0 0; }
+@keyframes bcat-bounce { 0%,100%{transform:translateY(0) scale(1)} 30%{transform:translateY(-10px) scale(1.06)} 50%{transform:translateY(0) scale(0.97)} }
+
+/* Big chunky tab labels */
+.tabs button, .tab-nav button { font-family: "Fredoka", sans-serif !important; font-size: 17px !important; font-weight: 600 !important; }
+
+/* Sassy chunky call-to-action button */
+.cta-btn { font-family: "Fredoka", sans-serif !important; font-size: 18px !important; font-weight: 700 !important; border-radius: 14px !important; padding: 12px 18px !important; box-shadow: 0 6px 0 0 rgba(0,0,0,0.12) !important; transition: transform 0.08s ease, box-shadow 0.08s ease !important; }
+.cta-btn:hover { transform: translateY(-2px) !important; box-shadow: 0 8px 0 0 rgba(0,0,0,0.14) !important; }
+.cta-btn:active { transform: translateY(3px) !important; box-shadow: 0 2px 0 0 rgba(0,0,0,0.14) !important; }
+
+/* Sassy quip — speech-bubble feel */
+.quip-line { font-size: 17px !important; font-style: italic; margin-top: 8px !important; }
+.quip-line p { background: var(--background-fill-secondary); border-radius: 14px; padding: 12px 16px; margin: 0; position: relative; }
+
+/* Surfaces — theme-aware so both light and dark render correctly.
+   gr.Group(elem_classes="section-card") IS the card; inner blocks are flattened
+   so the heading + prose read as one surface (not nested boxes). */
+.section-card, .input-card {
+  background: var(--block-background-fill);
+  border: 1px solid var(--border-color-primary);
+  color: var(--body-text-color);
+  border-radius: 14px !important; padding: 14px 18px; margin-bottom: 12px;
+  box-shadow: var(--block-shadow, 0 1px 3px rgba(0,0,0,0.06));
+  overflow: hidden;
+}
+.section-card > *, .section-card .block, .section-card .form,
+.section-card .prose, .section-card .md {
+  background: transparent !important; border: none !important; box-shadow: none !important;
+}
+.section-card h3 {
+  font-size: 12px; font-weight: 700; color: var(--body-text-color);
+  opacity: 0.55; margin: 0 0 6px 0; text-transform: uppercase; letter-spacing: 0.07em;
+}
+
+/* Panic verdict badge — status chip, deliberately NOT a fill/progress bar */
+.panic-badge { border-radius: 16px; padding: 16px 20px; color: #fff; display: flex; align-items: baseline; gap: 14px; box-shadow: 0 6px 18px rgba(0,0,0,0.16); margin-bottom: 10px; }
+.panic-badge__num { font-size: 40px; font-weight: 800; line-height: 1; }
+.panic-badge__denom { font-size: 18px; font-weight: 600; opacity: 0.8; margin-left: 2px; }
+.panic-badge__word { font-size: 17px; font-weight: 800; text-transform: uppercase; letter-spacing: 0.06em; align-self: center; }
+.panic-badge--none, .panic-badge--placeholder { background: var(--background-fill-secondary); color: var(--body-text-color-subdued); border: 1.5px dashed var(--border-color-primary); box-shadow: none; justify-content: center; }
+.panic-badge--none .panic-badge__word, .panic-badge--placeholder .panic-badge__word { text-transform: none; font-weight: 600; letter-spacing: 0; font-size: 15px; }
+/* Bouncy pop-in when a real verdict lands (game-feel) */
+@keyframes pop-in { 0%{transform:scale(0.85);opacity:0} 60%{transform:scale(1.04)} 100%{transform:scale(1);opacity:1} }
+.panic-badge.severity-1,.panic-badge.severity-2,.panic-badge.severity-3,.panic-badge.severity-4,.panic-badge.severity-5 { animation: pop-in 0.45s cubic-bezier(.22,1.2,.36,1); }
+
+/* Mascot — compact beside the verdict; bigger & bouncier on the fun tab */
+.mascot-panel { text-align: center; padding: 0; }
+.mascot-panel img { transition: opacity 0.2s ease; }
+.mascot-big img { max-width: 180px !important; }
+.mascot-big .mascot-idle { animation: bcat-bounce 2s ease-in-out infinite; transform-origin: bottom center; }
+
+/* Footer — theme-aware trust note */
+.bcat-footer { padding: 16px; border-top: 1px solid var(--border-color-primary); font-size: 13px; color: var(--body-text-color-subdued); }
+.bcat-footer p { margin: 4px 0; }
+
+[dir="rtl"] { text-align: right; }
+"""
+
+
+# ---------------------------------------------------------------------------
+# CSS animation keyframes — injected as a gr.HTML style block (first element
+# inside gr.Blocks context). gr.HTML passes through <style>@keyframes unchanged
+# (RESEARCH Pattern 1 / Pattern 2 verified against gradio 6.16.0 source).
+# ---------------------------------------------------------------------------
+
+ANIMATION_CSS_HTML = """
+<style>
+@keyframes bob   { 0%,100%{transform:translateY(0)} 50%{transform:translateY(-4px)} }
+@keyframes sway  { 0%,100%{transform:rotate(0deg)} 50%{transform:rotate(3deg)} }
+@keyframes blink { 0%,100%{opacity:1} 50%{opacity:0.6} }
+@keyframes pop   { 0%{transform:scale(1)} 50%{transform:scale(1.1)} 100%{transform:scale(1)} }
+@keyframes shake { 0%,100%{transform:rotate(0deg)} 25%{transform:rotate(-5deg)} 75%{transform:rotate(5deg)} }
+.mascot-idle     { animation: bob   2s ease-in-out infinite; }
+.mascot-reading  { animation: sway  0.8s ease-in-out infinite; }
+.mascot-verifying{ animation: blink 0.4s ease infinite; }
+.mascot-allclear { animation: pop   0.3s ease 1; }
+.mascot-deadline { animation: shake 0.15s ease-in-out 3; }
+.mascot-money    { animation: shake 0.15s ease-in-out 3; }
+.mascot-img      { transition: opacity 0.2s ease; max-width: 120px; height: auto; min-height: 44px; }
+</style>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Event handler functions (Task 2b)
+# These run outside the GPU context; only decode() is GPU-decorated.
+# ---------------------------------------------------------------------------
+
+def set_reading_state() -> str:
+    """Fires immediately on button click — no GPU. Sets mascot to reading."""
+    return render_mascot("reading")
+
+
+def run_verifying_state(result) -> str:
+    """
+    Fires after decode() completes — pure Python, no GPU.
+
+    On refusals (doctype != "letter"): returns the appropriate error mascot
+    immediately, bypassing check_no_invention (which would operate on empty
+    values and could raise — Pitfall 2 / T-03-03).
+
+    On successful reads: runs the grounded no-invention check (D2-05), then
+    dwells for 0.6 s so the verifying mascot state is visible in the browser.
+    Without the dwell, Gradio may coalesce this update with the preceding/
+    following step and the verifying state is invisible (RESEARCH Pattern 3 —
+    NON-GPU .then() step, zero GPU quota cost).
+    """
+    # Refusal guard (T-03-03): skip check_no_invention on non-letter doctypes.
+    # render_result's own refusal branch then renders the final panes.
+    if getattr(result, "doctype", "letter") != "letter":
+        mascot_state = "confused" if getattr(result, "doctype", "") == "unreadable" else "wrong_document"
+        return render_mascot(mascot_state)
+    check_no_invention(result)       # pure-Python grounded check (eval/grounded.py)
+    time.sleep(0.6)                  # deliberate dwell — verifying state must be visible
+    return render_mascot("verifying")
+
+
+REFUSAL_GUIDANCE = {
+    "unreadable": (
+        "The photo is too blurry or dark to read. "
+        "Retake it in better light and make sure the whole letter is in frame and in focus."
+    ),
+    "not_letter": (
+        "That's a fine image, but it doesn't look like a Swedish authority letter. "
+        "Upload a letter from Skatteverket, Försäkringskassan, Migrationsverket, CSN, or similar."
+    ),
+    "non_swedish": (
+        "Bureaucat reads Swedish authority letters. "
+        "This one looks like it's in another language — upload a letter written in Swedish."
+    ),
+}
+
+
+def render_refusal(result, language: str) -> tuple:
+    """
+    Render a bad-input refusal as the same 7-element tuple as render_result.
+
+    Returns:
+      [0] panic_html   = "" (no Panic Meter for refusals — D3-03)
+      [1] mascot_html  = confused for unreadable; wrong_document for not_letter/non_swedish
+      [2] quip_md      = model's in-voice refusal quip (already escaped in render_quip)
+      [3] tldr_out     = app-side fixed guidance text keyed by doctype (NOT model-driven)
+      [4] why_out      = "" (no section)
+      [5] actions_out  = "" (no section)
+      [6] deadlines_html = "" (no deadlines)
+
+    Guidance copy is app-side (REFUSAL_GUIDANCE constant) — model only provides the quip.
+    This keeps the function unit-testable without a model (BUREAUCAT_NO_MODEL=1).
+    """
+    is_rtl = language == "Arabic"
+
+    def _wrap_rtl_html(html_str: str) -> str:
+        if is_rtl:
+            return f'<div dir="rtl" style="text-align:right">{html_str}</div>'
+        return html_str
+
+    def _md_update(text: str) -> dict:
+        return gr.update(value=text, rtl=is_rtl)
+
+    doctype = getattr(result, "doctype", "not_letter")
+    mascot_state = "confused" if doctype == "unreadable" else "wrong_document"
+    guidance = REFUSAL_GUIDANCE.get(doctype, REFUSAL_GUIDANCE["not_letter"])
+
+    return (
+        "",                              # 0 panic_html — no Panic Meter (D3-03)
+        render_mascot(mascot_state),     # 1 mascot_html
+        render_quip(result.quip),        # 2 quip_md — model's in-voice refusal quip
+        _md_update(guidance),            # 3 tldr_out — app-side guidance (not model-driven)
+        _md_update(""),                  # 4 why_out
+        _md_update(""),                  # 5 actions_out
+        _wrap_rtl_html(""),              # 6 deadlines_html
+    )
+
+
+def render_result(result, language: str) -> tuple:
+    """
+    Fires after run_verifying_state — renders all output panes.
+
+    Returns a 7-element tuple matching the outputs order:
+    [panic_html(0), mascot_html(1), quip_md(2),
+     tldr_out(3), why_out(4), actions_out(5), deadlines_html(6)]
+
+    RTL delivery-layer contract (UI-SPEC §Typography, T-02-02-01):
+    - Prose panes (3, 4, 5) are gr.Markdown. Their rtl prop is toggled via
+      gr.update(value=..., rtl=True/False) — explicit bool both ways so a
+      component set RTL on a prior Arabic run is reset for the next English run.
+      gr.HTML(<div dir="rtl">) would be STRIPPED by sanitize_html=True on
+      gr.Markdown — that is the silent bug this approach avoids.
+    - Deadlines & Panic gr.HTML (0, 6) are pass-through. For Arabic, wrap in
+      <div dir="rtl" style="text-align:right">. For other languages, no wrapper.
+    - Extracted verbatim values remain Swedish-locale regardless of direction.
+
+    Error handling: severity=None / malformed result → 7-element tuple with error
+    copy in tldr pane; no crash (RESEARCH Pattern 3, UI-SPEC Copywriting Contract).
+    """
+    ERROR_COPY = (
+        "Bureaucat had trouble reading that letter. Try uploading a clearer photo."
+    )
+
+    # Determine if RTL is needed (Arabic only)
+    is_rtl = language == "Arabic"
+
+    def _wrap_rtl_html(html_str: str) -> str:
+        """Wrap gr.HTML content in dir=rtl div for Arabic; leave others bare."""
+        if is_rtl:
+            return f'<div dir="rtl" style="text-align:right">{html_str}</div>'
+        return html_str
+
+    def _md_update(text: str) -> dict:
+        """Return gr.update dict for a gr.Markdown prose pane with explicit rtl."""
+        return gr.update(value=text, rtl=is_rtl)
+
+    # 1. Intentional refusal — doctype check FIRST (D3-03).
+    # Refusals legitimately have severity=None, so this branch MUST precede
+    # the severity=None malformed check below (routing order is load-bearing).
+    if result is not None and getattr(result, "doctype", "letter") != "letter":
+        return render_refusal(result, language)
+
+    # 2. Malformed / error path — only when there is NOTHING to show. A letter that
+    # produced an analysis but whose trailing SEVERITY line got lost (e.g. a greedy
+    # repetition loop on a dense letter) still has real content — salvage it below
+    # rather than discarding it with a false "couldn't read" error.
+    _has_content = result is not None and (
+        getattr(result, "tldr", "") or getattr(result, "why", "")
+        or getattr(result, "actions", "") or getattr(result, "deadlines", "")
+    )
+    if result is None or not hasattr(result, "severity") or (result.severity is None and not _has_content):
+        return (
+            render_panic_meter(None),                        # 0 panic_html
+            render_mascot("idle"),                           # 1 mascot_html
+            "",                                              # 2 quip_md
+            _md_update(ERROR_COPY),                          # 3 tldr_out
+            _md_update(""),                                  # 4 why_out
+            _md_update(""),                                  # 5 actions_out
+            _wrap_rtl_html(""),                              # 6 deadlines_html
+        )
+
+    # Render the result state (money / deadline / allclear) for the mascot
+    state = select_result_state(result)
+
+    return (
+        _wrap_rtl_html(render_panic_meter(result.severity)),     # 0 panic_html
+        render_mascot(state),                                    # 1 mascot_html
+        render_quip(result.quip),                                # 2 quip_md (always English)
+        _md_update(result.tldr or ""),                           # 3 tldr_out
+        _md_update(result.why or ""),                            # 4 why_out
+        _md_update(result.actions or ""),                        # 5 actions_out
+        _wrap_rtl_html(render_deadlines_html(result.deadlines)), # 6 deadlines_html
+    )
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI — Full gr.Blocks layout (Task 2a: static structure; Task 2b: event wiring)
+# ---------------------------------------------------------------------------
+
+# Game-feel confetti — runs in the browser via demo.load(js=...) because a
+# <script> injected through gr.HTML's innerHTML never executes. Loads the tiny
+# canvas-confetti lib from CDN, then a MutationObserver fires a burst whenever
+# the all-clear mascot appears (good news only). Best-effort: no-ops if the CDN
+# is blocked. Zero GPU cost.
+CONFETTI_JS = """
+() => {
+  if (!window.__bcatConfettiLoaded) {
+    const s = document.createElement('script');
+    s.src = 'https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js';
+    document.head.appendChild(s);
+    window.__bcatConfettiLoaded = true;
+  }
+  const fire = () => {
+    if (window.confetti) {
+      window.confetti({ particleCount: 110, spread: 75, origin: { y: 0.65 },
+        colors: ['#E91E63', '#84CC16', '#FFD166', '#FFFFFF'] });
+    }
+  };
+  if (!window.__bcatObserver) {
+    window.__bcatObserver = new MutationObserver(() => {
+      if (document.querySelector('.mascot-allclear')) {
+        const now = Date.now();
+        if (!window.__bcatLastFire || now - window.__bcatLastFire > 3000) {
+          window.__bcatLastFire = now;
+          setTimeout(fire, 150);
+        }
+      }
+    });
+    window.__bcatObserver.observe(document.body,
+      { subtree: true, childList: true, attributes: true, attributeFilter: ['class'] });
+  }
+}
+"""
+
+
+with gr.Blocks(title="Bureaucat") as demo:
+    # Inject animation keyframes as FIRST element (gr.HTML passes <style> unchanged)
+    gr.HTML(ANIMATION_CSS_HTML)
+
+    # Hero header
+    gr.HTML(
+        '<div class="bcat-hero">'
+        '<div class="bcat-hero__emoji">🐱</div>'
+        '<div>'
+        '<h1 class="bcat-hero__title">Bureaucat</h1>'
+        '<p class="bcat-hero__tag">Snap a scary Swedish letter. I\'ll tell you how worried to be — and what to do.</p>'
+        '</div>'
+        '</div>'
+    )
+
+    # gr.State stores the StructuredResult between .then() steps (RESEARCH Pitfall 5)
+    result_state = gr.State(value=None)
+
+    # ---- Input bar (shared, sits above the tabs — upload front and centre) ----
+    with gr.Row(elem_classes="input-card", equal_height=True):
+        with gr.Column(scale=2, min_width=240):
+            # Combined uploader: accepts images AND PDF (INPUT-02).
+            # gr.File with type="filepath" (Gradio 6.16.0, verified 2026-06-06) passes
+            # list[str] of temp file paths to decode(); file_count="multiple" enables
+            # multi-page letter upload (one image per scanned page, or one multi-page PDF).
+            input_file = gr.File(
+                file_count="multiple",
+                file_types=[".jpg", ".jpeg", ".png", ".pdf"],
+                type="filepath",
+                label="Upload letter — image(s) or PDF",
+            )
+        with gr.Column(scale=1, min_width=200):
+            # English-only product (hackathon scope, 2026-06-07): Bureaucat reads Swedish
+            # letters and explains them in English. The multi-language output selector was
+            # removed — the model's non-Latin translation (Arabic/Hindi) was fragile under
+            # deterministic greedy decoding, and English is the single supported output.
+            # A fixed "English" flows through the .then() chain via gr.State so decode() and
+            # render_result() keep their existing (language) signatures and tests unchanged.
+            lang = gr.State("English")
+            beginner = gr.Checkbox(
+                value=True,
+                label="I'm new to Sweden — explain the institutions & jargon",
+            )
+            btn = gr.Button("🐾 Read it for me!", variant="primary", elem_classes="cta-btn")
+
+    # ---- Tabs: fun & sassy by default, the rigorous breakdown one click away ----
+    with gr.Tabs():
+        # DEFAULT TAB — the fun verdict: big reacting mascot + panic badge + sass
+        with gr.Tab("😼 How bad is it?"):
+            with gr.Row(equal_height=True):
+                with gr.Column(scale=1, min_width=150):
+                    mascot_html = gr.HTML(
+                        render_mascot("idle"), elem_classes="mascot-panel mascot-big"
+                    )
+                with gr.Column(scale=2, min_width=240):
+                    # Panic Meter verdict badge (FUN-01)
+                    panic_html = gr.HTML(render_panic_placeholder())
+                    # Bureaucat's sassy one-liner (the personality moment)
+                    quip_md = gr.Markdown(elem_classes="quip-line")
+            # The punchy plain-language summary lives on the fun tab
+            with gr.Group(elem_classes="section-card"):
+                gr.HTML("<h3>The short version</h3>")
+                tldr_out = gr.Markdown(rtl=False)
+
+        # DETAILS TAB — the actual findings
+        with gr.Tab("🔍 The full breakdown"):
+            with gr.Group(elem_classes="section-card"):
+                gr.HTML("<h3>Why you got this</h3>")
+                why_out = gr.Markdown(rtl=False)
+
+            with gr.Group(elem_classes="section-card"):
+                gr.HTML("<h3>What you need to do</h3>")
+                actions_out = gr.Markdown(rtl=False)
+
+            # Deadlines card — gr.HTML (not gr.Markdown — sanitize strips <mark> RESEARCH Pitfall 2)
+            with gr.Group(elem_classes="section-card"):
+                gr.HTML("<h3>Deadlines &amp; money</h3>")
+                deadlines_html = gr.HTML()
+
+    # Example gallery row — pre-computed analyses, zero GPU cost (UI-01)
+    with gr.Row():
+        with gr.Column():
+            gr.Markdown(
+                "### 👇 No scary letter handy? Borrow one of mine\n\n"
+                "_Tap any example — I've already read these, so it costs you zero GPU._"
+            )
+            example_gallery = gr.Gallery(
+                value=[entry["image"] for entry in EXAMPLE_LETTERS],
+                label=None,
+                show_label=False,
+                columns=5,
+                rows=1,
+                height="auto",
+                object_fit="contain",
+                interactive=False,
+                allow_preview=False,
+            )
+
+    # Always-visible footer (outside any accordion, TRUST-01 + TRUST-05, D2-17)
+    with gr.Row():
+        gr.HTML(render_footer())
+
+    # ---------------------------------------------------------------------------
+    # Event chain (Task 2b) — .then() pattern (RESEARCH Pattern 3):
+    #   click → set_reading_state (no GPU, immediate mascot update)
+    #   .then → decode (GPU, stores StructuredResult in gr.State)
+    #   .then → run_verifying_state (pure Python, 0.6 s dwell, verifying mascot)
+    #   .then → render_result (pure Python, renders all output panes)
+    #
+    # decode is called DIRECTLY as event handler — NOT wrapped in a generator
+    # (RESEARCH Anti-Patterns: generator wrapping may prevent ZeroGPU recognition).
+    # ---------------------------------------------------------------------------
+    dep = btn.click(
+        set_reading_state,
+        inputs=None,
+        outputs=mascot_html,
+    )
+    dep2 = dep.then(
+        decode,
+        inputs=[input_file, lang, beginner],
+        outputs=result_state,
+    )
+    dep3 = dep2.then(
+        run_verifying_state,
+        inputs=result_state,
+        outputs=mascot_html,
+    )
+    dep4 = dep3.then(  # noqa: F841
+        render_result,
+        inputs=[result_state, lang],
+        outputs=[panic_html, mascot_html, quip_md, tldr_out, why_out, actions_out, deadlines_html],
+    )
+
+    # Example gallery select — zero-GPU loader (UI-01 gallery click → cached JSON render)
+    # No @spaces.GPU on load_example; outputs mirror dep4 exactly so no new binding needed.
+    example_gallery.select(  # noqa: F841
+        load_example,
+        inputs=None,
+        outputs=[panic_html, mascot_html, quip_md, tldr_out, why_out, actions_out, deadlines_html],
+    )
+
+    # Selecting a new file clears any previous verdict (stale-result bug) —
+    # same 7-element binding as dep4, pure Python, zero GPU.
+    def reset_panes() -> tuple:
+        return (
+            render_panic_placeholder(),
+            render_mascot("idle"),
+            "",
+            gr.update(value="", rtl=False),
+            gr.update(value="", rtl=False),
+            gr.update(value="", rtl=False),
+            "",
+        )
+
+    input_file.change(  # noqa: F841
+        reset_panes,
+        inputs=None,
+        outputs=[panic_html, mascot_html, quip_md, tldr_out, why_out, actions_out, deadlines_html],
+    )
+
+    # Game-feel: confetti when the verdict is all-clear (good news). Browser-side.
+    demo.load(js=CONFETTI_JS)
+
+# ---------------------------------------------------------------------------
+# Phase 4 — gr.Server custom frontend (Off-Brand badge)
+#
+# Opt-in via BUREAUCAT_UI=server (the proven Blocks UI stays the default, so
+# the Space can fall back instantly by unsetting one env var).
+#
+# ZeroGPU pattern (verified against ysharma/text-behind-image + the official
+# server-mode guide): @spaces.GPU stays on decode(); the @server.api endpoint
+# is a plain wrapper that calls it. The browser MUST call endpoints through
+# @gradio/client (it forwards the X-IP-Token header ZeroGPU quota needs) —
+# raw fetch() would land every visitor in the anonymous quota tier.
+# ---------------------------------------------------------------------------
+
+def _deadline_items(deadlines: str) -> list:
+    """
+    Parse the "Deadlines & money" section into [{value, note}, ...] for the
+    custom frontend (value pills + the deadline banner).
+
+    Mirrors render_deadlines_html's line conventions (bullet strip, the
+    space-padded —/–/- interpretation separator, "None found" filtering) but
+    returns data instead of HTML — the JSON API contract for server mode.
+    """
+    items = []
+    if not deadlines or re.match(r"\s*none found\.?\s*$", deadlines.strip(), re.IGNORECASE):
+        return items
+    for raw_line in deadlines.strip().splitlines():
+        stripped = re.sub(r"^[-*•]\s*", "", raw_line.strip()).strip()
+        if not stripped or re.match(r"none found\.?$", stripped, re.IGNORECASE):
+            continue
+        sep = re.search(r"\s+[—–\-]\s+", stripped)
+        if sep:
+            items.append({
+                "value": stripped[: sep.start()].strip(),
+                "note": stripped[sep.end():].strip(),
+            })
+        else:
+            items.append({"value": stripped, "note": ""})
+    return items
+
+
+def _result_to_payload(result) -> dict:
+    """
+    Convert a StructuredResult into the JSON payload the custom frontend
+    renders. Routing mirrors render_result(): refusal first (doctype is
+    load-bearing — refusals legitimately have severity=None), then malformed,
+    then success. Success payloads run the grounded no-invention check and
+    expose its verdict so the frontend can show a verification badge.
+    """
+    if result is not None and getattr(result, "doctype", "letter") != "letter":
+        doctype = getattr(result, "doctype", "not_letter")
+        return {
+            "kind": "refusal",
+            "doctype": doctype,
+            "mascot": "confused" if doctype == "unreadable" else "wrong_document",
+            "quip": result.quip or "",
+            "guidance": REFUSAL_GUIDANCE.get(doctype, REFUSAL_GUIDANCE["not_letter"]),
+        }
+
+    # Error only when there is genuinely nothing to show. A letter that produced
+    # an analysis but lost its trailing SEVERITY line (e.g. a greedy repetition
+    # loop on a dense letter) still has real content — render it with the gauge
+    # in an "unclear" state instead of a false "couldn't read" error.
+    _has_content = result is not None and (
+        result.tldr or result.why or result.actions or result.deadlines
+    )
+    if result is None or (getattr(result, "severity", None) is None and not _has_content):
+        return {
+            "kind": "error",
+            "mascot": "idle",
+            "guidance": "Bureaucat had trouble reading that letter. "
+                        "Try uploading a clearer photo.",
+        }
+
+    invented = check_no_invention(result)
+    sev = getattr(result, "severity", None)
+    return {
+        "kind": "letter",
+        "doctype": "letter",
+        "severity": sev,                                    # may be null (SEVERITY line lost)
+        "severity_label": _SEVERITY_LABELS.get(sev) if sev else None,
+        "severity_color": _SEVERITY_COLORS.get(sev, "#9E9E9E"),
+        "mascot": select_result_state(result),
+        "quip": result.quip or "",
+        "tldr": result.tldr or "",
+        "why": result.why or "",
+        "actions": result.actions or "",
+        "deadline_items": _deadline_items(result.deadlines or ""),
+        "deadlines_text": result.deadlines or "",
+        "grounded": not invented,
+        "invented_values": invented,
+    }
+
+
+def build_server():
+    """
+    Construct the gr.Server custom-frontend app (Off-Brand mode).
+
+    Deferred behind BUREAUCAT_UI=server so the default Blocks deployment never
+    constructs gr.Server or runs its mounts at import — the Space boots exactly
+    like a vanilla Blocks Space unless server mode is explicitly requested.
+    """
+    from fastapi.responses import HTMLResponse
+    from gradio.data_classes import FileData
+    from starlette.staticfiles import StaticFiles
+
+    server = gr.Server()
+
+    @server.api(name="analyze")
+    def api_analyze(files: list[FileData], beginner: bool = True) -> dict:
+        """
+        Custom-frontend inference endpoint. NOT GPU-decorated itself — it calls
+        decode(), which carries @spaces.GPU(duration=55). This wrapper shape keeps
+        image/PDF prep outside the metered GPU window.
+        """
+        # Items arrive as FileData objects OR plain dicts depending on how the
+        # client serializes a list[FileData] param (observed: dicts via gradio_client).
+        paths = []
+        for f in files or []:
+            if f is None:
+                continue
+            p = f.get("path") if isinstance(f, dict) else getattr(f, "path", None)
+            if p:
+                paths.append(p)
+        result = decode(paths, "English", bool(beginner))
+        return _result_to_payload(result)
+
+    @server.api(name="example")
+    def api_example(index: int) -> dict:
+        """
+        Zero-GPU gallery endpoint — same cached JSONs as load_example(). Index is
+        clamped into the hardcoded EXAMPLE_LETTERS list (no user-supplied paths).
+        """
+        entry = EXAMPLE_LETTERS[int(index) % len(EXAMPLE_LETTERS)]
+        data = json.loads(Path(entry["cached"]).read_text(encoding="utf-8"))
+        return _result_to_payload(StructuredResult(**data))
+
+    @server.get("/", response_class=HTMLResponse)
+    async def _homepage():
+        return Path("frontend/index.html").read_text(encoding="utf-8")
+
+    # Custom routes/mounts take priority over Gradio's defaults (server-mode docs).
+    server.mount("/static", StaticFiles(directory="frontend"), name="static")
+    server.mount("/assets", StaticFiles(directory="assets"), name="assets")
+    server.mount("/letters", StaticFiles(directory="data/letters/public"), name="letters")
+    return server
+
+
+if __name__ == "__main__":
+    if os.getenv("BUREAUCAT_UI", "blocks").strip().lower() == "server":
+        # Off-Brand custom frontend (Phase 4). Theme/CSS live in frontend/.
+        build_server().launch(show_error=True)
+        raise SystemExit(0)
+    # Gradio 6.0 moved BOTH css and theme to launch() (Blocks-constructor args
+    # emit a UserWarning and are ignored). Soft theme + brand hues = the modern
+    # base; GLOBAL_CSS layers the verdict badge / card polish on top.
+    # allowed_paths: "assets" for mascot images; "data" for gallery source images.
+    # Fun, gamified theme: chunky rounded Google font + bright lime/pink accents.
+    # Per-mode page background via the theme (NOT CSS) so dark mode renders
+    # correctly; body text color is theme-driven so hero/footer stay readable.
+    theme = gr.themes.Soft(
+        primary_hue="pink",
+        secondary_hue="lime",
+        neutral_hue="stone",
+        radius_size="lg",
+        font=[gr.themes.GoogleFont("Fredoka"), "ui-sans-serif", "system-ui", "sans-serif"],
+    ).set(
+        body_background_fill="#FFFDF5",
+        body_background_fill_dark="#12131A",
+    )
+    demo.launch(
+        css=GLOBAL_CSS,
+        theme=theme,
+        allowed_paths=["assets", "data"],
+    )

data/gallery/csn-aterkrav-result.json

@@ -0,0 +1,11 @@
+{
+  "transcription": "CSN\nBeslut om återkrav\nStudiemedel höstterminen 2025\nDu har haft högre inkomst än du angav. Därför kräver CSN\ntillbaka en del av det studiemedel du fått.\nBelopp att återbetala: 15 600 kr\nSista betalningsdag: 31 december 2026\nLåntagarnummer: 555444\nDetta är ett kravbrev. Beloppet har förfallit till betalning.\nOm hela beloppet inte betalas senast sista betalningsdag\nlämnas skulden till Kronofogden för indrivning. Det kan leda\ntill utmätning av din lön eller egendom samt en\nbetalningsanmärkning som försvarar för dig att få lån,\nhyreskontrakt och abonnemang.\nCentrala studiestödsnämnden (CSN)",
+  "quip": "Your scholarship just turned into a debt collector’s dream — and it’s got a 2026 deadline.",
+  "tldr": "You owe 15,600 kr for a scholarship you received in autumn 2025 because your reported income was too low. The CSN demands payment by December 31, 2026. If you don’t pay, they’ll hand your debt over to the tax authority, which can garnish your wages or assets and block you from getting loans, leases, or subscriptions.",
+  "why": "You received a student grant (studiemedel) for autumn 2025, but your reported income was lower than your actual income. The Central Student Support Agency (CSN) is now demanding repayment of the difference — 15,600 kr — because they believe you were overpaid.",
+  "actions": "You must pay the 15,600 kr by December 31, 2026. If you cannot pay the full amount, you should contact the CSN to discuss payment plans or other options. Failure to pay may result in your debt being transferred to the tax authority (Kronofogden), which can garnish your wages or assets and prevent you from obtaining loans, leases, or subscriptions.",
+  "deadlines": "- 31 december 2026 — last day to pay the debt\n- 15 600 kr — amount owed\n- 555444 — loan account number (Låntagarnummer)",
+  "severity": 4,
+  "raw": "<transcription>\nCSN\nBeslut om återkrav\nStudiemedel höstterminen 2025\nDu har haft högre inkomst än du angav. Därför kräver CSN\ntillbaka en del av det studiemedel du fått.\nBelopp att återbetala: 15 600 kr\nSista betalningsdag: 31 december 2026\nLåntagarnummer: 555444\nDetta är ett kravbrev. Beloppet har förfallit till betalning.\nOm hela beloppet inte betalas senast sista betalningsdag\nlämnas skulden till Kronofogden för indrivning. Det kan leda\ntill utmätning av din lön eller egendom samt en\nbetalningsanmärkning som försvarar för dig att få lån,\nhyreskontrakt och abonnemang.\nCentrala studiestödsnämnden (CSN)\n</transcription>\nDOCTYPE: letter\nBureaucat says: Your scholarship just turned into a debt collector’s dream — and it’s got a 2026 deadline.\n## TL;DR\nYou owe 15,600 kr for a scholarship you received in autumn 2025 because your reported income was too low. The CSN demands payment by December 31, 2026. If you don’t pay, they’ll hand your debt over to the tax authority, which can garnish your wages or assets and block you from getting loans, leases, or subscriptions.\n## Why you got this\nYou received a student grant (studiemedel) for autumn 2025, but your reported income was lower than your actual income. The Central Student Support Agency (CSN) is now demanding repayment of the difference — 15,600 kr — because they believe you were overpaid.\n## What you need to do\nYou must pay the 15,600 kr by December 31, 2026. If you cannot pay the full amount, you should contact the CSN to discuss payment plans or other options. Failure to pay may result in your debt being transferred to the tax authority (Kronofogden), which can garnish your wages or assets and prevent you from obtaining loans, leases, or subscriptions.\n## Deadlines & money\n- 31 december 2026 — last day to pay the debt\n- 15 600 kr — amount owed\n- 555444 — loan account number (Låntagarnummer)\nSEVERITY: 4",
+  "doctype": "letter"
+}

data/gallery/forsakringskassan-komplettering-result.json

@@ -0,0 +1,11 @@
+{
+  "transcription": "Försäkringskassan\nBegäran om komplettering\nÄrende: bostadsbidrag\nPersonnummer: XXXXXX-XXXX\nVi kan inte fatta beslut om din ansökan om bostadsbidrag\neftersom underlag saknas. Du måste skicka in dina tre senaste\nlönespecifikationer.\nSista svarsdag: den 30 september 2026\nÄrendenummer: 9988776\nOm vi inte har fått dina uppgifter i tid kommer vi att avsluta\närendet utan beslut och din ansökan avslås.\nFörsäkringskassan",
+  "quip": "Your housing allowance application is on hold — send the docs or risk getting rejected.",
+  "tldr": "The Swedish Social Insurance Agency (Försäkringskassan) is asking you to submit your three most recent pay slips to process your housing allowance application. If you don’t send them by September 30, 2026, your application will be closed without a decision.",
+  "why": "Your housing allowance application (bostadsbidrag) is pending because the agency doesn’t have the required documentation — specifically, your three most recent pay slips (lönespecifikationer). Without these, they cannot make a decision.",
+  "actions": "Send your three most recent pay slips to Försäkringskassan. Make sure to include your personnummer (XXXXX-XXXX) and reference number (ärendenummer: 9988776) in your submission.",
+  "deadlines": "- den 30 september 2026 — last day to submit your documents; if you miss this, your application will be closed without a decision\n- 9988776 — case number (ärendenummer)",
+  "severity": 3,
+  "raw": "<transcription>\nFörsäkringskassan\nBegäran om komplettering\nÄrende: bostadsbidrag\nPersonnummer: XXXXXX-XXXX\nVi kan inte fatta beslut om din ansökan om bostadsbidrag\neftersom underlag saknas. Du måste skicka in dina tre senaste\nlönespecifikationer.\nSista svarsdag: den 30 september 2026\nÄrendenummer: 9988776\nOm vi inte har fått dina uppgifter i tid kommer vi att avsluta\närendet utan beslut och din ansökan avslås.\nFörsäkringskassan\n</transcription>\nDOCTYPE: letter\nBureaucat says: Your housing allowance application is on hold — send the docs or risk getting rejected.\n## TL;DR\nThe Swedish Social Insurance Agency (Försäkringskassan) is asking you to submit your three most recent pay slips to process your housing allowance application. If you don’t send them by September 30, 2026, your application will be closed without a decision.\n## Why you got this\nYour housing allowance application (bostadsbidrag) is pending because the agency doesn’t have the required documentation — specifically, your three most recent pay slips (lönespecifikationer). Without these, they cannot make a decision.\n## What you need to do\nSend your three most recent pay slips to Försäkringskassan. Make sure to include your personnummer (XXXXX-XXXX) and reference number (ärendenummer: 9988776) in your submission.\n## Deadlines & money\n- den 30 september 2026 — last day to submit your documents; if you miss this, your application will be closed without a decision\n- 9988776 — case number (ärendenummer)\nSEVERITY: 3",
+  "doctype": "letter"
+}

data/gallery/migrationsverket-uppehallstillstand-result.json

@@ -0,0 +1,11 @@
+{
+  "transcription": "Migrationsverket\nUppmaning att komplettera ansökan\nAnsökan om uppehållstillstånd\nDin ansökan om förlängt uppehållstillstånd kan inte handläggas utan ett giltigt pass. Du måste lämna in en kopia av ditt pass samt anställningsbevis.\nSenast den 15 augusti 2026\nDossiernummer: 12-345678\nDetta är en sista uppmaning. Om handlingarna inte kommer in senast ovanstående datum avslås din ansökan utan ytterligare påminnelse. Ett avslag innebär att du omedelbart förlorar din rätt att vistas i Sverige, blir skyldig att lämna landet och kan komma att utvisas. Ett avslag kan även leda till återreseförbud till hela Schengenområdet.\nMigrationsverket",
+  "quip": "Your visa extension is on life support — and the last warning buzzer is about to go off.",
+  "tldr": "This is your final warning from Migrationsverket to submit your visa extension documents (passport copy + employment proof) by August 15, 2026. Failure means automatic rejection, immediate loss of right to stay, deportation, and a Schengen ban.",
+  "why": "Your visa extension application is incomplete — you haven’t submitted a copy of your passport and employment proof. Migrationsverket has sent you this final notice because they can’t process your application without these documents.",
+  "actions": "Submit a copy of your passport and an employment proof document to Migrationsverket before August 15, 2026.",
+  "deadlines": "- 15 augusti 2026 — deadline to submit documents; failure means automatic rejection\n- 12-345678 — case number (dossiernummer)",
+  "severity": 5,
+  "raw": "<transcription>\nMigrationsverket\nUppmaning att komplettera ansökan\nAnsökan om uppehållstillstånd\nDin ansökan om förlängt uppehållstillstånd kan inte handläggas utan ett giltigt pass. Du måste lämna in en kopia av ditt pass samt anställningsbevis.\nSenast den 15 augusti 2026\nDossiernummer: 12-345678\nDetta är en sista uppmaning. Om handlingarna inte kommer in senast ovanstående datum avslås din ansökan utan ytterligare påminnelse. Ett avslag innebär att du omedelbart förlorar din rätt att vistas i Sverige, blir skyldig att lämna landet och kan komma att utvisas. Ett avslag kan även leda till återreseförbud till hela Schengenområdet.\nMigrationsverket\n</transcription>\nDOCTYPE: letter\nBureaucat says: Your visa extension is on life support — and the last warning buzzer is about to go off.\n## TL;DR\nThis is your final warning from Migrationsverket to submit your visa extension documents (passport copy + employment proof) by August 15, 2026. Failure means automatic rejection, immediate loss of right to stay, deportation, and a Schengen ban.\n## Why you got this\nYour visa extension application is incomplete — you haven’t submitted a copy of your passport and employment proof. Migrationsverket has sent you this final notice because they can’t process your application without these documents.\n## What you need to do\nSubmit a copy of your passport and an employment proof document to Migrationsverket before August 15, 2026.\n## Deadlines & money\n- 15 augusti 2026 — deadline to submit documents; failure means automatic rejection\n- 12-345678 — case number (dossiernummer)\nSEVERITY: 5",
+  "doctype": "letter"
+}

data/gallery/skatteverket-slutskattebesked-result.json

@@ -0,0 +1,11 @@
+{
+  "transcription": "Skatteverket\n\nSlutskattebesked inkomstår 2025\n\nTill: Anna Andersson\nPersonnummer: XXXXXX-XXXX\n\nDitt slutliga skattebesked är nu klart. Beräkningen visar att\ndu har betalat in för mycket skatt för inkomstår 2025. Du\nfår därför tillbaka pengar på skatten.\n\nBelopp att få tillbaka: 4 250 kr\nUtbetalningsdag: 12 november 2026\nReferensnummer: 1234567890\n\nBeloppet betalas ut automatiskt till det bankkonto du har\nanmält till Skatteverket. Du behöver inte göra någonting.\n\nMed vänlig hälsning, Skatteverket",
+  "quip": "You overpaid your taxes — Sweden’s version of a refund check, delivered with zero effort required.",
+  "tldr": "You overpaid your 2025 income tax, and Sweden’s Tax Agency (Skatteverket) will automatically refund you 4,250 kr on November 12, 2026. No action needed from you.",
+  "why": "This is your final tax assessment for 2025. The calculation shows you paid more tax than you owed, so you’re getting a refund.",
+  "actions": "Nothing. The refund will be automatically deposited into the bank account you registered with Skatteverket.",
+  "deadlines": "- 4 250 kr — amount to be refunded\n- 12 november 2026 — refund payment date\n- 1234567890 — reference number (Referensnummer)",
+  "severity": 1,
+  "raw": "<transcription>\nSkatteverket\n\nSlutskattebesked inkomstår 2025\n\nTill: Anna Andersson\nPersonnummer: XXXXXX-XXXX\n\nDitt slutliga skattebesked är nu klart. Beräkningen visar att\ndu har betalat in för mycket skatt för inkomstår 2025. Du\nfår därför tillbaka pengar på skatten.\n\nBelopp att få tillbaka: 4 250 kr\nUtbetalningsdag: 12 november 2026\nReferensnummer: 1234567890\n\nBeloppet betalas ut automatiskt till det bankkonto du har\nanmält till Skatteverket. Du behöver inte göra någonting.\n\nMed vänlig hälsning, Skatteverket\n</transcription>\nDOCTYPE: letter\nBureaucat says: You overpaid your taxes — Sweden’s version of a refund check, delivered with zero effort required.\n## TL;DR\nYou overpaid your 2025 income tax, and Sweden’s Tax Agency (Skatteverket) will automatically refund you 4,250 kr on November 12, 2026. No action needed from you.\n## Why you got this\nThis is your final tax assessment for 2025. The calculation shows you paid more tax than you owed, so you’re getting a refund.\n## What you need to do\nNothing. The refund will be automatically deposited into the bank account you registered with Skatteverket.\n## Deadlines & money\n- 4 250 kr — amount to be refunded\n- 12 november 2026 — refund payment date\n- 1234567890 — reference number (Referensnummer)\nSEVERITY: 1",
+  "doctype": "letter"
+}

data/gallery/vardcentral-kallelse-result.json

@@ -0,0 +1,11 @@
+{
+  "transcription": "Vårdcentral Centrum\n\nKallelse till besök\n\nTill: Erik Eriksson\n\nDu är välkommen på ett bokat besök hos din distriktssköterska\nför en hälsokontroll.\n\nTid: den 5 maj 2026 kl 10:30\nPatientavgift: 250 kr\nBokningsnummer: 778899\n\nOm du får förhinder, av- eller omboka senast 24 timmar innan,\nannars debiteras du avgiften ändå.\n\nVårdcentral Centrum",
+  "quip": "Your health check-up is booked — and your wallet is being gently reminded to pay up.",
+  "tldr": "You have a booked appointment with your district nurse for a health check-up on May 5, 2026, at 10:30. There’s a 250 kr patient fee, and you must cancel or reschedule at least 24 hours in advance to avoid being charged.",
+  "why": "This is a formal confirmation from Vårdcentral Centrum (Health Center Centrum) that you have a scheduled health check-up with your district nurse. It also includes the fee and cancellation policy.",
+  "actions": "- Attend your appointment on May 5, 2026, at 10:30.\n- If you cannot attend, cancel or reschedule at least 24 hours before the appointment to avoid being charged the fee.",
+  "deadlines": "- den 5 maj 2026 — appointment date\n- 250 kr — patient fee\n- 778899 — booking number (bokningsnummer)",
+  "severity": 2,
+  "raw": "<transcription>\nVårdcentral Centrum\n\nKallelse till besök\n\nTill: Erik Eriksson\n\nDu är välkommen på ett bokat besök hos din distriktssköterska\nför en hälsokontroll.\n\nTid: den 5 maj 2026 kl 10:30\nPatientavgift: 250 kr\nBokningsnummer: 778899\n\nOm du får förhinder, av- eller omboka senast 24 timmar innan,\nannars debiteras du avgiften ändå.\n\nVårdcentral Centrum\n</transcription>\nDOCTYPE: letter\nBureaucat says: Your health check-up is booked — and your wallet is being gently reminded to pay up.\n## TL;DR\nYou have a booked appointment with your district nurse for a health check-up on May 5, 2026, at 10:30. There’s a 250 kr patient fee, and you must cancel or reschedule at least 24 hours in advance to avoid being charged.\n\n## Why you got this\nThis is a formal confirmation from Vårdcentral Centrum (Health Center Centrum) that you have a scheduled health check-up with your district nurse. It also includes the fee and cancellation policy.\n\n## What you need to do\n- Attend your appointment on May 5, 2026, at 10:30.\n- If you cannot attend, cancel or reschedule at least 24 hours before the appointment to avoid being charged the fee.\n\n## Deadlines & money\n- den 5 maj 2026 — appointment date\n- 250 kr — patient fee\n- 778899 — booking number (bokningsnummer)\nSEVERITY: 2",
+  "doctype": "letter"
+}

data/letters/generate_synthetic_gold.py

@@ -0,0 +1,270 @@
+"""
+Synthetic gold-letter generator for the Phase 1 bake-off (Plan 01-04).
+
+These are SYNTHETIC, lower-fidelity gold letters (the builder opted to synthesize
+rather than supply real redacted letters). They exist to validate the EVAL-02
+harness end-to-end and lock a model — NOT as a high-fidelity production accuracy
+gate. Provenance is documented here and in the SUMMARY.
+
+Design contract that makes the gate reliable:
+  - Every `verbatim_swedish` value in a sidecar is the SAME Python string that is
+    rendered into the PNG. Recall (D-13) therefore cannot fail for transcription
+    reasons — only for genuine model extraction/formatting failures.
+  - Values are rendered on their own clearly-labelled lines so OCR is trivial.
+  - No real Swedish personnummer is rendered (PII hook compliance): the redacted
+    placeholder ``XXXXXX-XXXX`` is used.
+  - Authentic Swedish diacritics (å ä ö) are used throughout the body and sender
+    text so the bake-off exercises the model's diacritic OCR and the harness's
+    NFC normalization path end-to-end (WR-03). The matched verbatim_swedish
+    values are dates / amounts / reference numbers, which in Swedish contain no
+    diacritics — the diacritic load lands on the transcription/output haystack
+    that normalize() processes during the no-invention check.
+
+Run:  .venv/bin/python data/letters/generate_synthetic_gold.py
+Output: data/letters/public/<slug>.png  +  data/letters/public/<slug>.json
+"""
+
+import json
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+OUT_DIR = Path(__file__).resolve().parent / "public"
+
+# Page geometry (A4-ish portrait, generous margins for clean OCR)
+PAGE_W, PAGE_H = 1000, 1414
+MARGIN = 80
+TITLE_FONT_PATH = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
+BODY_FONT_PATH = "/System/Library/Fonts/Supplemental/Arial.ttf"
+
+
+def _font(path: str, size: int) -> ImageFont.FreeTypeFont:
+    return ImageFont.truetype(path, size)
+
+
+def render_letter(slug: str, sender: str, lines: list) -> None:
+    """Render `lines` (list of (text, kind) tuples) onto a white page PNG.
+
+    kind in {"title", "h", "body", "value", "gap"} controls font/spacing.
+    """
+    img = Image.new("RGB", (PAGE_W, PAGE_H), "white")
+    draw = ImageDraw.Draw(img)
+
+    title_font = _font(TITLE_FONT_PATH, 40)
+    head_font = _font(TITLE_FONT_PATH, 26)
+    body_font = _font(BODY_FONT_PATH, 24)
+    value_font = _font(TITLE_FONT_PATH, 26)
+
+    y = MARGIN
+    # Sender header band
+    draw.text((MARGIN, y), sender, fill="black", font=title_font)
+    y += 58
+    draw.line((MARGIN, y, PAGE_W - MARGIN, y), fill="black", width=2)
+    y += 30
+
+    for text, kind in lines:
+        if kind == "gap":
+            y += 24
+            continue
+        if kind == "title":
+            draw.text((MARGIN, y), text, fill="black", font=title_font)
+            y += 56
+        elif kind == "h":
+            draw.text((MARGIN, y), text, fill="black", font=head_font)
+            y += 40
+        elif kind == "value":
+            draw.text((MARGIN, y), text, fill="black", font=value_font)
+            y += 40
+        else:  # body — naive wrap at ~62 chars
+            for chunk in _wrap(text, 62):
+                draw.text((MARGIN, y), chunk, fill="black", font=body_font)
+                y += 34
+
+    img.save(OUT_DIR / f"{slug}.png")
+
+
+def _wrap(text: str, width: int) -> list:
+    words, out, cur = text.split(), [], ""
+    for w in words:
+        if len(cur) + len(w) + 1 > width:
+            out.append(cur)
+            cur = w
+        else:
+            cur = f"{cur} {w}".strip()
+    if cur:
+        out.append(cur)
+    return out or [""]
+
+
+def write_sidecar(slug: str, gold: dict) -> None:
+    (OUT_DIR / f"{slug}.json").write_text(
+        json.dumps(gold, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Letter definitions. Each value used in `gold` is rendered verbatim below.
+# ---------------------------------------------------------------------------
+
+LETTERS = []
+
+# 1. Skatteverket — slutskattebesked, tax REFUND (good news, no action). Severity 1.
+LETTERS.append(dict(
+    slug="skatteverket-slutskattebesked",
+    sender="Skatteverket",
+    lines=[
+        ("Slutskattebesked inkomståret 2025", "title"),
+        ("Till: Anna Andersson", "body"),
+        ("Personnummer: XXXXXX-XXXX", "body"),
+        ("", "gap"),
+        ("Ditt slutliga skattebesked är nu klart. Beräkningen visar att du "
+         "har betalat in för mycket skatt för inkomståret 2025. Du får "
+         "därför tillbaka pengar på skatten.", "body"),
+        ("", "gap"),
+        ("Belopp att få tillbaka: 4 250 kr", "value"),
+        ("Utbetalningsdag: 12 november 2026", "value"),
+        ("Referensnummer: 1234567890", "value"),
+        ("", "gap"),
+        ("Beloppet betalas ut automatiskt till det bankkonto du har anmält "
+         "till Skatteverket. Du behöver inte göra någonting.", "body"),
+        ("", "gap"),
+        ("Med vänlig hälsning, Skatteverket", "body"),
+    ],
+    gold=dict(
+        expected_severity=1,
+        deadlines=[{"verbatim_swedish": "12 november 2026", "meaning": "utbetalningsdag för skatteåterbäring"}],
+        amounts=[{"verbatim_swedish": "4 250 kr", "meaning": "belopp att få tillbaka"}],
+        references=[{"verbatim_swedish": "1234567890", "meaning": "referensnummer"}],
+    ),
+))
+
+# 2. Försäkringskassan — begäran om komplettering, benefit at risk. Severity 3.
+LETTERS.append(dict(
+    slug="forsakringskassan-komplettering",
+    sender="Försäkringskassan",
+    lines=[
+        ("Begäran om komplettering", "title"),
+        ("Ärende: bostadsbidrag", "body"),
+        ("Personnummer: XXXXXX-XXXX", "body"),
+        ("", "gap"),
+        ("Vi kan inte fatta beslut om din ansökan om bostadsbidrag eftersom "
+         "underlag saknas. Du måste skicka in dina tre senaste lönespecifikationer.", "body"),
+        ("", "gap"),
+        ("Sista svarsdag: den 30 september 2026", "value"),
+        ("Ärendenummer: 9988776", "value"),
+        ("", "gap"),
+        ("Om vi inte har fått dina uppgifter i tid kommer vi att avsluta "
+         "ärendet utan beslut och din ansökan avslås.", "body"),
+        ("", "gap"),
+        ("Försäkringskassan", "body"),
+    ],
+    gold=dict(
+        expected_severity=3,
+        deadlines=[{"verbatim_swedish": "30 september 2026", "meaning": "sista svarsdag för komplettering"}],
+        amounts=[],
+        references=[{"verbatim_swedish": "9988776", "meaning": "ärendenummer"}],
+    ),
+))
+
+# 3. Migrationsverket — uppmaning, residence permit. Severity 5.
+LETTERS.append(dict(
+    slug="migrationsverket-uppehallstillstand",
+    sender="Migrationsverket",
+    lines=[
+        ("Uppmaning att komplettera ansökan", "title"),
+        ("Ansökan om uppehållstillstånd", "body"),
+        ("", "gap"),
+        ("Din ansökan om förlängt uppehållstillstånd kan inte handläggas "
+         "utan ett giltigt pass. Du måste lämna in en kopia av ditt pass "
+         "samt anställningsbevis.", "body"),
+        ("", "gap"),
+        ("Senast den 15 augusti 2026", "value"),
+        ("Dossiernummer: 12-345678", "value"),
+        ("", "gap"),
+        ("Detta är en sista uppmaning. Om handlingarna inte kommer in senast "
+         "ovanstående datum avslås din ansökan utan ytterligare påminnelse. "
+         "Ett avslag innebär att du omedelbart förlorar din rätt att vistas i "
+         "Sverige, blir skyldig att lämna landet och kan komma att utvisas. "
+         "Ett avslag kan även leda till återreseförbud till hela Schengenområdet.", "body"),
+        ("", "gap"),
+        ("Migrationsverket", "body"),
+    ],
+    gold=dict(
+        expected_severity=5,
+        deadlines=[{"verbatim_swedish": "15 augusti 2026", "meaning": "deadline att lämna in pass"}],
+        amounts=[],
+        references=[{"verbatim_swedish": "12-345678", "meaning": "dossiernummer"}],
+    ),
+))
+
+# 4. CSN — återkrav of study allowance, debt-collection consequence. Severity 4.
+LETTERS.append(dict(
+    slug="csn-aterkrav",
+    sender="CSN",
+    lines=[
+        ("Beslut om återkrav", "title"),
+        ("Studiemedel höstterminen 2025", "body"),
+        ("", "gap"),
+        ("Du har haft högre inkomst än du angav. Därför kräver CSN tillbaka "
+         "en del av det studiemedel du fått.", "body"),
+        ("", "gap"),
+        ("Belopp att återbetala: 15 600 kr", "value"),
+        ("Sista betalningsdag: 31 december 2026", "value"),
+        ("Låntagarnummer: 555444", "value"),
+        ("", "gap"),
+        ("Detta är ett kravbrev. Beloppet har förfallit till betalning. Om "
+         "hela beloppet inte betalas senast sista betalningsdag lämnas skulden "
+         "till Kronofogden för indrivning. Det kan leda till utmätning av din "
+         "lön eller egendom samt en betalningsanmärkning som försvårar för dig "
+         "att få lån, hyreskontrakt och abonnemang.", "body"),
+        ("", "gap"),
+        ("Centrala studiestödsnämnden (CSN)", "body"),
+    ],
+    gold=dict(
+        expected_severity=4,
+        deadlines=[{"verbatim_swedish": "31 december 2026", "meaning": "sista betalningsdag för återkrav"}],
+        amounts=[{"verbatim_swedish": "15 600 kr", "meaning": "belopp att återbetala"}],
+        references=[{"verbatim_swedish": "555444", "meaning": "låntagarnummer"}],
+    ),
+))
+
+# 5. Vårdcentral — appointment reminder + patient fee. Severity 2.
+LETTERS.append(dict(
+    slug="vardcentral-kallelse",
+    sender="Vårdcentral Centrum",
+    lines=[
+        ("Kallelse till besök", "title"),
+        ("Till: Erik Eriksson", "body"),
+        ("", "gap"),
+        ("Du är välkommen på ett bokat besök hos din distriktssköterska "
+         "för en hälsokontroll.", "body"),
+        ("", "gap"),
+        ("Tid: den 5 maj 2026 kl 10:30", "value"),
+        ("Patientavgift: 250 kr", "value"),
+        ("Bokningsnummer: 778899", "value"),
+        ("", "gap"),
+        ("Om du får förhinder, av- eller omboka senast 24 timmar innan, "
+         "annars debiteras du avgiften ändå.", "body"),
+        ("", "gap"),
+        ("Vårdcentral Centrum", "body"),
+    ],
+    gold=dict(
+        expected_severity=2,
+        deadlines=[{"verbatim_swedish": "5 maj 2026", "meaning": "tid för bokat besök"}],
+        amounts=[{"verbatim_swedish": "250 kr", "meaning": "patientavgift"}],
+        references=[{"verbatim_swedish": "778899", "meaning": "bokningsnummer"}],
+    ),
+))
+
+
+def main() -> None:
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+    for letter in LETTERS:
+        render_letter(letter["slug"], letter["sender"], letter["lines"])
+        write_sidecar(letter["slug"], letter["gold"])
+        print(f"  wrote {letter['slug']}.png + .json")
+    print(f"Generated {len(LETTERS)} synthetic gold letters in {OUT_DIR}")
+
+
+if __name__ == "__main__":
+    main()

data/letters/public/adversarial/blurry_unreadable.json

@@ -0,0 +1,8 @@
+{
+  "fixture_type": "adversarial",
+  "expected_doctype": "unreadable",
+  "expected_severity": null,
+  "deadlines": [],
+  "amounts": [],
+  "references": []
+}

data/letters/public/adversarial/generate_adversarial_fixtures.py

@@ -0,0 +1,256 @@
+"""
+Adversarial fixture generator for Phase 3 TRUST-02/03/04 tests.
+
+Generates three unambiguously bad inputs using PIL only — no real PII.
+All images use generic placeholder content (no Swedish personnummer).
+
+Run from the project root:
+    .venv/bin/python data/letters/public/adversarial/generate_adversarial_fixtures.py
+
+Output (this directory):
+    blurry_unreadable.png       + blurry_unreadable.json       (DOCTYPE: unreadable)
+    non_letter_receipt.png      + non_letter_receipt.json       (DOCTYPE: not_letter)
+    non_swedish_english.png     + non_swedish_english.json      (DOCTYPE: non_swedish)
+
+PII safety: no real personnummer used anywhere.
+Manual image-redaction visual gate: these are programmatically generated synthetic
+images with no personal data — they cannot contain real PII by construction.
+"""
+
+import json
+import random
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFilter, ImageFont
+
+OUT_DIR = Path(__file__).resolve().parent
+
+# Page geometry matching the gold letter generator
+PAGE_W, PAGE_H = 1000, 1414
+
+TITLE_FONT_PATH = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
+BODY_FONT_PATH = "/System/Library/Fonts/Supplemental/Arial.ttf"
+
+
+def _font(path: str, size: int) -> ImageFont.FreeTypeFont:
+    try:
+        return ImageFont.truetype(path, size)
+    except OSError:
+        # Fallback for non-macOS environments
+        return ImageFont.load_default()
+
+
+def write_sidecar(slug: str, expected_doctype: str) -> None:
+    """Write the adversarial sidecar JSON (different schema from gold sidecars)."""
+    data = {
+        "fixture_type": "adversarial",
+        "expected_doctype": expected_doctype,
+        "expected_severity": None,
+        "deadlines": [],
+        "amounts": [],
+        "references": [],
+    }
+    (OUT_DIR / f"{slug}.json").write_text(
+        json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def generate_blurry_unreadable() -> None:
+    """
+    Generate blurry_unreadable.png — a heavily blurred, low-contrast noise image
+    with no legible text. Expected doctype: unreadable.
+
+    Approach: render faint text on a gray background, then apply multiple rounds
+    of Gaussian blur to make it completely illegible.
+    """
+    img = Image.new("RGB", (PAGE_W, PAGE_H), (180, 180, 180))  # Mid-gray background
+    draw = ImageDraw.Draw(img)
+
+    # Seeded RNG for reproducibility
+    rng = random.Random(42)
+
+    # Add some random noise patches to simulate a very dark/blurry scan
+    for _ in range(2000):
+        x = rng.randint(0, PAGE_W - 1)
+        y = rng.randint(0, PAGE_H - 1)
+        shade = rng.randint(120, 200)
+        draw.ellipse([x - 2, y - 2, x + 2, y + 2], fill=(shade, shade, shade))
+
+    # Add some extremely faint "text-like" marks that will be blurred into noise
+    body_font = _font(BODY_FONT_PATH, 20)
+    for row, text in enumerate([
+        "Lorem ipsum dolor sit amet consectetur",
+        "adipiscing elit sed do eiusmod tempor",
+        "incididunt ut labore et dolore magna",
+    ]):
+        draw.text((100, 200 + row * 40), text, fill=(130, 130, 130), font=body_font)
+
+    # Apply heavy Gaussian blur multiple times — makes everything illegible
+    for _ in range(8):
+        img = img.filter(ImageFilter.GaussianBlur(radius=6))
+
+    img.save(OUT_DIR / "blurry_unreadable.png")
+    write_sidecar("blurry_unreadable", "unreadable")
+    print("Generated: blurry_unreadable.png + blurry_unreadable.json")
+
+
+def generate_non_letter_receipt() -> None:
+    """
+    Generate non_letter_receipt.png — an obvious grocery receipt (NOT a letter).
+    Expected doctype: not_letter.
+
+    Uses generic placeholder content with no real PII, no real store name.
+    """
+    img = Image.new("RGB", (PAGE_W, PAGE_H), "white")
+    draw = ImageDraw.Draw(img)
+
+    title_font = _font(TITLE_FONT_PATH, 32)
+    body_font = _font(BODY_FONT_PATH, 22)
+    small_font = _font(BODY_FONT_PATH, 18)
+
+    MARGIN = 80
+    y = MARGIN
+
+    # Receipt header — looks NOTHING like an authority letter
+    draw.text((MARGIN, y), "STORE RECEIPT", fill="black", font=title_font)
+    y += 60
+    draw.text((MARGIN, y), "Generic Grocery AB", fill="black", font=body_font)
+    y += 36
+    draw.text((MARGIN, y), "Receipt no: 00042", fill="black", font=small_font)
+    y += 28
+    draw.text((MARGIN, y), "Date: 2026-05-15  Time: 14:32", fill="black", font=small_font)
+    y += 36
+
+    draw.line((MARGIN, y, PAGE_W - MARGIN, y), fill="black", width=1)
+    y += 20
+
+    # Item lines — clearly a grocery receipt
+    items = [
+        ("Milk 1L                         12.90"),
+        ("Bread (sourdough)               34.50"),
+        ("Cheese 500g                     49.90"),
+        ("Apples 1kg                      19.90"),
+        ("Pasta 500g                      15.50"),
+        ("Olive oil 500ml                 59.90"),
+        ("Yoghurt 400g                    18.50"),
+        ("Juice 1L                        22.90"),
+        ("Eggs 12-pack                    42.00"),
+        ("Butter 500g                     38.50"),
+    ]
+    for item in items:
+        draw.text((MARGIN, y), item, fill="black", font=body_font)
+        y += 34
+
+    draw.line((MARGIN, y, PAGE_W - MARGIN, y), fill="black", width=1)
+    y += 20
+
+    draw.text((MARGIN, y), "Subtotal:                      314.50", fill="black", font=body_font)
+    y += 34
+    draw.text((MARGIN, y), "VAT (25%):                      78.63", fill="black", font=body_font)
+    y += 34
+    draw.text((MARGIN, y), "TOTAL:                         393.13", fill="black", font=title_font)
+    y += 50
+
+    draw.line((MARGIN, y, PAGE_W - MARGIN, y), fill="black", width=1)
+    y += 20
+    draw.text((MARGIN, y), "Payment: Credit card", fill="black", font=small_font)
+    y += 28
+    draw.text((MARGIN, y), "Thank you for shopping with us!", fill="black", font=small_font)
+
+    img.save(OUT_DIR / "non_letter_receipt.png")
+    write_sidecar("non_letter_receipt", "not_letter")
+    print("Generated: non_letter_receipt.png + non_letter_receipt.json")
+
+
+def generate_non_swedish_english() -> None:
+    """
+    Generate non_swedish_english.png — a wholly English AUTHORITY LETTER.
+    Expected doctype: not_letter (see rationale below).
+
+    This fixture is a non-Swedish institutional LETTER (UK HMRC-style: letterhead, date,
+    recipient, salutation, body, sign-off), entirely in English, no Swedish, no real PII.
+    It exercises the realistic bad input of an expat uploading a letter from their home
+    country.
+
+    Expected doctype rationale (Phase-3 decision, builder-approved): the locked model
+    (Qwen3-VL-8B, greedy) classifies a non-Swedish *letter* as `not_letter`, not
+    `non_swedish`. Forcing the `non_swedish` distinction required a SYSTEM_PROMPT
+    decision-tree edit that deterministically regressed reference recall on real Swedish
+    letters (the project's #1 value), so it was reverted. `not_letter` and `non_swedish`
+    route to the IDENTICAL render_refusal (wrong_document mascot, no analysis), so TRUST-03
+    holds either way — only the refusal sub-copy differs. We therefore score this fixture's
+    refusal as `not_letter`. The `non_swedish` render path remains unit-tested directly in
+    tests/test_doctype_refusal.py. No Swedish text, no real PII, generic placeholders.
+    """
+    img = Image.new("RGB", (PAGE_W, PAGE_H), "white")
+    draw = ImageDraw.Draw(img)
+
+    head_font = _font(TITLE_FONT_PATH, 30)
+    sub_font = _font(BODY_FONT_PATH, 20)
+    body_font = _font(BODY_FONT_PATH, 22)
+
+    MARGIN = 80
+    y = MARGIN
+
+    # Letterhead — a non-Swedish (UK) government authority, entirely in English
+    draw.text((MARGIN, y), "HM Revenue & Customs", fill="black", font=head_font)
+    y += 42
+    draw.text((MARGIN, y), "National Insurance Contributions Office", fill="black", font=sub_font)
+    y += 30
+    draw.text((MARGIN, y), "Benton Park View, Newcastle upon Tyne, NE98 1ZZ", fill="black", font=sub_font)
+    y += 30
+    draw.text((MARGIN, y), "United Kingdom", fill="black", font=sub_font)
+    y += 50
+
+    # Date + recipient block — letter structure, not a form/bill
+    draw.text((MARGIN, y), "12 May 2026", fill="black", font=body_font)
+    y += 50
+    draw.text((MARGIN, y), "Mr A. Taylor", fill="black", font=body_font)
+    y += 32
+    draw.text((MARGIN, y), "14 Example Terrace", fill="black", font=body_font)
+    y += 32
+    draw.text((MARGIN, y), "Manchester, M1 2AB", fill="black", font=body_font)
+    y += 56
+
+    draw.text((MARGIN, y), "Dear Mr Taylor,", fill="black", font=body_font)
+    y += 44
+    draw.text((MARGIN, y), "Re: Your Self Assessment tax return for 2025/26", fill="black", font=body_font)
+    y += 50
+
+    body_lines = [
+        "We are writing to remind you that your Self Assessment tax",
+        "return for the year ending 5 April 2026 has not yet been",
+        "received. Our records show that you registered for Self",
+        "Assessment but have not submitted a completed return.",
+        "",
+        "Please complete and submit your return as soon as possible to",
+        "avoid a late-filing penalty. If you have already sent your",
+        "return, please disregard this letter.",
+        "",
+        "If you need help completing your return, you can find guidance",
+        "and contact details on our website. Please quote your reference",
+        "when you get in touch so we can deal with your enquiry quickly.",
+    ]
+    for line in body_lines:
+        draw.text((MARGIN, y), line, fill="black", font=body_font)
+        y += 34
+    y += 24
+
+    draw.text((MARGIN, y), "Yours sincerely,", fill="black", font=body_font)
+    y += 60
+    draw.text((MARGIN, y), "J. Morgan", fill="black", font=body_font)
+    y += 32
+    draw.text((MARGIN, y), "Customer Compliance Officer", fill="black", font=body_font)
+
+    img.save(OUT_DIR / "non_swedish_english.png")
+    write_sidecar("non_swedish_english", "not_letter")  # see docstring: model refuses as not_letter
+    print("Generated: non_swedish_english.png + non_swedish_english.json")
+
+
+if __name__ == "__main__":
+    generate_blurry_unreadable()
+    generate_non_letter_receipt()
+    generate_non_swedish_english()
+    print("\nAll adversarial fixtures generated successfully.")
+    print("Manual image-redaction visual gate: these are programmatically generated")
+    print("synthetic images with no real PII — confirmed clean by construction.")

data/letters/public/adversarial/non_letter_receipt.json

@@ -0,0 +1,8 @@
+{
+  "fixture_type": "adversarial",
+  "expected_doctype": "not_letter",
+  "expected_severity": null,
+  "deadlines": [],
+  "amounts": [],
+  "references": []
+}

data/letters/public/adversarial/non_swedish_english.json

@@ -0,0 +1,9 @@
+{
+  "fixture_type": "adversarial",
+  "expected_doctype": "non_swedish",
+  "accepted_doctypes": ["non_swedish", "not_letter"],
+  "expected_severity": null,
+  "deadlines": [],
+  "amounts": [],
+  "references": []
+}

data/letters/public/csn-aterkrav.json

@@ -0,0 +1,21 @@
+{
+  "expected_severity": 4,
+  "deadlines": [
+    {
+      "verbatim_swedish": "31 december 2026",
+      "meaning": "sista betalningsdag för återkrav"
+    }
+  ],
+  "amounts": [
+    {
+      "verbatim_swedish": "15 600 kr",
+      "meaning": "belopp att återbetala"
+    }
+  ],
+  "references": [
+    {
+      "verbatim_swedish": "555444",
+      "meaning": "låntagarnummer"
+    }
+  ]
+}

data/letters/public/forsakringskassan-komplettering.json

@@ -0,0 +1,16 @@
+{
+  "expected_severity": 3,
+  "deadlines": [
+    {
+      "verbatim_swedish": "30 september 2026",
+      "meaning": "sista svarsdag för komplettering"
+    }
+  ],
+  "amounts": [],
+  "references": [
+    {
+      "verbatim_swedish": "9988776",
+      "meaning": "ärendenummer"
+    }
+  ]
+}

data/letters/public/migrationsverket-uppehallstillstand.json

@@ -0,0 +1,16 @@
+{
+  "expected_severity": 5,
+  "deadlines": [
+    {
+      "verbatim_swedish": "15 augusti 2026",
+      "meaning": "deadline att lämna in pass"
+    }
+  ],
+  "amounts": [],
+  "references": [
+    {
+      "verbatim_swedish": "12-345678",
+      "meaning": "dossiernummer"
+    }
+  ]
+}

data/letters/public/skatteverket-slutskattebesked.json

@@ -0,0 +1,21 @@
+{
+  "expected_severity": 1,
+  "deadlines": [
+    {
+      "verbatim_swedish": "12 november 2026",
+      "meaning": "utbetalningsdag för skatteåterbäring"
+    }
+  ],
+  "amounts": [
+    {
+      "verbatim_swedish": "4 250 kr",
+      "meaning": "belopp att få tillbaka"
+    }
+  ],
+  "references": [
+    {
+      "verbatim_swedish": "1234567890",
+      "meaning": "referensnummer"
+    }
+  ]
+}

data/letters/public/vardcentral-kallelse.json

@@ -0,0 +1,21 @@
+{
+  "expected_severity": 2,
+  "deadlines": [
+    {
+      "verbatim_swedish": "5 maj 2026",
+      "meaning": "tid för bokat besök"
+    }
+  ],
+  "amounts": [
+    {
+      "verbatim_swedish": "250 kr",
+      "meaning": "patientavgift"
+    }
+  ],
+  "references": [
+    {
+      "verbatim_swedish": "778899",
+      "meaning": "bokningsnummer"
+    }
+  ]
+}

eval/cuda_parity.ipynb

@@ -0,0 +1,318 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "2b67e522",
+   "metadata": {},
+   "source": [
+    "# Bureaucat — CUDA A100 Parity Run\n",
+    "\n",
+    "**Purpose:** Confirm accuracy parity between local MPS (bfloat16) and A100 CUDA (bfloat16)\n",
+    "on the 5 gold English letters.\n",
+    "\n",
+    "**Scope:** 5 gold letters × English only — the hardware-numerics parity question.\n",
+    "Translation accuracy (5×5 matrix) is verified separately on local MPS.\n",
+    "\n",
+    "**Claims proved here:** zero invented values, recall == local MPS baseline on 5 English letters.\n",
+    "\n",
+    "**D-03 NOTE — DEFERRED:**\n",
+    "This notebook proves ACCURACY parity ONLY.\n",
+    "The D-03 gate (`<40s` inference latency AND `device=cuda` in the Space startup log)\n",
+    "requires a real ZeroGPU Space and is explicitly DEFERRED to Phase 5 (deploy day).\n",
+    "Nothing in this notebook closes D-03.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Prerequisites\n",
+    "- **Colab Pro A100 40GB runtime** (not T4 — model needs ~24-26 GB VRAM at bfloat16).\n",
+    "- If Colab schedules an L4 (22.5 GB) instead, the VRAM assertion in Cell 1 will fail.\n",
+    "  Reconnect runtime until you get an A100.\n",
+    "- bfloat16 only — 4-bit quantization is NOT used because it alters numerics and\n",
+    "  would undermine the parity claim."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14ae03ca",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 1: VRAM assertion — must pass before loading the model\n",
+    "# Colab Pro may schedule an L4 (22.5 GB) instead of A100 (40 GB).\n",
+    "# This assertion catches that case and fails cleanly rather than OOM-crashing mid-load.\n",
+    "\n",
+    "import torch\n",
+    "\n",
+    "assert torch.cuda.is_available(), \"No CUDA device found — start a GPU runtime\"\n",
+    "\n",
+    "vram_gb = torch.cuda.get_device_properties(0).total_memory / 1e9\n",
+    "device_name = torch.cuda.get_device_name(0)\n",
+    "\n",
+    "assert vram_gb >= 35, (\n",
+    "    f\"Insufficient VRAM: {vram_gb:.1f} GB on {device_name!r}.\\n\"\n",
+    "    f\"Need A100 40 GB (>=35 GB threshold). \"\n",
+    "    f\"Reconnect runtime to get an A100, or use Colab Pro+ with guaranteed A100 access.\\n\"\n",
+    "    f\"Do NOT fall back to 4-bit quantization — bfloat16 parity is the claim being tested.\"\n",
+    ")\n",
+    "\n",
+    "print(f\"VRAM check PASSED: {vram_gb:.1f} GB on {device_name!r}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fb712c5e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 2: Install the pinned Space stack and clone the repo\n",
+    "# Run this cell once per Colab session.\n",
+    "\n",
+    "# Install pinned Space requirements (torch 2.11.0 is the ZeroGPU-confirmed ceiling)\n",
+    "# Note: torch is already installed in Colab; we pin the inference-stack deps.\n",
+    "import subprocess, sys\n",
+    "\n",
+    "packages = [\n",
+    "    \"transformers==5.10.2\",\n",
+    "    \"accelerate==1.13.0\",\n",
+    "    \"qwen-vl-utils==0.0.14\",\n",
+    "    \"gradio==6.16.0\",\n",
+    "    \"spaces==0.50.4\",\n",
+    "    \"pypdfium2==5.9.0\",\n",
+    "    \"pillow>=10.0.0\",\n",
+    "]\n",
+    "subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"-q\"] + packages)\n",
+    "\n",
+    "print(\"Package install complete.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "96fa92df",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 2b: Clone the Bureaucat repo and add to sys.path\n",
+    "# Option A (recommended): clone from HF Hub or GitHub\n",
+    "#   !git clone https://huggingface.co/spaces/build-small-hackathon/bureaucat bureaucat\n",
+    "# Option B: upload the repo as a zip via the Colab file panel, then unzip.\n",
+    "# After cloning/uploading, set REPO_ROOT below and run this cell.\n",
+    "\n",
+    "import os, sys\n",
+    "\n",
+    "# --- Set this path after cloning/uploading the repo ---\n",
+    "REPO_ROOT = \"/content/bureaucat\"  # adjust if you uploaded to a different path\n",
+    "\n",
+    "if os.path.isdir(REPO_ROOT):\n",
+    "    if REPO_ROOT not in sys.path:\n",
+    "        sys.path.insert(0, REPO_ROOT)\n",
+    "    os.chdir(REPO_ROOT)\n",
+    "    print(f\"REPO_ROOT set to: {REPO_ROOT}\")\n",
+    "else:\n",
+    "    raise FileNotFoundError(\n",
+    "        f\"Repo not found at {REPO_ROOT!r}.\\n\"\n",
+    "        f\"Clone or upload the Bureaucat repo first, then update REPO_ROOT above.\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ba196e70",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 3: Load Qwen3-VL-8B-Instruct at bfloat16 on CUDA\n",
+    "# bfloat16 ONLY — not 4-bit. 4-bit would alter numerics and undermine the parity claim.\n",
+    "# The VRAM assertion in Cell 1 ensures we have enough headroom (~24-26 GB peak).\n",
+    "\n",
+    "import os\n",
+    "os.environ.setdefault(\"SPACE_ID\", \"\")  # prevent app.py from activating @spaces.GPU paths\n",
+    "\n",
+    "# Load via app.load_model which handles device detection and dtype\n",
+    "from app import load_model, MODEL_VARIANTS\n",
+    "\n",
+    "model_variant = \"qwen3\"  # Qwen/Qwen3-VL-8B-Instruct — MODEL-01 LOCKED\n",
+    "variant_cfg = MODEL_VARIANTS[model_variant]\n",
+    "image_patch_size = variant_cfg[\"image_patch_size\"]\n",
+    "\n",
+    "print(f\"Loading {model_variant} at bfloat16 on CUDA...\")\n",
+    "mdl, proc = load_model(model_variant)\n",
+    "\n",
+    "# Verify bfloat16 and CUDA placement\n",
+    "import torch\n",
+    "assert next(mdl.parameters()).dtype == torch.bfloat16, \"Model must be bfloat16\"\n",
+    "assert next(mdl.parameters()).device.type == \"cuda\", \"Model must be on CUDA\"\n",
+    "\n",
+    "print(f\"Model loaded: dtype={next(mdl.parameters()).dtype}, device={next(mdl.parameters()).device}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fe84bf49",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 4: Run 5 English-language passes on the 5 gold letters using the harness\n",
+    "# Reuses run_inference() + evaluate() from eval/run_eval.py (same harness as local MPS).\n",
+    "# Only English — CUDA parity is a hardware-numerics question, not a translation question.\n",
+    "\n",
+    "import json\n",
+    "from pathlib import Path\n",
+    "from PIL import Image\n",
+    "from app import run_inference\n",
+    "\n",
+    "# Add eval/ to path for run_eval imports\n",
+    "import sys\n",
+    "_eval_dir = str(Path(\"eval\").resolve())\n",
+    "if _eval_dir not in sys.path:\n",
+    "    sys.path.insert(0, _eval_dir)\n",
+    "\n",
+    "from run_eval import evaluate\n",
+    "\n",
+    "letter_dir = Path(\"data/letters/public\")\n",
+    "sidecars = sorted(letter_dir.glob(\"*.json\"))\n",
+    "\n",
+    "cuda_results = []\n",
+    "\n",
+    "for sidecar in sidecars:\n",
+    "    image_path = sidecar.with_suffix(\".png\")\n",
+    "    if not image_path.exists():\n",
+    "        image_path = sidecar.with_suffix(\".jpg\")\n",
+    "    if not image_path.exists():\n",
+    "        print(f\"[SKIP] {sidecar.stem}: no image\")\n",
+    "        continue\n",
+    "\n",
+    "    image = Image.open(image_path).convert(\"RGB\")\n",
+    "    gold = json.loads(sidecar.read_text())\n",
+    "\n",
+    "    result = run_inference(\n",
+    "        image, \"English\", beginner_mode=False,\n",
+    "        mdl=mdl, proc=proc, image_patch_size=image_patch_size,\n",
+    "    )\n",
+    "    verdict = evaluate(result, gold)\n",
+    "    cuda_results.append({\"letter\": sidecar.stem, \"verdict\": verdict})\n",
+    "\n",
+    "    status = \"PASS\" if verdict[\"pass\"] else \"FAIL\"\n",
+    "    print(\n",
+    "        f\"  {status} {sidecar.stem}: \"\n",
+    "        f\"recall={verdict['recall_rate']:.0%} \"\n",
+    "        f\"invented={verdict['invented_count']} \"\n",
+    "        f\"severity_mae={verdict['severity_mae']:.1f} \"\n",
+    "        f\"all_sections={verdict['all_sections_present']}\"\n",
+    "    )\n",
+    "\n",
+    "print(f\"\\n{len(cuda_results)} letters evaluated on CUDA A100.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec66dbad",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 5: Assert parity with local MPS baseline and print verdict table\n",
+    "# MPS baseline (from Phase 1 / 03-01 bake-off): 5/5 PASS, 0 invented, 100% recall.\n",
+    "# Assert: zero invented values + recall == 100% on all 5 letters.\n",
+    "\n",
+    "# --- MPS baseline (recorded from local Phase 1 bake-off run) ---\n",
+    "MPS_BASELINE = {\n",
+    "    \"skatteverket-slutskattebesked\":        {\"invented_count\": 0, \"recall_rate\": 1.0, \"pass\": True},\n",
+    "    \"migrationsverket-uppehallstillstand\":  {\"invented_count\": 0, \"recall_rate\": 1.0, \"pass\": True},\n",
+    "    \"forsakringskassan-komplettering\":      {\"invented_count\": 0, \"recall_rate\": 1.0, \"pass\": True},\n",
+    "    \"csn-aterkrav\":                         {\"invented_count\": 0, \"recall_rate\": 1.0, \"pass\": True},\n",
+    "    \"vardcentral-kallelse\":                 {\"invented_count\": 0, \"recall_rate\": 1.0, \"pass\": True},\n",
+    "}\n",
+    "\n",
+    "print(\"=\" * 60)\n",
+    "print(\"CUDA A100 vs MPS PARITY TABLE\")\n",
+    "print(\"=\" * 60)\n",
+    "print(f\"{'Letter':<44} {'CUDA':>5} {'MPS':>5} {'PARITY':>8}\")\n",
+    "print(\"-\" * 60)\n",
+    "\n",
+    "all_parity_ok = True\n",
+    "zero_invented = True\n",
+    "\n",
+    "for row in cuda_results:\n",
+    "    stem = row[\"letter\"]\n",
+    "    v = row[\"verdict\"]\n",
+    "    mps = MPS_BASELINE.get(stem, {})\n",
+    "\n",
+    "    cuda_recall = v[\"recall_rate\"]\n",
+    "    mps_recall = mps.get(\"recall_rate\", None)\n",
+    "    recall_match = (mps_recall is None) or (abs(cuda_recall - mps_recall) < 0.001)\n",
+    "\n",
+    "    parity_ok = v[\"invented_count\"] == 0 and recall_match\n",
+    "    all_parity_ok = all_parity_ok and parity_ok\n",
+    "    zero_invented = zero_invented and v[\"invented_count\"] == 0\n",
+    "\n",
+    "    cuda_str = f\"{cuda_recall:.0%}\"\n",
+    "    mps_str = f\"{mps_recall:.0%}\" if mps_recall is not None else \"n/a\"\n",
+    "    parity_str = \"OK\" if parity_ok else \"FAIL\"\n",
+    "    print(f\"  {stem:<42} {cuda_str:>5} {mps_str:>5} {parity_str:>8}\")\n",
+    "\n",
+    "print(\"-\" * 60)\n",
+    "print(f\"  Zero invented values: {'YES' if zero_invented else 'NO (FAIL)'}\")\n",
+    "print(f\"  Recall == MPS baseline ±0: {'YES' if all_parity_ok else 'NO (FAIL)'}\")\n",
+    "print()\n",
+    "\n",
+    "assert zero_invented, \"PARITY FAIL: CUDA run invented values not present in transcription\"\n",
+    "assert all_parity_ok, \"PARITY FAIL: CUDA recall does not match local MPS baseline\"\n",
+    "\n",
+    "print(\"PARITY VERDICT: PASS — zero invented, recall == MPS baseline on all 5 English letters.\")\n",
+    "print()\n",
+    "print(\"=\" * 60)\n",
+    "print(\"D-03 DEFERRAL NOTE\")\n",
+    "print(\"=\" * 60)\n",
+    "print(\"This notebook proves ACCURACY parity (zero invented, matched recall) ONLY.\")\n",
+    "print(\"The D-03 gate remains DEFERRED:\")\n",
+    "print(\"  - <40s per-inference latency: requires ZeroGPU Space measurement\")\n",
+    "print(\"  - device=cuda in startup log: requires real ZeroGPU Space deployment\")\n",
+    "print(\"Both will be verified in Phase 5 (deploy day). D-03 is NOT closed here.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a8741192",
+   "metadata": {},
+   "source": [
+    "## Results Recording\n",
+    "\n",
+    "After running all cells, record the results in the Phase 3 Plan 03 SUMMARY.md:\n",
+    "\n",
+    "| Letter | CUDA Recall | MPS Recall | Invented | Parity |\n",
+    "|--------|-------------|------------|----------|--------|\n",
+    "| (fill from Cell 5 output) | | | | |\n",
+    "\n",
+    "**Verdict:** PASS / FAIL  \n",
+    "**Runtime:** A100 40GB / [actual device from Cell 1]  \n",
+    "**D-03 status:** DEFERRED to Phase 5 (latency + device=cuda Space gate)\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Acknowledgements\n",
+    "\n",
+    "Model: `Qwen/Qwen3-VL-8B-Instruct` (MODEL-01 LOCKED, Phase 1 bake-off 2026-06-05)  \n",
+    "Harness: `eval/run_eval.py` (shared with local MPS runs)  \n",
+    "Gold set: `data/letters/public/*.json` (5 synthetic Swedish authority letters)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

eval/grounded.py

@@ -0,0 +1,146 @@
+"""
+eval/grounded.py — Shared grounded matching primitives for Bureaucat.
+
+Provides the no-invention check used by app.py (to drive the verifying mascot
+state, D2-05) and by eval/run_eval.py (for bake-off accuracy gating).
+
+Stdlib-only: only `re` and `unicodedata`. Importing this module never loads
+model weights and never imports app.
+"""
+
+# ---------------------------------------------------------------------------
+# Imports — stdlib only
+# ---------------------------------------------------------------------------
+
+import re
+import unicodedata
+
+
+# ---------------------------------------------------------------------------
+# Normalization (D-12)
+# Python 3 \s on str matches all Unicode whitespace:
+#   U+00A0 non-breaking space, U+2009 thin space, U+202F narrow no-break space,
+#   U+2007 figure space, U+3000 ideographic space — no literal chars needed.
+# ---------------------------------------------------------------------------
+
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def normalize(text: str) -> str:
+    """
+    Collapse all Unicode whitespace to single ASCII space; NFC-normalize; lowercase.
+
+    Preserves digits, commas, periods (Swedish decimal format), and kr suffix.
+    Purpose: makes OCR whitespace/case variance transparent to value_found().
+    """
+    # NFC normalize first — handles combining characters from OCR output
+    text = unicodedata.normalize("NFC", text)
+    # Collapse all Unicode whitespace variants to a single ASCII space
+    text = _WHITESPACE_RE.sub(" ", text)
+    # Lowercase and strip leading/trailing whitespace
+    return text.lower().strip()
+
+
+# ---------------------------------------------------------------------------
+# Value matching (D-12 no-invention, D-13 recall)
+# ---------------------------------------------------------------------------
+
+def value_found(gold_value: str, haystack: str) -> bool:
+    """
+    Check if gold_value appears in haystack using normalized substring match
+    with non-digit boundaries on both sides.
+
+    The digit boundary (`(?<!\\d)...(?!\\d)`) prevents a gold value from matching
+    INSIDE a longer run of digits — both for short refs (e.g. "123" inside
+    "1234567") AND for long values (e.g. ref "12-345678" must NOT match inside
+    "912-3456789", and ISO date "2026-06-15" must NOT match inside "12026-06-15").
+    Applying the boundary universally (not only when <6 digits) closes the
+    superstring hole that previously let a garbled longer number satisfy the
+    no-invention / recall gate (WR-01, D-12).
+
+    Legitimate values are always delimited by whitespace/punctuation in the
+    model's output, so the boundary never rejects a real match.
+    """
+    norm_gold = normalize(gold_value)
+    norm_hay = normalize(haystack)
+
+    pattern = r"(?<!\d)" + re.escape(norm_gold) + r"(?!\d)"
+    return bool(re.search(pattern, norm_hay))
+
+
+# ---------------------------------------------------------------------------
+# Value extraction from "Deadlines & money" section (D-12 no-invention)
+# ---------------------------------------------------------------------------
+
+def extract_values_from_section(section_text: str) -> list:
+    """
+    Extract emitted verbatim values from the "Deadlines & money" section.
+
+    Exploits the locked prompt's "one item per line, verbatim value first" format:
+      - 15 juni 2026 — last day to file
+      - 1 234 kr - belopp
+
+    For each line:
+      1. Strip leading bullet marker ('- ' or '* ' or bare '-' at start) and whitespace.
+      2. Skip blank lines and any "None found" lines.
+      3. Split on the first interpretation separator: ' — ' (em-dash) or ' - ' (hyphen
+         with surrounding spaces). The surrounding-spaces requirement prevents the
+         internal hyphens in ISO dates (e.g., 2026-06-15) from being split.
+      4. The text before the separator is the verbatim value; strip it.
+
+    Returns a list of verbatim value strings. Empty list if nothing matches.
+    """
+    values = []
+    for raw_line in section_text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        # Strip leading bullet markers (-, *, •) with optional trailing space
+        line = re.sub(r"^[-*•]\s*", "", line).strip()
+        if not line:
+            continue
+
+        # Skip "None found" variants (case-insensitive)
+        if re.match(r"none found\.?$", line, re.IGNORECASE):
+            continue
+
+        # Split on first interpretation separator:
+        #   ' — ' (em-dash, U+2014, with surrounding spaces)
+        #   ' – ' (en-dash, U+2013, with surrounding spaces — LLMs emit this constantly)
+        #   ' - ' (hyphen with surrounding spaces — requires spaces to avoid splitting dates)
+        # The surrounding-spaces requirement keeps internal ISO-date hyphens intact.
+        sep_match = re.search(r"\s+[—–\-]\s+", line)
+        if sep_match:
+            verbatim = line[: sep_match.start()].strip()
+        else:
+            # No separator found — the whole line is the verbatim value
+            verbatim = line
+
+        if verbatim:
+            values.append(verbatim)
+
+    return values
+
+
+# ---------------------------------------------------------------------------
+# No-invention check (D-12, D2-05 verifying mascot state)
+# ---------------------------------------------------------------------------
+
+def check_no_invention(result) -> list:
+    """
+    Returns list of values from result.deadlines that are NOT found verbatim
+    in result.transcription (the no-invention check, D-12).
+
+    Called from app.py to drive the verifying mascot state (D2-05).
+    Does NOT require a gold dict — safe to call on any real user letter.
+    Returns empty list = no invention detected.
+
+    Works on any SimpleNamespace or StructuredResult that has .deadlines
+    and .transcription attributes.
+    """
+    invented = []
+    for emitted_val in extract_values_from_section(result.deadlines):
+        if not value_found(emitted_val, result.transcription):
+            invented.append(emitted_val)
+    return invented

eval/regen_gallery.py

@@ -0,0 +1,161 @@
+"""
+eval/regen_gallery.py — Regenerate data/gallery/*-result.json from the five
+EXAMPLE_LETTERS images under the CURRENT SYSTEM_PROMPT (post-DOCTYPE, Phase 3).
+
+This is the mandatory D2-16 ripple-completion step: the old gallery JSONs were
+generated before Phase 3's SYSTEM_PROMPT change (DOCTYPE sentinel addition).
+After any prompt change, run this script to refresh the cached results.
+
+Usage:
+    python eval/regen_gallery.py [--model qwen3|qwen25]
+
+Requires model weights (will download from HF Hub if not cached).
+MPS / CUDA / CPU are all supported; ZeroGPU not required (no GPU quota cost on
+MPS — these are local synthetic letters).
+
+The script:
+  1. Loads EXAMPLE_LETTERS from app (the canonical list of slug/image/cached paths).
+  2. For each entry, runs run_inference() under the current SYSTEM_PROMPT in English.
+  3. Serializes ALL StructuredResult fields (matching run_eval's _fields tuple) to JSON.
+  4. Overwrites the existing data/gallery/*-result.json files.
+  5. Verifies each file deserializes cleanly via StructuredResult(**data) (round-trip).
+
+Ensures:
+  - All five gallery JSONs contain doctype == "letter" (normal letters).
+  - load_example()'s StructuredResult(**data) call succeeds without schema errors.
+  - The field set matches run_eval's _fields tuple (includes doctype).
+
+NOTE: py3langid is NOT used here (eval/regen_gallery.py is model-execution, not
+language-ID). No additional dependencies beyond the existing Space requirements.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Ensure project root is on sys.path so `from app import ...` resolves
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+# ---------------------------------------------------------------------------
+# Field set for serialization — matches run_eval's _fields tuple exactly
+# ---------------------------------------------------------------------------
+
+_FIELDS = (
+    "transcription",
+    "quip",
+    "tldr",
+    "why",
+    "actions",
+    "deadlines",
+    "severity",
+    "raw",
+    "doctype",
+)
+
+
+def regen_gallery(model_variant: str = "qwen3") -> bool:
+    """
+    Regenerate all five gallery JSONs under the current SYSTEM_PROMPT.
+
+    Returns True if all five JSONs were regenerated successfully with
+    doctype == "letter" and round-trip via StructuredResult(**data).
+    """
+    # Lazy import — keeps module importable without loading model weights
+    from app import (  # noqa: PLC0415
+        EXAMPLE_LETTERS,
+        StructuredResult,
+        load_model,
+        run_inference,
+        MODEL_VARIANTS,
+    )
+    from PIL import Image  # noqa: PLC0415
+
+    variant_cfg = MODEL_VARIANTS[model_variant]
+    image_patch_size = variant_cfg["image_patch_size"]
+
+    print(f"\n[regen_gallery] Loading model variant: {model_variant}")
+    mdl, proc = load_model(model_variant)
+
+    all_ok = True
+
+    for entry in EXAMPLE_LETTERS:
+        slug = entry["slug"]
+        image_path = Path(entry["image"])
+        cached_path = Path(entry["cached"])
+
+        if not image_path.exists():
+            print(f"  [SKIP] {slug}: image not found at {image_path}")
+            all_ok = False
+            continue
+
+        print(f"\n  [{slug}] Running inference...")
+        image = Image.open(image_path).convert("RGB")
+
+        result = run_inference(
+            image,
+            "English",
+            beginner_mode=False,
+            mdl=mdl,
+            proc=proc,
+            image_patch_size=image_patch_size,
+        )
+
+        # Serialize ALL StructuredResult fields matching _FIELDS (includes doctype)
+        data = {f: getattr(result, f) for f in _FIELDS}
+
+        # Verify doctype is "letter" (normal letters should always classify as letter)
+        if data.get("doctype") != "letter":
+            print(
+                f"  [WARN] {slug}: doctype={data.get('doctype')!r} — expected 'letter'. "
+                f"Check SYSTEM_PROMPT and model output."
+            )
+            # Continue — do not skip; overwrite anyway so the human can inspect
+
+        # Round-trip verification before writing: StructuredResult(**data) must not raise
+        try:
+            StructuredResult(**data)
+        except TypeError as exc:
+            print(f"  [ERROR] {slug}: StructuredResult(**data) round-trip failed: {exc}")
+            all_ok = False
+            continue
+
+        # Write JSON (utf-8, ensure_ascii=False to preserve Swedish diacritics)
+        cached_path.parent.mkdir(parents=True, exist_ok=True)
+        cached_path.write_text(
+            json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+
+        verdict = "OK" if data.get("doctype") == "letter" else "WARN"
+        print(
+            f"  [{verdict}] {slug}: written to {cached_path}  "
+            f"(doctype={data.get('doctype')!r}, severity={data.get('severity')!r})"
+        )
+
+    print(f"\n[regen_gallery] Done. all_ok={all_ok}")
+    return all_ok
+
+
+def _main():
+    parser = argparse.ArgumentParser(
+        description=(
+            "Regenerate data/gallery/*-result.json from EXAMPLE_LETTERS images "
+            "under the current SYSTEM_PROMPT (D2-16 mandatory after any prompt change)."
+        )
+    )
+    parser.add_argument(
+        "--model",
+        choices=["qwen3", "qwen25"],
+        default="qwen3",
+        help="Model variant to use for regeneration (default: qwen3)",
+    )
+    args = parser.parse_args()
+
+    ok = regen_gallery(args.model)
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    _main()

eval/run_eval.py

@@ -0,0 +1,493 @@
+"""
+EVAL-02 harness — Bureaucat bake-off evaluator.
+
+Usage:
+    python eval/run_eval.py [--model qwen3|qwen25] [--dump PATH]
+
+English-only product (2026-06-07 descope): Bureaucat reads Swedish letters and explains
+them in English. The gate runs two passes:
+  - Gold-letter accuracy (run_eval): anti-hallucination (D-12/D-13/D-14) + SC1 four-sections
+    completeness, each letter run standard + beginner (D-08 invariance).
+  - Adversarial refusal (run_adversarial_eval): the three bad-input fixtures must route to
+    the refusal path (correct doctype + no analysis rendered).
+Both must pass for exit 0. (The earlier 5x5 multilingual matrix and the py3langid prose-
+language assertion were retired with the English-only descope.)
+
+A gold letter passes only when:
+  - Pass A verdict passes (no-invention AND recall=100% AND all_sections_present AND severity)
+  - Pass B evaluate() verdict passes (same gate on beginner output)
+  - beginner_invariant(pass_B_result) holds (structural invariance, D-08)
+
+Severity MAE is reported but never fails the gate (D-15, advisory).
+
+Gate exits non-zero when ANY letter fails (either pass), the adversarial pass fails, or the
+gold set is empty.
+
+CRITICAL lazy-import contract:
+  - Stdlib-only at module top (json, re, unicodedata, argparse, pathlib, sys)
+  - `from app import ...` lives ONLY inside run_eval()/run_adversarial_eval() so importing
+    this module (e.g., for unit tests) never loads the model.
+"""
+
+import argparse
+import json
+import re
+import sys
+import unicodedata
+from pathlib import Path
+
+# Ensure project root is on sys.path so `from app import ...` resolves
+# whether this script is run as:
+#   python eval/run_eval.py          (cwd = project root)
+#   python run_eval.py               (cwd = eval/)
+#   python -m pytest eval/           (cwd = project root)
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+# Also ensure eval/ is on sys.path so `import grounded` resolves when
+# run_eval.py is imported from the project root (e.g. by test_eval_matching.py).
+_EVAL_DIR = str(Path(__file__).resolve().parent)
+if _EVAL_DIR not in sys.path:
+    sys.path.insert(0, _EVAL_DIR)
+
+# ---------------------------------------------------------------------------
+# Import matching primitives from shared module (D2-05 refactor).
+# Names re-bound here so existing `import run_eval as e; e.normalize(...)` calls
+# in eval/test_eval_matching.py continue to work without modification.
+# Use `from grounded import ...` (eval/ is on sys.path when running run_eval.py).
+# ---------------------------------------------------------------------------
+from grounded import normalize, value_found, extract_values_from_section  # noqa: F401
+
+
+# ---------------------------------------------------------------------------
+# Per-letter verdict (D-12, D-13, D-14, D-15, SC1)
+# ---------------------------------------------------------------------------
+
+def evaluate(result, gold: dict) -> dict:
+    """
+    Return a per-letter verdict dict for a StructuredResult-shaped object and gold dict.
+
+    No-invention check (D-12): every value extracted from result.deadlines must be
+    a normalized substring of result.transcription.
+
+    Recall check (D-13): every verbatim_swedish value from gold["deadlines"],
+    gold["amounts"], gold["references"] must appear in result.deadlines.
+
+    Four-sections completeness (SC1): tldr, why, actions, deadlines must all be non-empty.
+
+    Severity (D-15): MAE is computed and included; does NOT affect pass.
+
+    PASS = no-invention AND recall=100% AND severity is not None AND all_sections_present.
+
+    Works on any SimpleNamespace or StructuredResult — evaluate() does NOT import app.
+    """
+    # 1. No-invention check (D-12)
+    invented = []
+    for emitted_val in extract_values_from_section(result.deadlines):
+        if not value_found(emitted_val, result.transcription):
+            invented.append(emitted_val)
+
+    # 2. Recall check (D-13) — must extract verbatim_swedish string (Pitfall 9)
+    missing = []
+    for category_key in ("deadlines", "amounts", "references"):
+        for d in gold.get(category_key, []):
+            verbatim = d["verbatim_swedish"]
+            if not value_found(verbatim, result.deadlines):
+                missing.append(verbatim)
+
+    # 3. Four-sections completeness (SC1)
+    all_sections_present = all(
+        bool(getattr(result, f, None))
+        for f in ("tldr", "why", "actions", "deadlines")
+    )
+
+    # 4. Severity MAE (D-15, advisory — never fails gate)
+    severity = result.severity
+    if severity is not None:
+        sev_mae = abs(severity - gold["expected_severity"])
+    else:
+        sev_mae = 5.0  # sentinel: output truncated before SEVERITY line
+
+    # 5. Recall rate denominator
+    total_gold = sum(
+        len(gold.get(k, []))
+        for k in ("deadlines", "amounts", "references")
+    )
+
+    passed = (
+        len(invented) == 0
+        and len(missing) == 0
+        and severity is not None
+        and all_sections_present
+    )
+
+    return {
+        "pass": passed,
+        "invented_count": len(invented),
+        "invented": invented,
+        "missing_count": len(missing),
+        "missing": missing,
+        "recall_rate": 1.0 - len(missing) / max(total_gold, 1),
+        "severity_mae": sev_mae,
+        "schema_complete": severity is not None,
+        "all_sections_present": all_sections_present,
+    }
+
+
+# ---------------------------------------------------------------------------
+# D-08 beginner-mode structural invariance checker
+# ---------------------------------------------------------------------------
+
+def beginner_invariant(result) -> tuple:
+    """
+    Assert D-08 structural invariance on a beginner-mode StructuredResult.
+
+    Checks:
+      - All four section fields (tldr, why, actions, deadlines) are non-empty
+      - severity is not None (SEVERITY line still present and parseable)
+      - transcription is non-empty (transcription block still present)
+
+    Returns (ok: bool, reasons: list[str]).
+    ok=True if all invariants hold; False if any fail, with reasons listing each failure.
+    """
+    reasons = []
+
+    # Check all four section fields
+    for field in ("tldr", "why", "actions", "deadlines"):
+        if not bool(getattr(result, field, None)):
+            reasons.append(f"section '{field}' is empty in beginner-mode output (D-08 violation)")
+
+    # Check severity parseable
+    if result.severity is None:
+        reasons.append(
+            "severity is None in beginner-mode output — SEVERITY line dropped or truncated (D-08 violation)"
+        )
+
+    # Check transcription block present
+    if not bool(getattr(result, "transcription", None)):
+        reasons.append(
+            "transcription is empty in beginner-mode output — transcription block dropped (D-08 violation)"
+        )
+
+    return (len(reasons) == 0, reasons)
+
+
+# ---------------------------------------------------------------------------
+# Refusal scorer (Phase 3 TRUST-02/03/04) — called by slice 3 for adversarial fixtures
+# ---------------------------------------------------------------------------
+
+def _render_value(pane) -> str:
+    """Extract the text value from a render_result pane (gr.update dict or str)."""
+    if isinstance(pane, dict):
+        return str(pane.get("value", "") or "")
+    return str(pane or "")
+
+
+def evaluate_refusal(result, gold: dict, language: str = "English") -> dict:
+    """
+    Score a StructuredResult against an adversarial fixture sidecar.
+
+    Not evaluated with evaluate() — adversarial fixtures have no gold values to recall.
+    The pass criterion is the REAL TRUST-03 / SC1 guarantee — *the user is shown no
+    four-section analysis* — verified at the render layer, plus correct classification:
+      - result.doctype matches gold["expected_doctype"] (drives the refusal route)
+      - render_result(result) shows no Panic Meter (panic_html == "") and no analysis
+        in the why / actions / deadlines panes (render_refusal suppresses them)
+
+    Why not the old `result.tldr is empty` proxy: a readable non-Swedish *letter* can be
+    (and is) analysed by the model before the render layer suppresses it, so raw `tldr`
+    is legitimately non-empty even though the user correctly sees only a refusal. The old
+    proxy wrongly failed that case. tldr_empty is still reported, but ADVISORY only.
+
+    render_result is imported lazily (it is a pure function — no model — so it is safe
+    under BUREAUCAT_NO_MODEL=1, and this keeps module import of run_eval app-free).
+
+    Returns a dict matching evaluate()'s shape (for uniform handling in slice 3).
+    """
+    expected = gold.get("expected_doctype", "")
+    # A fixture may list several equally-correct refusal doctypes. A non-Swedish
+    # English letter, for instance, is a correct refusal whether the model labels it
+    # "non_swedish" (precise) or "not_letter" (generic) — both route to render_refusal
+    # and show the user no analysis. accepted_doctypes makes the gate robust to that
+    # benign drift across prompt tweaks; falls back to the single expected_doctype.
+    accepted = gold.get("accepted_doctypes") or [expected]
+    actual_doctype = getattr(result, "doctype", "letter")
+    doctype_correct = actual_doctype in accepted
+
+    from app import render_result  # lazy; pure fn, safe under BUREAUCAT_NO_MODEL=1
+    rendered = render_result(result, language)
+    panic_html = rendered[0]
+    no_analysis_rendered = (
+        panic_html == ""
+        and not _render_value(rendered[4]).strip()   # why
+        and not _render_value(rendered[5]).strip()   # actions
+        and not _render_value(rendered[6]).strip()   # deadlines
+    )
+
+    tldr_empty = not getattr(result, "tldr", None)  # advisory only
+
+    passed = doctype_correct and no_analysis_rendered
+    verdict = "refusal_correct" if passed else "refusal_wrong"
+
+    return {
+        "pass": passed,
+        "verdict": verdict,
+        "doctype": actual_doctype,
+        "expected_doctype": expected,
+        "doctype_correct": doctype_correct,
+        "no_analysis_rendered": no_analysis_rendered,
+        "tldr_empty": tldr_empty,  # advisory — model may legitimately analyse non-Swedish
+    }
+
+
+# ---------------------------------------------------------------------------
+# Bake-off runner — app contracts imported LAZILY inside this function only
+# ---------------------------------------------------------------------------
+
+def run_eval(
+    model_variant: str = "qwen3",
+    dump_path: str = None,
+) -> bool:
+    """
+    Run the bake-off harness for the given model variant and output language.
+
+    Imports app contracts lazily BELOW the empty-set guard ONLY:
+    load_model, run_inference, MODEL_VARIANTS — the ONLY place app is imported.
+
+    Iterates sorted data/letters/public/*.json sidecars. For each letter:
+      - Pass A (standard, beginner_mode=False): full evaluate() gate
+      - Pass B (beginner, beginner_mode=True): full evaluate() gate + beginner_invariant()
+
+    A letter PASSES only when both passes pass AND beginner_invariant holds.
+
+    The *language* parameter controls the output language passed to run_inference().
+    Default "English" preserves the existing single-language harness behaviour.
+
+    Exits non-zero (returns False) when any letter fails or gold set is empty.
+    The empty-set guard fires BEFORE the app import so no model weights are
+    downloaded/loaded when the gold set has not been populated yet.
+    """
+    # ------------------------------------------------------------------
+    # Guard: check gold set exists BEFORE importing app (which triggers
+    # load_model() at module scope unless BUREAUCAT_NO_MODEL=1 is set).
+    # This ensures `python eval/run_eval.py` on an empty gold set exits
+    # immediately with a clear message and no 16GB weight download.
+    # ------------------------------------------------------------------
+    letter_dir = Path("data/letters/public")
+    sidecars = sorted(letter_dir.glob("*.json"))
+
+    if not sidecars:
+        print(
+            f"\n[run_eval] ERROR: Gold set is empty — no .json sidecars in {letter_dir}.\n"
+            f"The bake-off gate cannot pass with zero letters (D-09).\n"
+            f"Add at least 5 annotated gold letters before running Plan 04 bake-off.\n"
+        )
+        return False
+
+    # LAZY IMPORT — app is only imported here, after the empty-set guard,
+    # so module-scope import of run_eval (for unit tests) never loads the
+    # 16GB+ model, AND an empty gold set exits cleanly with no download.
+    from app import load_model, run_inference, MODEL_VARIANTS  # noqa: PLC0415
+
+    # Load model once for the entire eval run
+    print(f"\n[run_eval] Loading model variant: {model_variant}")
+    variant_cfg = MODEL_VARIANTS[model_variant]
+    image_patch_size = variant_cfg["image_patch_size"]
+    mdl, proc = load_model(model_variant)
+
+    results = []
+    dump = {}  # letter_stem -> {"standard": {...fields}, "beginner": {...fields}}
+    for sidecar in sidecars:
+        # Find matching image (.png preferred, fallback .jpg)
+        image_path = sidecar.with_suffix(".png")
+        if not image_path.exists():
+            image_path = sidecar.with_suffix(".jpg")
+        if not image_path.exists():
+            print(f"  [SKIP] {sidecar.stem}: no matching image file")
+            continue
+
+        from PIL import Image
+        image = Image.open(image_path)
+        gold = json.loads(sidecar.read_text())
+
+        # Pass A: standard inference (English-only product — 2026-06-07 descope)
+        result_std = run_inference(
+            image, "English", beginner_mode=False,
+            mdl=mdl, proc=proc, image_patch_size=image_patch_size,
+        )
+        verdict_std = evaluate(result_std, gold)
+
+        # Pass B: beginner-mode inference (D-08 invariance check)
+        result_beg = run_inference(
+            image, "English", beginner_mode=True,
+            mdl=mdl, proc=proc, image_patch_size=image_patch_size,
+        )
+        verdict_beg = evaluate(result_beg, gold)
+        inv_ok, inv_reasons = beginner_invariant(result_beg)
+
+        if dump_path:
+            _fields = ("transcription", "quip", "tldr", "why", "actions", "deadlines", "severity", "raw", "doctype")
+            dump[sidecar.stem] = {
+                "standard": {f: getattr(result_std, f) for f in _fields},
+                "beginner": {f: getattr(result_beg, f) for f in _fields},
+            }
+
+        letter_pass = verdict_std["pass"] and verdict_beg["pass"] and inv_ok
+
+        # Per-letter output
+        status = "PASS" if letter_pass else "FAIL"
+        print(
+            f"\n  {status} {sidecar.stem}:\n"
+            f"    STANDARD: recall={verdict_std['recall_rate']:.0%}  "
+            f"invented={verdict_std['invented_count']}  "
+            f"severity_mae={verdict_std['severity_mae']:.1f}  "
+            f"all_sections={verdict_std['all_sections_present']}\n"
+            f"    BEGINNER: recall={verdict_beg['recall_rate']:.0%}  "
+            f"invented={verdict_beg['invented_count']}  "
+            f"severity_mae={verdict_beg['severity_mae']:.1f}  "
+            f"all_sections={verdict_beg['all_sections_present']}\n"
+            f"    BEGINNER_INVARIANT: {'OK' if inv_ok else 'FAIL(' + '; '.join(inv_reasons) + ')'}"
+        )
+        if not verdict_std["pass"]:
+            if verdict_std["invented"]:
+                print(f"    [STD] Invented values: {verdict_std['invented']}")
+            if verdict_std["missing"]:
+                print(f"    [STD] Missing gold values: {verdict_std['missing']}")
+        if not verdict_beg["pass"]:
+            if verdict_beg["invented"]:
+                print(f"    [BEG] Invented values: {verdict_beg['invented']}")
+            if verdict_beg["missing"]:
+                print(f"    [BEG] Missing gold values: {verdict_beg['missing']}")
+
+        results.append({
+            "letter": sidecar.stem,
+            "pass": letter_pass,
+        })
+
+    # Overall summary
+    n_pass = sum(1 for r in results if r["pass"])
+    n_total = len(results)
+    gate = n_pass == n_total and n_total > 0
+
+    print(f"\n=== EVAL RESULTS ({model_variant}) ===")
+    print(f"  Overall: {n_pass}/{n_total} letters passed both passes")
+    print(f"  GATE: {'PASS' if gate else 'FAIL'}")
+
+    if dump_path:
+        Path(dump_path).write_text(
+            json.dumps(dump, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        print(f"  Dumped raw model outputs for {len(dump)} letters to {dump_path}")
+
+    return gate
+
+
+# ---------------------------------------------------------------------------
+# Adversarial refusal scoring (Phase 3 TRUST-02/03/04)
+# ---------------------------------------------------------------------------
+
+def run_adversarial_eval(
+    model_variant: str = "qwen3",
+) -> tuple[bool, list[dict]]:
+    """
+    Score the three adversarial fixtures against the refusal gate.
+
+    Globs data/letters/public/adversarial/*.json — separate from the gold-letter
+    loop (glob("*.json") in run_eval is non-recursive so adversarial sidecars never
+    enter the EVAL-02 letter loop).
+
+    Loads the model lazily after the empty-set guard (mirrors run_eval discipline).
+    Runs each fixture in English only (adversarial path is not language-specific;
+    classification is always English-emitted via the DOCTYPE sentinel).
+
+    Returns (gate_pass: bool, verdicts: list[dict]).
+    """
+    adv_dir = Path("data/letters/public/adversarial")
+    adv_sidecars = sorted(adv_dir.glob("*.json"))
+
+    if not adv_sidecars:
+        print(
+            f"\n[run_adversarial_eval] WARNING: no adversarial fixtures in {adv_dir}.\n"
+            f"Skipping adversarial refusal scoring.\n"
+        )
+        return True, []
+
+    from app import load_model, run_inference, MODEL_VARIANTS  # noqa: PLC0415
+    from PIL import Image  # noqa: PLC0415
+
+    variant_cfg = MODEL_VARIANTS[model_variant]
+    image_patch_size = variant_cfg["image_patch_size"]
+    mdl, proc = load_model(model_variant)
+
+    verdicts = []
+    for sidecar in adv_sidecars:
+        image_path = sidecar.with_suffix(".png")
+        if not image_path.exists():
+            image_path = sidecar.with_suffix(".jpg")
+        if not image_path.exists():
+            print(f"  [SKIP-ADV] {sidecar.stem}: no matching image file")
+            continue
+
+        image = Image.open(image_path)
+        gold = json.loads(sidecar.read_text())
+
+        result = run_inference(
+            image, "English", beginner_mode=False,
+            mdl=mdl, proc=proc, image_patch_size=image_patch_size,
+        )
+        verdict = evaluate_refusal(result, gold)
+        verdict["letter"] = sidecar.stem
+        verdicts.append(verdict)
+
+        status = "PASS" if verdict["pass"] else "FAIL"
+        print(
+            f"\n  {status} [ADV] {sidecar.stem}:\n"
+            f"    verdict={verdict['verdict']}  "
+            f"doctype={verdict['doctype']!r}  expected={verdict['expected_doctype']!r}  "
+            f"tldr_empty={verdict['tldr_empty']}"
+        )
+
+    n_pass = sum(1 for v in verdicts if v["pass"])
+    n_total = len(verdicts)
+    gate = n_pass == n_total and n_total > 0
+
+    print(f"\n=== ADVERSARIAL RESULTS ({model_variant}) ===")
+    print(f"  Overall: {n_pass}/{n_total} adversarial fixtures scored refusal_correct")
+    print(f"  GATE: {'PASS' if gate else 'FAIL'}")
+
+    return gate, verdicts
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point — English-only gate (gold accuracy + adversarial refusal)
+# ---------------------------------------------------------------------------
+
+def _main():
+    parser = argparse.ArgumentParser(
+        description="Bureaucat evaluator — EVAL-02 gate (English-only product)"
+    )
+    parser.add_argument(
+        "--model",
+        choices=["qwen3", "qwen25"],
+        default="qwen3",
+        help="Model variant to evaluate (default: qwen3)",
+    )
+    parser.add_argument(
+        "--dump",
+        default=None,
+        metavar="PATH",
+        help="Write raw per-letter StructuredResult outputs to PATH (JSON) for "
+             "offline matching/gold iteration at zero GPU cost.",
+    )
+    args = parser.parse_args()
+
+    # English-only product (2026-06-07 descope): gold-letter accuracy gate +
+    # adversarial refusal gate. Both must pass.
+    gold_gate = run_eval(args.model, dump_path=args.dump)
+    adv_gate, _ = run_adversarial_eval(args.model)
+    sys.exit(0 if (gold_gate and adv_gate) else 1)
+
+
+if __name__ == "__main__":
+    _main()

eval/test_eval_matching.py

@@ -0,0 +1,475 @@
+"""
+Unit tests for eval/run_eval.py — matching primitives only.
+
+These tests import run_eval DIRECTLY (not via app) and never load model weights.
+No BUREAUCAT_NO_MODEL needed here because run_eval.py does NOT import app at
+module scope — only inside run_eval() (lazy import contract).
+
+Test coverage:
+  Task 1 primitives (normalize, value_found, extract_values_from_section):
+    - normalize: collapses NBSP, thin space, narrow no-break space, lowercases
+    - value_found: long ISO date found in transcription with surrounding text
+    - value_found short-value boundary: "123" NOT matched inside "1234567"
+    - value_found short-value boundary: "123" IS matched when standing alone
+    - value_found whitespace tolerance: gold with thin-space found in transcription
+    - extract_values_from_section: em-dash separator, strips bullets
+    - extract_values_from_section: hyphen-with-spaces separator
+    - extract_values_from_section: "None found." yields no values
+    - importability: 'app' not in sys.modules after importing run_eval
+      (checked in a standalone -c probe, not here — see verify block in plan)
+
+  Task 2 functions (evaluate, beginner_invariant):
+    - evaluate: clean result passes (invented=0, missing=0, all_sections_present, severity)
+    - evaluate: invented value (not in transcription) → pass=False
+    - evaluate: missing gold value (not in deadlines) → pass=False
+    - evaluate: empty section (tldr="") → pass=False even with zero invented/missing
+    - evaluate: severity MAE is computed but does not affect pass
+    - beginner_invariant: True when all fields present
+    - beginner_invariant: False when a section is empty
+    - beginner_invariant: False when severity is None
+    - beginner_invariant: False when transcription is empty
+"""
+
+import os
+import sys
+
+# Ensure project root and eval/ are on the path regardless of where pytest is run from.
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_EVAL_DIR = os.path.join(_REPO_ROOT, "eval")
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+if _EVAL_DIR not in sys.path:
+    sys.path.insert(0, _EVAL_DIR)
+
+import run_eval as e
+from types import SimpleNamespace as S
+
+
+# ---------------------------------------------------------------------------
+# Task 1 primitive tests: normalize
+# ---------------------------------------------------------------------------
+
+def test_normalize_case_insensitive():
+    """normalize lowercases input."""
+    assert e.normalize("1 234,56 KR") == e.normalize("1 234,56 kr")
+
+
+def test_normalize_collapses_nbsp():
+    """U+00A0 non-breaking space collapsed to ASCII space."""
+    #   between digits, as OCR might produce
+    text_with_nbsp = "1 234 kr"
+    text_plain = "1 234 kr"
+    assert e.normalize(text_with_nbsp) == e.normalize(text_plain)
+
+
+def test_normalize_collapses_thin_space():
+    """U+2009 thin space collapsed to ASCII space."""
+    text_thin = "1 234 kr"
+    text_plain = "1 234 kr"
+    assert e.normalize(text_thin) == e.normalize(text_plain)
+
+
+def test_normalize_collapses_narrow_nobreak():
+    """U+202F narrow no-break space collapsed to ASCII space."""
+    text_narrow = "1 234 kr"
+    text_plain = "1 234 kr"
+    assert e.normalize(text_narrow) == e.normalize(text_plain)
+
+
+def test_normalize_nfc():
+    """NFC normalization handles combining characters from OCR."""
+    # e + combining acute = é (NFC)
+    composed = "é"     # é
+    decomposed = "é"  # e + combining acute
+    assert e.normalize(decomposed) == e.normalize(composed)
+
+
+def test_normalize_collapses_multiple_spaces():
+    """Multiple spaces (including mixed Unicode) collapse to single space."""
+    assert e.normalize("a   b") == "a b"
+    assert e.normalize("a   b") == "a b"
+
+
+# ---------------------------------------------------------------------------
+# Task 1 primitive tests: value_found
+# ---------------------------------------------------------------------------
+
+def test_value_found_long_date_in_transcription():
+    """An ISO date (>= 6 digits) is found when present with surrounding text."""
+    haystack = "Du ska betala senast 2026-06-15. Glöm inte."
+    assert e.value_found("2026-06-15", haystack) is True
+
+
+def test_value_found_long_date_absent():
+    """A date not in the transcription is not found."""
+    haystack = "Du ska betala senast 2026-06-15."
+    assert e.value_found("2026-07-99", haystack) is False
+
+
+def test_value_found_short_boundary_inside_longer():
+    """A 3-digit ref "123" is NOT found inside "1234567" (boundary rule, Pitfall 5)."""
+    haystack = "ref 1234567 i systemet"
+    assert e.value_found("123", haystack) is False
+
+
+def test_value_found_short_boundary_standalone():
+    """A 3-digit ref "123" IS found when it stands alone."""
+    haystack = "OCR-nummer 123 gäller"
+    assert e.value_found("123", haystack) is True
+
+
+def test_value_found_short_boundary_at_start():
+    """A 3-digit ref at the start of the string is found."""
+    haystack = "123 är ditt referensnummer"
+    assert e.value_found("123", haystack) is True
+
+
+def test_value_found_whitespace_tolerance():
+    """Gold "1 234 kr" (thin space) is found in transcription with plain space."""
+    haystack = "belopp 1 234 kr forfaller 2026-06-15"
+    # Gold may have thin space; haystack has plain space — both normalize
+    assert e.value_found("1 234 kr", haystack) is True
+
+
+def test_value_found_case_insensitive():
+    """Match is case-insensitive (normalize lowercases)."""
+    assert e.value_found("JUNI", "betala i juni 2026") is True
+
+
+def test_value_found_not_found_returns_false():
+    """A value genuinely absent from haystack returns False."""
+    assert e.value_found("2026-12-31", "betala senast 2026-06-15") is False
+
+
+def test_value_found_six_digit_reference_uses_plain_substring():
+    """A 6+ digit reference uses plain normalized substring (no boundary required)."""
+    # "123456789" has 9 digits (>= 6) — substring match, no boundary needed
+    assert e.value_found("123456789", "OCR: 123456789") is True
+
+
+def test_value_found_long_value_not_matched_inside_longer_digit_run():
+    """WR-01: a value must NOT match inside a longer run of digits, regardless of
+    digit count — the non-digit boundary is applied universally."""
+    # 6-digit value inside a 7-digit run — must NOT match
+    assert e.value_found("123456", "ref 1234567") is False
+    # 8-digit reference must NOT match as a superstring (the WR-01 case)
+    assert e.value_found("12-345678", "ref 912-3456789") is False
+    # ISO date must NOT match inside a longer leading-digit run
+    assert e.value_found("2026-06-15", "x12026-06-15") is False
+    # ...but the same values DO match when properly delimited
+    assert e.value_found("123456", "ref 123456 end") is True
+    assert e.value_found("12-345678", "dossier 12-345678.") is True
+    assert e.value_found("2026-06-15", "senast 2026-06-15") is True
+
+
+# ---------------------------------------------------------------------------
+# Task 1 primitive tests: extract_values_from_section
+# ---------------------------------------------------------------------------
+
+def test_extract_em_dash_separator():
+    """Em-dash separator lines: verbatim value before ' — '."""
+    section = "- 15 juni 2026 — last day to file\n- 1 234 kr — amount owed"
+    vals = e.extract_values_from_section(section)
+    assert vals == ["15 juni 2026", "1 234 kr"]
+
+
+def test_extract_hyphen_with_spaces_separator():
+    """Hyphen-with-spaces separator lines: verbatim value before ' - '."""
+    section = "- 2026-06-15 - sista betalningsdag\n- 1 234 kr - fakturabelopp"
+    vals = e.extract_values_from_section(section)
+    assert vals == ["2026-06-15", "1 234 kr"]
+
+
+def test_extract_none_found_yields_empty():
+    """'None found.' line (and variants) yields no values."""
+    assert e.extract_values_from_section("None found.") == []
+    assert e.extract_values_from_section("none found.") == []
+    assert e.extract_values_from_section("None found") == []
+
+
+def test_extract_blank_lines_skipped():
+    """Blank lines between entries are skipped."""
+    section = "\n- 2026-06-15 — sista dag\n\n- 1 234 kr — belopp\n"
+    vals = e.extract_values_from_section(section)
+    assert vals == ["2026-06-15", "1 234 kr"]
+
+
+def test_extract_date_with_internal_hyphens_preserved():
+    """ISO date 2026-06-15 is not split by internal hyphens — only ' - ' with spaces."""
+    section = "- 2026-06-15 — sista dag"
+    vals = e.extract_values_from_section(section)
+    assert vals == ["2026-06-15"]
+
+
+def test_extract_mixed_separators():
+    """Mixed em-dash and hyphen-space separators in same section."""
+    section = "- 15 juni 2026 — sista dag\n- 1 234 kr - belopp"
+    vals = e.extract_values_from_section(section)
+    assert vals == ["15 juni 2026", "1 234 kr"]
+
+
+def test_extract_empty_section_yields_empty():
+    """Empty section string yields empty list."""
+    assert e.extract_values_from_section("") == []
+
+
+# ---------------------------------------------------------------------------
+# Task 2 tests: evaluate (SimpleNamespace stand-ins — no app import)
+# ---------------------------------------------------------------------------
+
+def _gold(
+    deadlines=None, amounts=None, references=None, expected_severity=4
+):
+    """Helper: build a gold dict with the pattern-6 sidecar schema."""
+    return {
+        "expected_severity": expected_severity,
+        "deadlines": deadlines or [],
+        "amounts": amounts or [],
+        "references": references or [],
+    }
+
+
+def _good_result():
+    """A fully-populated StructuredResult stand-in that should PASS."""
+    return S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="You must pay.",
+        why="You owe money.",
+        actions="Pay the invoice.",
+        deadlines="- 2026-06-15 — sista dag\n- 1 234 kr — belopp",
+        severity=4,
+    )
+
+
+def test_evaluate_clean_result_passes():
+    """A clean, complete result passes all gate checks."""
+    gold = _gold(
+        deadlines=[{"verbatim_swedish": "2026-06-15"}],
+        amounts=[{"verbatim_swedish": "1 234 kr"}],
+    )
+    v = e.evaluate(_good_result(), gold)
+    assert v["pass"] is True
+    assert v["invented_count"] == 0
+    assert v["missing_count"] == 0
+    assert v["all_sections_present"] is True
+
+
+def test_evaluate_invented_value_fails():
+    """A value in deadlines section absent from transcription → pass=False."""
+    result = S(
+        transcription="betala senast 2026-06-15",  # "2026-07-99" NOT in transcription
+        tldr="You must pay.",
+        why="Because.",
+        actions="Pay it.",
+        deadlines="- 2026-07-99 — invented\n- 2026-06-15 — real",
+        severity=4,
+    )
+    gold = _gold(deadlines=[{"verbatim_swedish": "2026-06-15"}])
+    v = e.evaluate(result, gold)
+    assert v["pass"] is False
+    assert v["invented_count"] >= 1
+
+
+def test_evaluate_missing_gold_value_fails():
+    """A gold verbatim_swedish value absent from deadlines section → pass=False."""
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="You must pay.",
+        why="Because.",
+        actions="Pay it.",
+        # "1 234 kr" is NOT in this deadlines section
+        deadlines="- 2026-06-15 — sista dag",
+        severity=4,
+    )
+    gold = _gold(
+        deadlines=[{"verbatim_swedish": "2026-06-15"}],
+        amounts=[{"verbatim_swedish": "1 234 kr"}],
+    )
+    v = e.evaluate(result, gold)
+    assert v["pass"] is False
+    assert v["missing_count"] >= 1
+
+
+def test_evaluate_empty_section_fails_sc1():
+    """
+    SC1 gate: an empty TL;DR section → pass=False even with zero invented/missing
+    and a valid severity.
+    """
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="",            # EMPTY — SC1 failure
+        why="Because.",
+        actions="Pay it.",
+        deadlines="- 2026-06-15 — sista dag\n- 1 234 kr — belopp",
+        severity=4,
+    )
+    gold = _gold(
+        deadlines=[{"verbatim_swedish": "2026-06-15"}],
+        amounts=[{"verbatim_swedish": "1 234 kr"}],
+    )
+    v = e.evaluate(result, gold)
+    assert v["pass"] is False
+    assert v["all_sections_present"] is False
+
+
+def test_evaluate_empty_deadlines_section_fails_sc1():
+    """An empty deadlines section → pass=False (SC1)."""
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        deadlines="",       # EMPTY deadlines — SC1
+        severity=4,
+    )
+    gold = _gold()          # No gold values — so 0 invented, 0 missing
+    v = e.evaluate(result, gold)
+    assert v["pass"] is False
+    assert v["all_sections_present"] is False
+
+
+def test_evaluate_severity_none_fails():
+    """severity=None → pass=False (schema_complete=False)."""
+    result = S(
+        transcription="betala 1 234 kr",
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        deadlines="- 1 234 kr — belopp",
+        severity=None,      # truncated output
+    )
+    gold = _gold(amounts=[{"verbatim_swedish": "1 234 kr"}])
+    v = e.evaluate(result, gold)
+    assert v["pass"] is False
+    assert v["schema_complete"] is False
+
+
+def test_evaluate_severity_mae_advisory_does_not_fail():
+    """Severity MAE is reported but does NOT cause pass=False (D-15)."""
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        deadlines="- 2026-06-15 — sista dag\n- 1 234 kr — belopp",
+        severity=1,         # severity=1 vs expected=4 → MAE=3
+    )
+    gold = _gold(
+        deadlines=[{"verbatim_swedish": "2026-06-15"}],
+        amounts=[{"verbatim_swedish": "1 234 kr"}],
+        expected_severity=4,
+    )
+    v = e.evaluate(result, gold)
+    # Large MAE but everything else is correct → PASS
+    assert v["pass"] is True
+    assert v["severity_mae"] == 3
+
+
+def test_evaluate_all_sections_present_in_verdict():
+    """all_sections_present key is always present in the verdict dict."""
+    v = e.evaluate(_good_result(), _gold())
+    assert "all_sections_present" in v
+
+
+def test_evaluate_references_checked_in_recall():
+    """References in gold sidecar are checked in the recall (deadlines section)."""
+    result = S(
+        transcription="betala 1 234 kr OCR 123456789",
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        # "123456789" is absent from deadlines
+        deadlines="- 1 234 kr — belopp",
+        severity=3,
+    )
+    gold = _gold(
+        amounts=[{"verbatim_swedish": "1 234 kr"}],
+        references=[{"verbatim_swedish": "123456789"}],
+    )
+    v = e.evaluate(result, gold)
+    assert v["pass"] is False
+    assert v["missing_count"] >= 1
+
+
+# ---------------------------------------------------------------------------
+# Task 2 tests: beginner_invariant
+# ---------------------------------------------------------------------------
+
+def test_beginner_invariant_fully_populated_passes():
+    """A fully-populated beginner-mode result passes all D-08 invariants."""
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        deadlines="- 2026-06-15 — sista dag\n- 1 234 kr — belopp",
+        severity=4,
+    )
+    ok, reasons = e.beginner_invariant(result)
+    assert ok is True
+    assert reasons == []
+
+
+def test_beginner_invariant_empty_section_fails():
+    """beginner_invariant returns False when a section is empty."""
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        tldr="",            # empty
+        why="Because.",
+        actions="Pay.",
+        deadlines="- 2026-06-15 — sista dag",
+        severity=4,
+    )
+    ok, reasons = e.beginner_invariant(result)
+    assert ok is False
+    assert len(reasons) >= 1
+
+
+def test_beginner_invariant_severity_none_fails():
+    """beginner_invariant returns False when severity is None (D-08: SEVERITY line dropped)."""
+    result = S(
+        transcription="betala 1 234 kr",
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        deadlines="- 1 234 kr — belopp",
+        severity=None,
+    )
+    ok, reasons = e.beginner_invariant(result)
+    assert ok is False
+    assert any("severity" in r.lower() for r in reasons)
+
+
+def test_beginner_invariant_empty_transcription_fails():
+    """beginner_invariant returns False when transcription is empty (D-08: block dropped)."""
+    result = S(
+        transcription="",   # empty transcription block
+        tldr="Summary.",
+        why="Because.",
+        actions="Pay.",
+        deadlines="- 2026-06-15 — sista dag",
+        severity=3,
+    )
+    ok, reasons = e.beginner_invariant(result)
+    assert ok is False
+    assert any("transcription" in r.lower() for r in reasons)
+
+
+def test_beginner_invariant_multiple_failures_all_reported():
+    """beginner_invariant reports ALL failures, not just the first."""
+    result = S(
+        transcription="",   # empty
+        tldr="",            # empty
+        why="Because.",
+        actions="Pay.",
+        deadlines="d",
+        severity=None,
+    )
+    ok, reasons = e.beginner_invariant(result)
+    assert ok is False
+    assert len(reasons) >= 2  # at least transcription + severity
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])

eval/test_grounded.py

@@ -0,0 +1,166 @@
+"""
+Unit tests for eval/grounded.py — shared matching primitives + check_no_invention.
+
+These tests use the same sys.path bootstrap as test_eval_matching.py.
+No app import needed — grounded.py is stdlib-only.
+
+Test coverage:
+  - check_no_invention: returns [] when all deadline values appear verbatim in transcription
+  - check_no_invention: returns non-empty list when a deadline value is NOT in transcription
+  - normalize, value_found, extract_values_from_section: return identical results to known
+    cases from test_eval_matching (regression against moved functions)
+  - import run_eval still works after refactor (eval-compat regression)
+"""
+
+import os
+import sys
+
+# Ensure project root and eval/ are on the path regardless of where pytest is run from.
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_EVAL_DIR = os.path.join(_REPO_ROOT, "eval")
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+if _EVAL_DIR not in sys.path:
+    sys.path.insert(0, _EVAL_DIR)
+
+import grounded  # direct import (eval/ is on sys.path)
+from types import SimpleNamespace as S
+
+
+# ---------------------------------------------------------------------------
+# check_no_invention: no invented values — returns empty list
+# ---------------------------------------------------------------------------
+
+def test_check_no_invention_returns_empty_when_all_values_in_transcription():
+    """Returns [] when every deadline value appears verbatim in the transcription."""
+    result = S(
+        transcription="betala 1 234 kr senast 2026-06-15",
+        deadlines="- 2026-06-15 — sista dag\n- 1 234 kr — belopp",
+    )
+    invented = grounded.check_no_invention(result)
+    assert invented == []
+
+
+def test_check_no_invention_returns_nonempty_for_invented_value():
+    """Returns a non-empty list when a deadline value is NOT in transcription."""
+    result = S(
+        transcription="betala senast 2026-06-15",  # "2026-07-99" NOT in transcription
+        deadlines="- 2026-07-99 — invented date\n- 2026-06-15 — real date",
+    )
+    invented = grounded.check_no_invention(result)
+    assert len(invented) >= 1
+    assert "2026-07-99" in invented
+
+
+def test_check_no_invention_empty_deadlines_returns_empty():
+    """Empty deadlines section → no values extracted → returns []."""
+    result = S(
+        transcription="betala senast 2026-06-15",
+        deadlines="",
+    )
+    invented = grounded.check_no_invention(result)
+    assert invented == []
+
+
+def test_check_no_invention_none_found_returns_empty():
+    """'None found.' sentinel in deadlines → no values extracted → returns []."""
+    result = S(
+        transcription="informational letter",
+        deadlines="None found.",
+    )
+    invented = grounded.check_no_invention(result)
+    assert invented == []
+
+
+def test_check_no_invention_all_invented_returns_all():
+    """All values invented → all returned in invented list."""
+    result = S(
+        transcription="hej det här är ett informationsbrev",
+        deadlines="- 2099-01-01 — fake\n- 99 999 kr — fake amount",
+    )
+    invented = grounded.check_no_invention(result)
+    assert len(invented) == 2
+
+
+# ---------------------------------------------------------------------------
+# Regression: moved functions return identical results to test_eval_matching cases
+# ---------------------------------------------------------------------------
+
+def test_normalize_case_insensitive():
+    """normalize lowercases input (regression from test_eval_matching)."""
+    assert grounded.normalize("1 234,56 KR") == grounded.normalize("1 234,56 kr")
+
+
+def test_normalize_collapses_multiple_spaces():
+    """Multiple spaces collapse to single space."""
+    assert grounded.normalize("a   b") == "a b"
+
+
+def test_value_found_long_date_in_transcription():
+    """An ISO date is found when present."""
+    haystack = "Du ska betala senast 2026-06-15. Glöm inte."
+    assert grounded.value_found("2026-06-15", haystack) is True
+
+
+def test_value_found_short_boundary_inside_longer():
+    """A 3-digit ref is NOT found inside a longer run of digits."""
+    haystack = "ref 1234567 i systemet"
+    assert grounded.value_found("123", haystack) is False
+
+
+def test_value_found_short_boundary_standalone():
+    """A 3-digit ref IS found when standing alone."""
+    haystack = "OCR-nummer 123 gäller"
+    assert grounded.value_found("123", haystack) is True
+
+
+def test_extract_em_dash_separator():
+    """Em-dash separator: verbatim value before ' — '."""
+    section = "- 15 juni 2026 — last day to file\n- 1 234 kr — amount owed"
+    vals = grounded.extract_values_from_section(section)
+    assert vals == ["15 juni 2026", "1 234 kr"]
+
+
+def test_extract_hyphen_with_spaces_separator():
+    """Hyphen-with-spaces separator."""
+    section = "- 2026-06-15 - sista betalningsdag\n- 1 234 kr - fakturabelopp"
+    vals = grounded.extract_values_from_section(section)
+    assert vals == ["2026-06-15", "1 234 kr"]
+
+
+def test_extract_none_found_yields_empty():
+    """'None found.' lines yield no values."""
+    assert grounded.extract_values_from_section("None found.") == []
+
+
+def test_extract_date_with_internal_hyphens_preserved():
+    """ISO date is not split by internal hyphens."""
+    section = "- 2026-06-15 — sista dag"
+    vals = grounded.extract_values_from_section(section)
+    assert vals == ["2026-06-15"]
+
+
+# ---------------------------------------------------------------------------
+# Eval-compat regression: import run_eval still works after refactor
+# ---------------------------------------------------------------------------
+
+def test_import_run_eval_succeeds():
+    """import run_eval still works after the grounded.py refactor."""
+    import run_eval  # noqa: F401 — just checking importability
+    assert hasattr(run_eval, "normalize"), "run_eval.normalize must be re-bound"
+    assert hasattr(run_eval, "value_found"), "run_eval.value_found must be re-bound"
+    assert hasattr(run_eval, "extract_values_from_section"), (
+        "run_eval.extract_values_from_section must be re-bound"
+    )
+
+
+def test_run_eval_normalize_still_accessible_via_namespace():
+    """import run_eval as e; e.normalize(...) still resolves after refactor."""
+    import run_eval as e
+    # Same case as test_eval_matching.py lines 44-45
+    assert e.normalize("A  b") == "a b"
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])

eval/test_parse_output.py

@@ -0,0 +1,273 @@
+"""
+Unit tests for parse_output() and build_user_prompt() in app.py.
+
+These tests NEVER load model weights. The BUREAUCAT_NO_MODEL env var is set
+before app is imported so the module-scope load_model() call is skipped.
+Tests run in seconds (pure Python, no GPU required).
+
+Test coverage:
+  - Well-formed output → all fields populated, severity int
+  - Transcription isolation from displayed sections
+  - Truncated output (no SEVERITY line) → severity=None, no crash
+  - Non-English body with fixed English headings → language-invariance (Pitfall 3)
+  - Empty raw string → empty fields, severity=None, no exception
+  - SEVERITY regex tolerates trailing whitespace/newline
+  - build_user_prompt() beginner vs standard: structural invariance (D-08 unit guard)
+"""
+
+import os
+import sys
+
+# Set escape hatch BEFORE importing app so model weights are never downloaded.
+os.environ["BUREAUCAT_NO_MODEL"] = "1"
+
+# Ensure the project root is on the path when running from eval/
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import app
+from app import parse_output, build_user_prompt, StructuredResult
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+WELL_FORMED = """\
+<transcription>
+Faktura 2026-06-15
+Belopp: 1 234 kr
+OCR: 555666777
+</transcription>
+
+Bureaucat says: This invoice wants your money, and it's not even polite about it.
+
+## TL;DR
+You have received an invoice for 1 234 kr due on 2026-06-15.
+
+## Why you got this
+You purchased a service and this is the bill.
+
+## What you need to do
+- Pay the invoice by 2026-06-15
+- Use OCR number 555666777
+
+## Deadlines & money
+- 2026-06-15 - sista betalningsdag
+- 1 234 kr - fakturabelopp
+- 555666777 - OCR-nummer
+SEVERITY: 4"""
+
+NON_ENGLISH_BODY = """\
+<transcription>
+Skatteverket deklaration
+</transcription>
+
+Bureaucat says: The taxman cometh (and speaketh Swedish).
+
+## TL;DR
+आपको अपना कर विवरण जमा करना होगा।
+
+## Why you got this
+आप स्वीडिश करदाता हैं।
+
+## What you need to do
+- कर फार्म भरें
+
+## Deadlines & money
+- 15 जून 2026 - अंतिम तारीख
+SEVERITY: 3"""
+
+TRUNCATED = """\
+<transcription>
+Short letter
+</transcription>
+
+Bureaucat says: The suspense is killing me.
+
+## TL;DR
+This letter got cut off before the severity was emitted.
+
+## Why you got this
+Unknown - truncated."""
+
+ARABIC_BODY = """\
+<transcription>
+مكتوب
+</transcription>
+
+Bureaucat says: Even in Arabic, deadlines are stressful.
+
+## TL;DR
+محتوى عربي
+
+## Why you got this
+سبب عربي
+
+## What you need to do
+- إجراء عربي
+
+## Deadlines & money
+- 2026-07-01 - موعد أخير
+SEVERITY: 2"""
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+def test_well_formed_all_fields_populated():
+    """Well-formed output parses into fully-populated StructuredResult."""
+    r = parse_output(WELL_FORMED)
+    assert r.transcription, "transcription should be non-empty"
+    assert r.quip, "quip should be non-empty"
+    assert r.tldr, "tldr should be non-empty"
+    assert r.why, "why should be non-empty"
+    assert r.actions, "actions should be non-empty"
+    assert r.deadlines, "deadlines should be non-empty"
+    assert r.severity == 4, f"expected severity=4, got {r.severity}"
+    assert r.raw == WELL_FORMED
+
+
+def test_transcription_isolated_from_sections():
+    """
+    The <transcription> block is stripped from the displayed body (D-04):
+    - result.transcription contains the verbatim OCR text
+    - The XML <transcription> tags are NOT present in sections or quip
+    - Deadlines section can legitimately contain values that also appear in the
+      transcription (verbatim extraction is the goal); what we test is that the
+      raw transcription BLOCK itself is stripped from the displayed output
+    """
+    r = parse_output(WELL_FORMED)
+    # Transcription field is populated with OCR text
+    assert "1 234 kr" in r.transcription, "verbatim value must be in transcription field"
+    assert "Faktura" in r.transcription, "OCR text must be in transcription field"
+    # The <transcription> XML tags must not appear anywhere in the section fields
+    assert "<transcription>" not in r.tldr
+    assert "<transcription>" not in r.deadlines
+    assert "</transcription>" not in r.tldr
+    assert "</transcription>" not in r.deadlines
+    # The raw transcription block text (e.g., OCR-only content that would not
+    # naturally appear in a section) must not appear verbatim in sections
+    assert "OCR: 555666777" not in r.tldr, (
+        "raw transcription text must not bleed into tldr section"
+    )
+    assert "Belopp: 1 234 kr" not in r.tldr, (
+        "raw transcription text must not bleed into tldr (only extracted values belong)"
+    )
+
+
+def test_truncated_output_severity_none_no_crash():
+    """Truncated output (no SEVERITY line) → severity is None, other fields still parse."""
+    r = parse_output(TRUNCATED)
+    assert r.severity is None, f"expected None for truncated output, got {r.severity}"
+    assert r.tldr, "tldr should still parse even without SEVERITY line"
+    assert r.quip, "quip should parse from truncated output"
+
+
+def test_non_english_body_language_invariance():
+    """
+    Hindi body with fixed English headings → all four sections split non-empty.
+    (Pitfall 3: sections must anchor on English headings regardless of prose language.)
+    """
+    r = parse_output(NON_ENGLISH_BODY)
+    assert r.tldr, f"tldr empty — language invariance broken: {r.tldr!r}"
+    assert r.why, f"why empty — language invariance broken: {r.why!r}"
+    assert r.actions, f"actions empty — language invariance broken: {r.actions!r}"
+    assert r.deadlines, f"deadlines empty — language invariance broken: {r.deadlines!r}"
+    assert r.severity == 3
+
+
+def test_arabic_body_language_invariance():
+    """Arabic body with fixed English headings → all four sections split non-empty."""
+    r = parse_output(ARABIC_BODY)
+    assert r.tldr, "tldr should be non-empty for Arabic body"
+    assert r.why, "why should be non-empty for Arabic body"
+    assert r.actions, "actions should be non-empty for Arabic body"
+    assert r.deadlines, "deadlines should be non-empty for Arabic body"
+    assert r.severity == 2
+
+
+def test_empty_raw_no_exception():
+    """Empty raw string → StructuredResult with empty fields and severity=None, no crash."""
+    r = parse_output("")
+    assert r.severity is None
+    assert r.transcription == ""
+    assert r.quip == ""
+    assert r.tldr == ""
+    assert r.why == ""
+    assert r.actions == ""
+    assert r.deadlines == ""
+    assert r.raw == ""
+
+
+def test_severity_regex_tolerates_trailing_whitespace():
+    """SEVERITY regex matches with trailing whitespace/newline and only accepts 1-5."""
+    for sev in range(1, 6):
+        raw = f"<transcription>x</transcription>\nBureaucat says: hi\n## TL;DR\na\n## Why you got this\nb\n## What you need to do\nc\n## Deadlines & money\nd\nSEVERITY: {sev}  \n"
+        r = parse_output(raw)
+        assert r.severity == sev, f"Expected {sev}, got {r.severity}"
+
+    # Value 0 and 6 should not match
+    for bad in ("0", "6", "10"):
+        raw = f"<transcription>x</transcription>\nBureaucat says: hi\n## TL;DR\na\n## Why you got this\nb\n## What you need to do\nc\n## Deadlines & money\nd\nSEVERITY: {bad}\n"
+        r = parse_output(raw)
+        assert r.severity is None, f"Severity {bad} should not parse to int, got {r.severity}"
+
+
+def test_build_user_prompt_beginner_mode_invariance():
+    """
+    D-08 unit guard: beginner and standard prompts differ only by appended
+    inline-explanation guidance. Neither adds/removes sections, alters the
+    SEVERITY line reference, or touches the transcription block.
+    """
+    standard = build_user_prompt("English", beginner_mode=False)
+    beginner = build_user_prompt("English", beginner_mode=True)
+
+    # Beginner must be strictly longer (has additional guidance appended)
+    assert len(beginner) > len(standard), "beginner prompt must be longer than standard"
+
+    # Standard must be a prefix of beginner (beginner only appends, never replaces)
+    assert beginner.startswith(standard), (
+        "beginner prompt must start with the full standard prompt"
+    )
+
+    # The extra beginner content must not mention adding/removing sections
+    extra = beginner[len(standard):]
+    assert "new section" not in extra.lower() or "do not add new sections" in extra.lower(), (
+        "beginner extra guidance must not instruct adding new sections"
+    )
+
+    # Neither prompt should reference SEVERITY or transcription in a way that
+    # would alter those structural elements (those are in SYSTEM_PROMPT only)
+    assert "SEVERITY" not in standard
+    assert "SEVERITY" not in beginner
+    assert "<transcription>" not in standard
+    assert "<transcription>" not in beginner
+
+
+def test_build_user_prompt_language_interpolation():
+    """Language is correctly embedded in the prompt for different languages."""
+    for lang in ("English", "Hindi", "Arabic", "Spanish", "Swedish"):
+        p = build_user_prompt(lang, beginner_mode=False)
+        assert lang in p, f"Language '{lang}' must appear in prompt"
+
+
+def test_structured_result_is_dataclass():
+    """StructuredResult can be instantiated directly and has all required fields."""
+    r = StructuredResult(
+        transcription="t", quip="q", tldr="tl", why="w",
+        actions="a", deadlines="d", severity=3, raw="raw"
+    )
+    assert r.severity == 3
+    assert r.transcription == "t"
+
+
+def test_model_is_none_under_no_model_flag():
+    """BUREAUCAT_NO_MODEL=1 → app.model is None (set in os.environ before import)."""
+    assert app.model is None, "model should be None when BUREAUCAT_NO_MODEL is set"
+    assert app.processor is None, "processor should be None when BUREAUCAT_NO_MODEL is set"
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])

frontend/app.js

@@ -0,0 +1,788 @@
+/* Bureaucat custom frontend (Phase 4, Off-Brand badge).
+ *
+ * ZeroGPU contract: ALL API calls go through @gradio/client — it forwards the
+ * HF iframe auth headers (X-IP-Token) that ZeroGPU quota attribution needs.
+ * A raw fetch() here would silently burn the anonymous quota tier. */
+
+import { Client, handle_file } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+
+const $ = (id) => document.getElementById(id);
+
+const MASCOT = (state) => `/assets/mascot/${state}.png`;
+
+// MUST mirror EXAMPLE_LETTERS in app.py IN ORDER — the gallery sends the array
+// index to /example, which indexes app.py's list. If the orders drift, clicking a
+// thumbnail shows a different letter's result.
+const EXAMPLES = [
+  { slug: "skatteverket-slutskattebesked",        label: "Skatteverket — tax refund (severity 1)" },
+  { slug: "vardcentral-kallelse",                  label: "Vårdcentral — appointment (severity 2)" },
+  { slug: "forsakringskassan-komplettering",      label: "Försäkringskassan — submit documents (severity 3)" },
+  { slug: "csn-aterkrav",                          label: "CSN — repayment demand (severity 4)" },
+  { slug: "migrationsverket-uppehallstillstand",  label: "Migrationsverket — permit at risk (severity 5)" },
+];
+
+let client = null;
+let pickedFiles = [];
+let busy = false;
+let pendingSource = null;   // { name, thumbUrl } for the letter currently being read
+let lastThumbUrl = null;    // object URL to revoke when it's replaced
+let lastPayload = null;     // last rendered verdict (for the shareable card)
+let _stepTimer = null;      // rotating reading-step interval
+
+/* ---------- tiny safe renderers ---------- */
+
+const escapeHtml = (s) =>
+  String(s).replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+/* Escape first, then allow exactly **bold** and *italic*; paragraphs on blank lines. */
+function mdLite(text) {
+  const esc = escapeHtml(text.trim());
+  const inline = esc
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/\*([^*]+)\*/g, "<em>$1</em>");
+  return inline
+    .split(/\n{2,}/)
+    .map((p) => `<p>${p.replace(/\n/g, "<br>")}</p>`)
+    .join("");
+}
+
+function setMascot(state, statusText) {
+  const m = $("mascot");
+  m.src = MASCOT(state);
+  m.alt = `Bureaucat is ${state.replace("_", " ")}`;
+  m.className = `mascot mascot--${state}`;
+  if (statusText !== undefined) $("status-line").textContent = statusText;
+}
+
+// ---- Delightful loading: rotating step messages + skeleton shimmer ----
+const READING_STEPS = [
+  "🤓 Putting on my reading glasses…",
+  "🔍 Decoding the bureaucratese…",
+  "📅 Hunting for every deadline…",
+  "🧮 Checking every number twice…",
+  "🐾 Forming my expert opinion…",
+];
+function startReadingSteps() {
+  setMascot("reading", READING_STEPS[0]);
+  $("skeleton").hidden = false;
+  let i = 0;
+  clearInterval(_stepTimer);
+  _stepTimer = setInterval(() => {
+    i = (i + 1) % READING_STEPS.length;
+    $("status-line").textContent = READING_STEPS[i];
+  }, 2200);
+}
+function stopReadingSteps() {
+  clearInterval(_stepTimer);
+  _stepTimer = null;
+  $("skeleton").hidden = true;
+}
+
+// ---- Panic-o-meter: a cartoon gauge dial with a wobbling needle ----
+const FACES = { 1: "😌", 2: "🙂", 3: "😬", 4: "😰", 5: "😱" };
+const SEG_COLORS = ["#27AE60", "#8BC34A", "#F39C12", "#E67E22", "#C0392B"];
+
+function polar(cx, cy, r, deg) {
+  const a = (deg * Math.PI) / 180;
+  return [cx + r * Math.cos(a), cy - r * Math.sin(a)];
+}
+// Sample the true circle as a polyline (no SVG arc-flag ambiguity).
+function arcPoints(cx, cy, r, t1, t2) {
+  const pts = [];
+  const step = t1 > t2 ? -3 : 3;
+  for (let t = t1; step < 0 ? t > t2 : t < t2; t += step) {
+    const [x, y] = polar(cx, cy, r, t);
+    pts.push(`${x.toFixed(1)},${y.toFixed(1)}`);
+  }
+  const [xe, ye] = polar(cx, cy, r, t2);
+  pts.push(`${xe.toFixed(1)},${ye.toFixed(1)}`);
+  return pts.join(" ");
+}
+
+function buildGauge(severity, word, color) {
+  // severity may be null/undefined when a dense letter read fine but lost its
+  // SEVERITY line — render an "unclear" dial (greyed band, no needle/marker).
+  const known = severity != null && severity >= 1 && severity <= 5;
+  const s = known ? severity : 0;
+  const CX = 100, CY = 105, R = 78;
+  // Equal-thickness zones forming one continuous curved band (no "active bar" —
+  // a thickened top zone read as a flat horizontal line). The needle + a marker
+  // dot on the band indicate the level instead.
+  let segs = "";
+  for (let k = 1; k <= 5; k++) {
+    const tc = 180 - (k - 0.5) * 36;          // segment centre angle (1=left … 5=right)
+    const pts = arcPoints(CX, CY, R, tc + 16, tc - 16);
+    const active = known && k === s;
+    segs += `<polyline points="${pts}" fill="none" stroke="${SEG_COLORS[k - 1]}" ` +
+      `stroke-width="13" stroke-linecap="round" opacity="${active ? 1 : known ? 0.5 : 0.4}"/>`;
+    const [nx, ny] = polar(CX, CY, R + 17, tc);
+    segs += `<text x="${nx.toFixed(1)}" y="${(ny + 3.5).toFixed(1)}" text-anchor="middle" ` +
+      `font-size="11" font-weight="700" ${active ? `fill="${SEG_COLORS[k - 1]}"` : 'class="gauge-tick"'} ` +
+      `opacity="${active ? 1 : 0.6}">${k}</text>`;
+  }
+  let marker = "", needle = "";
+  if (known) {
+    // Glowing marker dot sitting on the band at the active zone — a dot, not a bar.
+    const [mx, my] = polar(CX, CY, R, 180 - (s - 0.5) * 36);
+    marker = `<circle cx="${mx.toFixed(1)}" cy="${my.toFixed(1)}" r="9" ` +
+      `fill="${color}" filter="url(#glow)"/><circle cx="${mx.toFixed(1)}" cy="${my.toFixed(1)}" r="3.5" fill="#fff"/>`;
+    const phi = (s - 3) * 36;                    // needle rotation; 0 = straight up (level 3)
+    // Static transform = correct end state even if SMIL is unavailable; SMIL adds the wobble.
+    needle = `<polygon class="gauge-needle" points="100,38 105.5,105 94.5,105" ` +
+      `transform="rotate(${phi} 100 105)">` +
+      `<animateTransform attributeName="transform" type="rotate" ` +
+      `values="0 100 105; ${(phi * 1.18).toFixed(1)} 100 105; ${(phi * 0.9).toFixed(1)} 100 105; ${phi} 100 105" ` +
+      `keyTimes="0;0.6;0.82;1" dur="0.8s" fill="freeze"/></polygon>`;
+  } else {
+    // unclear: a "?" where the needle would be, no hub-needle
+    needle = `<text x="100" y="84" text-anchor="middle" font-size="42" font-weight="700" class="gauge-tick">?</text>`;
+  }
+  const face = known ? FACES[s] : "🤔";
+  const num = known ? `${s}<span style="font-size:.6em">/5</span>` : `?<span style="font-size:.6em">/5</span>`;
+  return `<div class="panic-gauge" role="img" aria-label="Panic level ${known ? s + " of 5" : "unclear"} — ${escapeHtml(word)}">` +
+    `<div class="panic-gauge__title">🐾 Panic-o-meter</div>` +
+    `<svg class="panic-gauge__svg" viewBox="0 0 200 126">` +
+      `<defs><filter id="glow" x="-40%" y="-40%" width="180%" height="180%">` +
+      `<feDropShadow dx="0" dy="0" stdDeviation="3" flood-color="${color}" flood-opacity="0.75"/></filter></defs>` +
+      segs + marker + needle +
+      (known ? `<circle cx="100" cy="105" r="9" class="gauge-needle"/>` +
+               `<circle cx="100" cy="105" r="3.5" fill="#fff" opacity="0.85"/>` : "") +
+    `</svg>` +
+    `<div class="panic-gauge__readout">` +
+      `<span class="panic-gauge__face">${face}</span>` +
+      `<span class="panic-gauge__num" style="color:${color}">${num}</span>` +
+      `<span class="panic-gauge__word" style="color:${color}">${escapeHtml(word)}</span>` +
+    `</div></div>`;
+}
+
+function setPanic(payload) {
+  const panic = $("panic");
+  const stage = $("stage");
+  if (!payload) {
+    panic.innerHTML =
+      '<div class="panic__placeholder">🐾 Feed me a letter and I\'ll tell you how worried to be</div>';
+    stage.style.removeProperty("--sev");
+    stage.classList.remove("stage--alarm");
+    return;
+  }
+  const label = payload.severity_label || "Panic level unclear";
+  const word = label.includes("—") ? label.split("—")[1].trim() : label;
+  const color = payload.severity_color || "#9E9E9E";
+  panic.innerHTML = buildGauge(payload.severity, word, color);
+  // Severity colour-wash over the stage + a red alarm aura at the high end.
+  stage.style.setProperty("--sev", color);
+  stage.classList.toggle("stage--alarm", (payload.severity || 0) >= 4);
+  rollPanicNumber(payload.severity);
+}
+
+// Roll the panic number 1→N for a little gauge-spinning drama (skipped on reduced motion;
+// buildGauge already shows the final number, so nothing is lost).
+function rollPanicNumber(sev) {
+  if (sev == null || REDUCE_MOTION) return;
+  const el = document.querySelector(".panic-gauge__num");
+  if (!el) return;
+  const suffix = '<span style="font-size:.6em">/5</span>';
+  let cur = 1;
+  el.innerHTML = `1${suffix}`;
+  const iv = setInterval(() => {
+    cur += 1;
+    if (cur > sev) { clearInterval(iv); return; }
+    el.innerHTML = `${cur}${suffix}`;
+    el.classList.remove("num-pop"); void el.offsetWidth; el.classList.add("num-pop");
+  }, 150);
+}
+
+function setQuip(quip) {
+  const q = $("quip");
+  if (quip && quip.trim()) {
+    q.innerHTML = `<strong>Bureaucat says:</strong> ${escapeHtml(quip.trim())}`;
+    q.hidden = false;
+  } else {
+    q.hidden = true;
+  }
+}
+
+function renderChecklist(actions) {
+  const box = $("actions");
+  box.innerHTML = "";
+  const lines = actions.split("\n").map((l) => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    const m = line.match(/^(?:[-*•]|\d+[.)])\s+(.*)$/);
+    if (m) {
+      const label = document.createElement("label");
+      label.className = "check-item";
+      const cb = document.createElement("input");
+      cb.type = "checkbox";
+      cb.addEventListener("change", () => label.classList.toggle("done", cb.checked));
+      const span = document.createElement("span");
+      span.innerHTML = mdLite(m[1]);
+      label.append(cb, span);
+      box.appendChild(label);
+    } else {
+      const p = document.createElement("p");
+      p.className = "prose";
+      p.innerHTML = mdLite(line);
+      box.appendChild(p);
+    }
+  }
+  if (!box.children.length) box.innerHTML = '<p class="prose">Nothing to do. Enjoy your fika. ☕</p>';
+}
+
+// ---- Deadline countdowns: turn a date string into "in 12 days" / "overdue" ----
+const SV_MONTHS = {
+  januari: 0, februari: 1, mars: 2, april: 3, maj: 4, juni: 5,
+  juli: 6, augusti: 7, september: 8, oktober: 9, november: 10, december: 11,
+};
+function parseLetterDate(s) {
+  if (!s) return null;
+  let m = s.match(/(\d{4})-(\d{2})-(\d{2})/);                       // ISO 2026-06-22
+  if (m) return new Date(+m[1], +m[2] - 1, +m[3]);
+  m = s.toLowerCase().match(                                        // "den 5 maj 2026"
+    /(\d{1,2})\s+(januari|februari|mars|april|maj|juni|juli|augusti|september|oktober|november|december)\s+(\d{4})/);
+  if (m) return new Date(+m[3], SV_MONTHS[m[2]], +m[1]);
+  return null;
+}
+function countdownBadge(value) {
+  const date = parseLetterDate(value);
+  if (!date) return null;
+  const today = new Date(); today.setHours(0, 0, 0, 0);
+  const n = Math.round((date - today) / 86400000);
+  if (n < 0)  return { text: `overdue by ${-n} day${-n === 1 ? "" : "s"}`, cls: "overdue" };
+  if (n === 0) return { text: "today", cls: "soon" };
+  if (n === 1) return { text: "tomorrow", cls: "soon" };
+  if (n <= 7)  return { text: `in ${n} days`, cls: "soon" };
+  if (n <= 30) return { text: `in ${n} days`, cls: "near" };
+  return { text: `in ${Math.round(n / 30)} month${Math.round(n / 30) === 1 ? "" : "s"}`, cls: "far" };
+}
+
+function renderDeadlines(payload) {
+  const ul = $("deadlines");
+  ul.innerHTML = "";
+  const banner = $("deadline-banner");
+  banner.hidden = true;
+
+  if (!payload.deadline_items.length) {
+    ul.innerHTML = '<li class="none">None found.</li>';
+    return;
+  }
+  let firstDated = null;
+  for (const item of payload.deadline_items) {
+    const cd = countdownBadge(item.value);
+    if (cd && !firstDated) firstDated = { item, cd };
+    const li = document.createElement("li");
+    li.innerHTML =
+      `<mark>${escapeHtml(item.value)}</mark>` +
+      (item.note ? ` — ${escapeHtml(item.note)}` : "") +
+      (cd ? ` <span class="cd cd--${cd.cls}">${cd.text}</span>` : "");
+    ul.appendChild(li);
+  }
+  // Banner highlights the soonest dated deadline (not just the first listed value).
+  const lead = firstDated || { item: payload.deadline_items[0], cd: null };
+  banner.innerHTML =
+    `⏰ Mark this: <span class="value">${escapeHtml(lead.item.value)}</span>` +
+    (lead.item.note ? ` — ${escapeHtml(lead.item.note)}` : "") +
+    (lead.cd ? ` <span class="cd cd--${lead.cd.cls}">${lead.cd.text}</span>` : "");
+  banner.hidden = false;
+}
+
+function renderGrounding(payload) {
+  const g = $("grounding");
+  if (payload.grounded) {
+    g.className = "grounding ok";
+    g.textContent = "✓ Verified: every value above appears verbatim in the letter — nothing invented.";
+  } else {
+    g.className = "grounding fail";
+    g.textContent =
+      "⚠ Verification failed for: " + payload.invented_values.join(", ") +
+      " — these were NOT found in the letter. Double-check against the original.";
+  }
+  g.hidden = false;
+}
+
+/* ---------- celebration: reactive visuals + synth sound ----------
+ * Sound is synthesized in-browser via Web Audio (no audio files, no CDN) so it
+ * stays fully "Off the Grid". A mute toggle persists in localStorage. Visuals
+ * respect prefers-reduced-motion. */
+
+const REDUCE_MOTION = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+const BCAT_COLORS = ["#E91E63", "#84CC16", "#FFD166", "#FFFFFF", "#FF8A3D"];
+let muted = localStorage.getItem("bcat-muted") === "1";
+let _actx = null;
+
+function audioCtx() {
+  if (!_actx) {
+    try { _actx = new (window.AudioContext || window.webkitAudioContext)(); }
+    catch { return null; }
+  }
+  if (_actx.state === "suspended") _actx.resume();   // must be primed by a user gesture
+  return _actx;
+}
+
+// One enveloped oscillator note. start/dur in seconds, relative to now.
+function tone(freq, start, dur, type = "sine", peak = 0.16) {
+  const ac = audioCtx(); if (!ac) return;
+  const t0 = ac.currentTime + start;
+  const osc = ac.createOscillator(), g = ac.createGain();
+  osc.type = type; osc.frequency.value = freq;
+  osc.connect(g); g.connect(ac.destination);
+  g.gain.setValueAtTime(0.0001, t0);
+  g.gain.exponentialRampToValueAtTime(peak, t0 + 0.02);
+  g.gain.exponentialRampToValueAtTime(0.0001, t0 + dur);
+  osc.start(t0); osc.stop(t0 + dur + 0.03);
+}
+const chimeGood = () => { if (!muted) [523.25, 659.25, 783.99, 1046.5].forEach((f, i) => tone(f, i * 0.09, 0.4, "triangle", 0.15)); };
+const chimeAlert = () => { if (!muted) { tone(311.13, 0, 0.26, "sawtooth", 0.1); tone(233.08, 0.22, 0.45, "sawtooth", 0.1); } };
+const chimePop = () => { if (!muted) { tone(880, 0, 0.12, "sine", 0.12); tone(1318.5, 0.08, 0.16, "sine", 0.1); } };
+// Calm "noted" cue for action-needed-but-manageable — neutral, NOT celebratory.
+const noteTone = () => { if (!muted) { tone(587.33, 0, 0.16, "sine", 0.12); tone(440, 0.14, 0.26, "sine", 0.11); } };
+
+function fireworks() {
+  if (!window.confetti || REDUCE_MOTION) return;
+  // dual side-cannons streaming for ~1.3s …
+  const end = Date.now() + 1300;
+  (function frame() {
+    window.confetti({ particleCount: 7, angle: 60, spread: 72, startVelocity: 55, origin: { x: 0, y: 0.7 }, colors: BCAT_COLORS });
+    window.confetti({ particleCount: 7, angle: 120, spread: 72, startVelocity: 55, origin: { x: 1, y: 0.7 }, colors: BCAT_COLORS });
+    if (Date.now() < end) requestAnimationFrame(frame);
+  })();
+  // … plus staggered center bursts for a real "show"
+  window.confetti({ particleCount: 150, spread: 100, origin: { y: 0.62 }, colors: BCAT_COLORS, scalar: 1.1 });
+  setTimeout(() => window.confetti({ particleCount: 130, spread: 130, startVelocity: 45, origin: { y: 0.55 }, colors: BCAT_COLORS }), 300);
+  setTimeout(() => window.confetti({ particleCount: 90, spread: 160, decay: 0.92, scalar: 1.3, origin: { y: 0.5 }, colors: BCAT_COLORS }), 650);
+}
+
+// Action-needed cue: glow the deadline banner to pull the eye to the date/amount.
+// Localized and non-celebratory — the right signal when there's something to do.
+function pulseDeadlineBanner() {
+  if (REDUCE_MOTION) return;
+  const b = $("deadline-banner");
+  if (!b || b.hidden) return;
+  b.classList.remove("pulse");
+  void b.offsetWidth;            // force reflow so the animation restarts on repeat
+  b.classList.add("pulse");
+  b.addEventListener("animationend", () => b.classList.remove("pulse"), { once: true });
+}
+
+function screenFlash(kind) {
+  if (REDUCE_MOTION) return;
+  const el = document.createElement("div");
+  el.className = "screen-flash screen-flash--" + kind;
+  document.body.appendChild(el);
+  el.addEventListener("animationend", () => el.remove(), { once: true });
+}
+
+// Verdict-reactive celebration: good news → fireworks; severe → red alert pulse; else → puff.
+function reactToResult(payload) {
+  if (payload.kind !== "letter") return;
+  const sev = payload.severity || 0;
+  if (payload.mascot === "allclear") {
+    // genuinely good news — nothing to pay, no deadline. Celebrate.
+    fireworks(); screenFlash("good"); chimeGood();
+  } else if (sev >= 4) {
+    // urgent — act now
+    screenFlash("alert"); chimeAlert();
+  } else {
+    // action needed but manageable — draw the eye to the deadline, do NOT celebrate
+    pulseDeadlineBanner(); noteTone();
+  }
+}
+
+function setMuted(v) {
+  muted = v;
+  localStorage.setItem("bcat-muted", v ? "1" : "0");
+  const b = $("sound-toggle");
+  if (b) { b.textContent = v ? "🔇" : "🔊"; b.title = v ? "Sound off — click to enable" : "Sound on — click to mute"; }
+}
+
+/* ---------- shareable verdict card ---------- */
+
+function _roundRect(ctx, x, y, w, h, r) {
+  ctx.beginPath();
+  if (ctx.roundRect) { ctx.roundRect(x, y, w, h, r); return; }
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + w, y, x + w, y + h, r);
+  ctx.arcTo(x + w, y + h, x, y + h, r);
+  ctx.arcTo(x, y + h, x, y, r);
+  ctx.arcTo(x, y, x + w, y, r);
+  ctx.closePath();
+}
+function _wrapText(ctx, text, maxWidth) {
+  const words = text.split(/\s+/), lines = [];
+  let line = "";
+  for (const w of words) {
+    const test = line ? `${line} ${w}` : w;
+    if (ctx.measureText(test).width > maxWidth && line) { lines.push(line); line = w; }
+    else line = test;
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+function _loadImage(src) {
+  return new Promise((res, rej) => {
+    const img = new Image();
+    img.onload = () => res(img); img.onerror = rej; img.src = src;
+  });
+}
+
+// Draw a 1080×1080 social card of the verdict and share/download it. Pure canvas —
+// no external lib, stays "Off the Grid". Doubles as the hackathon social-post asset.
+async function generateShareCard() {
+  const p = lastPayload;
+  if (!p || p.kind !== "letter") return;
+  if (!muted) chimePop();
+  const W = 1080, H = 1080;
+  const c = document.createElement("canvas");
+  c.width = W; c.height = H;
+  const ctx = c.getContext("2d");
+  const FONT = "Fredoka, system-ui, sans-serif";
+  ctx.textAlign = "center";
+
+  const bg = ctx.createLinearGradient(0, 0, W, H);
+  bg.addColorStop(0, "#FFE3F1"); bg.addColorStop(1, "#FFF6D6");
+  ctx.fillStyle = bg; ctx.fillRect(0, 0, W, H);
+  ctx.fillStyle = "#ffffff";
+  _roundRect(ctx, 56, 56, W - 112, H - 112, 48); ctx.fill();
+
+  ctx.fillStyle = "#E91E63";
+  ctx.font = `700 62px ${FONT}`;
+  ctx.fillText("🐱 Bureaucat", W / 2, 168);
+  ctx.fillStyle = "#7a7a7a";
+  ctx.font = `500 28px ${FONT}`;
+  ctx.fillText("read my scary Swedish letter so I didn't have to", W / 2, 214);
+
+  try {
+    const cat = await _loadImage(MASCOT(p.mascot || "idle"));
+    const cw = 300, ch = cat.height * (cw / cat.width);
+    ctx.drawImage(cat, W / 2 - cw / 2, 250, cw, ch);
+  } catch { /* mascot optional */ }
+
+  const sev = p.severity;
+  const color = p.severity_color || "#9E9E9E";
+  const face = FACES[sev] || "🤔";
+  ctx.fillStyle = color;
+  ctx.font = `700 150px ${FONT}`;
+  ctx.fillText(`${face} ${sev != null ? sev : "?"}/5`, W / 2, 690);
+  const label = p.severity_label || "Panic level unclear";
+  ctx.font = `600 46px ${FONT}`;
+  ctx.fillText(label.includes("—") ? label.split("—")[1].trim() : label, W / 2, 752);
+
+  ctx.fillStyle = "#2b2b2b";
+  ctx.font = `400 33px ${FONT}`;
+  let tldr = (p.tldr || "").replace(/\*\*/g, "").replace(/\s+/g, " ").trim();
+  if (tldr.length > 230) tldr = tldr.slice(0, 227) + "…";
+  _wrapText(ctx, tldr, W - 220).slice(0, 4).forEach((ln, i) =>
+    ctx.fillText(ln, W / 2, 840 + i * 46));
+
+  ctx.fillStyle = "#9b9b9b";
+  ctx.font = `500 25px ${FONT}`;
+  ctx.fillText("runs on one small model, inside the Space — no cloud", W / 2, H - 88);
+
+  c.toBlob(async (blob) => {
+    if (!blob) return;
+    const file = new File([blob], "bureaucat-panic.png", { type: "image/png" });
+    if (navigator.canShare && navigator.canShare({ files: [file] })) {
+      try { await navigator.share({ files: [file], title: "My Bureaucat panic level" }); return; }
+      catch { /* fall through to download */ }
+    }
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url; a.download = "bureaucat-panic.png";
+    document.body.appendChild(a); a.click(); a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 4000);
+  }, "image/png");
+}
+
+/* ---------- payload → page ---------- */
+
+function showResult(payload, statusText) {
+  stopReadingSteps();
+  lastPayload = payload;
+  $("results").hidden = true;
+  $("refusal").hidden = true;
+  $("share-row").hidden = true;
+
+  if (payload.kind === "letter") {
+    setPanic(payload);
+    setQuip(payload.quip);
+    setMascot(payload.mascot, statusText);
+    $("tldr").innerHTML = mdLite(payload.tldr);
+    $("why").innerHTML = mdLite(payload.why);
+    renderChecklist(payload.actions);
+    renderDeadlines(payload);
+    renderGrounding(payload);
+    $("results").hidden = false;
+    $("share-row").hidden = false;   // letters have a panic level worth sharing
+    setTimeout(() => reactToResult(payload), 220);
+  } else if (payload.kind === "refusal") {
+    setPanic(null);
+    setQuip(payload.quip);
+    setMascot(payload.mascot, "That didn't look right.");
+    $("refusal-title").textContent =
+      payload.doctype === "unreadable" ? "🙀 I can't read that…" : "🤨 That's not a Swedish letter…";
+    $("refusal-guidance").textContent = payload.guidance;
+    $("refusal").hidden = false;
+    $("deadline-banner").hidden = true;
+  } else {
+    setPanic(null);
+    setQuip("");
+    setMascot("idle", "Something went wrong — try again.");
+    $("refusal-title").textContent = "😿 Hmm, that didn't work";
+    $("refusal-guidance").textContent = payload.guidance;
+    $("refusal").hidden = false;
+    $("deadline-banner").hidden = true;
+  }
+  if (pendingSource) setReadSource(pendingSource.name, pendingSource.thumbUrl);
+  armForNext();   // verdict stays; upload area re-arms (selection cleared, CTA off)
+}
+
+/* ---------- API ---------- */
+
+async function getClient() {
+  if (!client) client = await Client.connect(window.location.origin);
+  return client;
+}
+
+async function analyze() {
+  if (busy || !pickedFiles.length) return;
+  audioCtx();  // prime audio within this click gesture so the result sound can play later
+  busy = true;
+  $("analyze-btn").disabled = true;
+  $("results").hidden = true;
+  $("refusal").hidden = true;
+  $("deadline-banner").hidden = true;
+  clearReadSource();   // hide any stale "verdict for" while this one reads
+  $("share-row").hidden = true;
+  setPanic(null);
+  setQuip("");
+  startReadingSteps();   // rotating step messages + skeleton shimmer
+
+  // Remember which letter this verdict is for (pickedFiles is cleared once it renders).
+  // Thumbnail only for a single image; PDFs/multi just show the name.
+  const files = pickedFiles.slice();
+  const first = files[0];
+  let thumbUrl = null;
+  if (files.length === 1 && /\.(jpe?g|png)$/i.test(first.name)) {
+    thumbUrl = URL.createObjectURL(first);
+    lastThumbUrl = thumbUrl;
+  }
+  pendingSource = {
+    name: files.length > 1 ? `${first.name} +${files.length - 1} more` : first.name,
+    thumbUrl,
+  };
+
+  try {
+    const c = await getClient();
+    // Race the prediction against a timeout so a dropped/hung connection can never
+    // leave the UI stuck `busy` (which would silently dead-click "Read it for me").
+    let timer;
+    const timeout = new Promise((_, rej) => {
+      timer = setTimeout(() => rej(new Error("timeout")), 180000);
+    });
+    let res;
+    try {
+      res = await Promise.race([
+        c.predict("/analyze", {
+          files: pickedFiles.map((f) => handle_file(f)),
+          beginner: $("beginner").checked,
+        }),
+        timeout,
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+    const payload = res.data[0];
+    // Brief "verifying" beat so the grounding check is a visible moment (D2-05).
+    setMascot("verifying", "Double-checking every number against the letter…");
+    await new Promise((r) => setTimeout(r, 700));
+    showResult(payload, "Verdict delivered.");
+  } catch (err) {
+    console.error(err);
+    client = null;  // drop the cached client so the next attempt reconnects fresh
+    showResult({
+      kind: "error",
+      guidance: "The Space hiccuped (queue or quota). Wait a moment and try again — or tap an example below (zero GPU).",
+    });
+  } finally {
+    busy = false;
+    $("analyze-btn").disabled = pickedFiles.length === 0;
+  }
+}
+
+async function loadExample(index) {
+  if (busy) return;
+  audioCtx();  // prime audio within this click gesture
+  busy = true;
+  $("refusal").hidden = true;
+  clearReadSource();
+  setMascot("reading", "Fetching a pre-read letter — zero GPU…");
+  const ex = EXAMPLES[index];
+  pendingSource = ex
+    ? { name: ex.label, thumbUrl: `/letters/${ex.slug}.png` }
+    : null;
+  try {
+    const c = await getClient();
+    const res = await c.predict("/example", { index });
+    showResult(res.data[0], "Pre-computed example — cost you nothing.");
+  } catch (err) {
+    console.error(err);
+    setMascot("idle", "Couldn't load that example. Try again.");
+  } finally {
+    busy = false;
+  }
+}
+
+/* ---------- wiring ---------- */
+
+/* ---------- UI state model ----------
+ * The upload area and the CTA always agree on one fact: is a letter selected?
+ *   • CTA enabled  ⟺ exactly when a file is selected and ready to read (SELECTED)
+ *   • CTA disabled ⟺ nothing selected (EMPTY at start, ARMED after a verdict, or READING)
+ * Transitions:
+ *   EMPTY    page load / nothing chosen        → idle invite, CTA off
+ *   SELECTED a file is picked                   → filename shown, CTA on, prior verdict cleared
+ *   READING  CTA clicked                        → CTA off (busy), mascot reading
+ *   ARMED    a verdict is on screen             → selection cleared, dropzone re-arms as the
+ *                                                 highlighted next-letter target, CTA off
+ */
+
+const DZ_DEFAULT = {
+  icon: "📬",
+  title: "Drop a saved photo or PDF here",
+  hint: "upload an existing image/PDF file · multi-page is fine · or click to browse",
+};
+const DZ_NEXT = {
+  icon: "📸",
+  title: "Drop the next letter here to scan it",
+  hint: "your verdict is below — drop a new file (or click) to read another",
+};
+function setDropzoneText(t) {
+  $("dz-icon").textContent = t.icon;
+  $("dz-title").textContent = t.title;
+  $("dz-hint").textContent = t.hint;
+}
+
+// "Verdict for <letter>" indicator — keeps the result attributable after the
+// dropzone re-arms (you can no longer see which file was read otherwise).
+function setReadSource(name, thumbUrl) {
+  $("read-source-name").textContent = name;
+  const thumb = $("read-source-thumb");
+  if (thumbUrl) { thumb.src = thumbUrl; thumb.hidden = false; }
+  else { thumb.removeAttribute("src"); thumb.hidden = true; }
+  $("read-source").hidden = false;
+}
+function clearReadSource() {
+  $("read-source").hidden = true;
+  if (lastThumbUrl) { URL.revokeObjectURL(lastThumbUrl); lastThumbUrl = null; }
+}
+
+// Forget any selected file and turn the CTA off — the single source of truth for
+// "no letter is loaded". Always leaves the dropzone showing its idle invite.
+function clearSelection() {
+  pickedFiles = [];
+  const fi = $("file-input");
+  if (fi) fi.value = "";               // so re-picking the same file still fires `change`
+  const ul = $("file-list");
+  ul.innerHTML = "";
+  ul.hidden = true;
+  $("dropzone-idle").hidden = false;
+  $("analyze-btn").disabled = true;
+}
+
+// Hide any verdict currently on screen (does not touch the file selection).
+function hideVerdict() {
+  $("results").hidden = true;
+  $("refusal").hidden = true;
+  $("deadline-banner").hidden = true;
+  $("share-row").hidden = true;
+  stopReadingSteps();
+  setPanic(null);
+  setQuip("");
+}
+
+// EMPTY — clean slate (page load, or after the user clears everything).
+function resetView() {
+  hideVerdict();
+  clearSelection();
+  clearReadSource();
+  pendingSource = null;
+  setDropzoneText(DZ_DEFAULT);
+  $("dropzone").classList.remove("dropzone--ready");
+  setMascot("idle", "Awaiting your scary letter.");
+}
+
+// ARMED — a verdict stays on screen; the upload area becomes the obvious, highlighted
+// target for the NEXT letter, with the CTA off because nothing is selected yet.
+function armForNext() {
+  clearSelection();
+  setDropzoneText(DZ_NEXT);
+  $("dropzone").classList.add("dropzone--ready");
+}
+
+// SELECTED — a new file was chosen: clear any prior verdict, list the file, enable the CTA.
+function setFiles(fileList) {
+  hideVerdict();
+  $("dropzone").classList.remove("dropzone--ready");
+  setDropzoneText(DZ_DEFAULT);
+  pickedFiles = Array.from(fileList).filter((f) =>
+    /\.(jpe?g|png|pdf)$/i.test(f.name));
+  if (!pickedFiles.length) {
+    clearSelection();                  // nothing valid picked → back to EMPTY
+    return;
+  }
+  const ul = $("file-list");
+  ul.innerHTML = "";
+  for (const f of pickedFiles) {
+    const li = document.createElement("li");
+    li.textContent = `${f.name} (${(f.size / 1024).toFixed(0)} kB)`;
+    ul.appendChild(li);
+  }
+  ul.hidden = false;
+  $("dropzone-idle").hidden = true;
+  $("analyze-btn").disabled = false;   // a letter is ready → CTA on
+  setMascot("idle", "Ready when you are — tap “Read it for me!”");
+}
+
+const dz = $("dropzone");
+dz.addEventListener("click", () => $("file-input").click());
+dz.addEventListener("keydown", (e) => {
+  if (e.key === "Enter" || e.key === " ") { e.preventDefault(); $("file-input").click(); }
+});
+$("file-input").addEventListener("change", (e) => setFiles(e.target.files));
+["dragenter", "dragover"].forEach((ev) =>
+  dz.addEventListener(ev, (e) => { e.preventDefault(); dz.classList.add("is-dragover"); }));
+["dragleave", "drop"].forEach((ev) =>
+  dz.addEventListener(ev, (e) => { e.preventDefault(); dz.classList.remove("is-dragover"); }));
+dz.addEventListener("drop", (e) => setFiles(e.dataTransfer.files));
+
+$("analyze-btn").addEventListener("click", analyze);
+$("share-btn").addEventListener("click", generateShareCard);
+
+// Sound mute toggle (persists in localStorage; a click also primes the audio ctx)
+setMuted(muted);
+$("sound-toggle").addEventListener("click", () => { setMuted(!muted); if (!muted) chimePop(); });
+
+// Gallery thumbnails (static files — zero GPU until clicked, and zero even then).
+const gal = $("gallery");
+EXAMPLES.forEach((ex, i) => {
+  const btn = document.createElement("button");
+  btn.className = "gallery__item";
+  btn.innerHTML =
+    `<img src="/letters/${ex.slug}.png" alt="${escapeHtml(ex.label)}" loading="lazy">` +
+    `<span>${escapeHtml(ex.label)}</span>`;
+  btn.addEventListener("click", () => loadExample(i));
+  gal.appendChild(btn);
+});
+
+// Confetti lib (best-effort; no-op if CDN blocked).
+const s = document.createElement("script");
+s.src = "https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js";
+document.head.appendChild(s);
+
+// Deep-link: /#example-2 auto-loads a pre-computed example (zero GPU) —
+// lets the demo video / judges land straight on a rendered verdict.
+const deepLink = location.hash.match(/^#example-([0-4])$/);
+if (deepLink) loadExample(Number(deepLink[1]));
+
+// Warm the client connection in the background.
+getClient().catch(() => { /* connect lazily on first use instead */ });

frontend/index.html

@@ -0,0 +1,133 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Bureaucat — the cat that reads scary Swedish letters</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Fredoka:wght@400;500;600;700&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="/static/style.css?v=20260614g" />
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🐱</text></svg>" />
+</head>
+<body>
+  <!-- Hero -->
+  <header class="hero">
+    <img src="/assets/mascot/idle.png" alt="Bureaucat, a cat civil servant" class="hero__cat" id="hero-cat" />
+    <div class="hero__text">
+      <h1>Bureaucat</h1>
+      <p>Upload a scary Swedish letter. I'll tell you how worried to be — and what to do.</p>
+    </div>
+  </header>
+
+  <main>
+    <!-- Upload card -->
+    <section class="card upload-card" id="upload-card">
+      <div class="dropzone" id="dropzone" role="button" tabindex="0"
+           aria-label="Upload letter — images or PDF">
+        <input type="file" id="file-input" accept=".jpg,.jpeg,.png,.pdf" multiple hidden />
+        <div class="dropzone__idle" id="dropzone-idle">
+          <span class="dropzone__icon" id="dz-icon">📬</span>
+          <strong id="dz-title">Drop a saved photo or PDF here</strong>
+          <span class="dropzone__hint" id="dz-hint">upload an existing image/PDF file · multi-page is fine · or click to browse</span>
+        </div>
+        <ul class="dropzone__files" id="file-list" hidden></ul>
+      </div>
+      <div class="upload-card__controls">
+        <label class="beginner-toggle">
+          <input type="checkbox" id="beginner" checked />
+          <span class="beginner-toggle__track" aria-hidden="true"></span>
+          I'm new to Sweden — explain the institutions &amp; jargon
+        </label>
+        <div class="upload-card__buttons">
+          <button class="cta" id="analyze-btn" disabled>🐾 Read it for me!</button>
+        </div>
+      </div>
+    </section>
+
+    <!-- What was read (shown with a verdict so the result is always attributable) -->
+    <div class="read-source" id="read-source" hidden>
+      <img class="read-source__thumb" id="read-source-thumb" alt="preview of the letter you read" hidden />
+      <div class="read-source__meta">
+        <span class="read-source__eyebrow">📄 Verdict for</span>
+        <strong id="read-source-name"></strong>
+      </div>
+    </div>
+
+    <!-- Stage: mascot + verdict -->
+    <section class="stage" id="stage">
+      <div class="stage__mascot">
+        <img src="/assets/mascot/idle.png" alt="Bureaucat is idle" id="mascot" class="mascot mascot--idle" />
+        <div class="stage__status" id="status-line">Awaiting your scary letter.</div>
+      </div>
+      <div class="stage__verdict">
+        <div class="panic" id="panic">
+          <div class="panic__placeholder">🐾 Feed me a letter and I'll tell you how worried to be</div>
+        </div>
+        <div class="quip" id="quip" hidden></div>
+      </div>
+    </section>
+
+    <!-- Deadline banner (hidden until a result has deadline items) -->
+    <div class="deadline-banner" id="deadline-banner" hidden></div>
+
+    <!-- Skeleton shimmer while the model reads -->
+    <section class="skeleton" id="skeleton" hidden aria-hidden="true">
+      <div class="skel-card skel-card--tall"></div>
+      <div class="skel-card"></div>
+      <div class="skel-card"></div>
+      <div class="skel-card"></div>
+    </section>
+
+    <!-- Results -->
+    <section class="results" id="results" hidden>
+      <div class="card result-card result-card--tldr">
+        <h2>📨 The short version</h2>
+        <div class="prose" id="tldr"></div>
+      </div>
+      <div class="card result-card">
+        <h2>🏛️ Why you got this</h2>
+        <div class="prose" id="why"></div>
+      </div>
+      <div class="card result-card">
+        <h2>✅ What you need to do</h2>
+        <div class="checklist" id="actions"></div>
+      </div>
+      <div class="card result-card">
+        <h2>⏰ Deadlines &amp; money</h2>
+        <ul class="deadlines" id="deadlines"></ul>
+        <div class="grounding" id="grounding" hidden></div>
+      </div>
+    </section>
+
+    <!-- Share the verdict (letters only) -->
+    <div class="share-row" id="share-row" hidden>
+      <button type="button" class="cta cta--share" id="share-btn">📤 Share my panic level</button>
+    </div>
+
+    <!-- Refusal panel -->
+    <section class="card refusal" id="refusal" hidden>
+      <h2 id="refusal-title">🙀 Hold on…</h2>
+      <p class="prose" id="refusal-guidance"></p>
+    </section>
+
+    <!-- Example gallery -->
+    <section class="gallery-section">
+      <h2>👇 No scary letter handy? Borrow one of mine</h2>
+      <p class="gallery-section__hint">Tap any example — I've already read these, so it costs you <strong>zero GPU</strong>.</p>
+      <div class="gallery" id="gallery"></div>
+    </section>
+  </main>
+
+  <footer class="footer">
+    <p>Everything runs on a small model inside this Space. Nothing is sent to external APIs.
+       Nothing is stored after your session ends.</p>
+    <p>Bureaucat explains letters — it does not give legal advice.
+       For legal matters, consult a qualified professional.</p>
+  </footer>
+
+  <button id="sound-toggle" class="sound-toggle" type="button" title="Sound on — click to mute">🔊</button>
+
+  <script type="module" src="/static/app.js?v=20260614g"></script>
+</body>
+</html>

frontend/style.css

@@ -0,0 +1,446 @@
+/* Bureaucat — Off-Brand custom frontend (Phase 4)
+   Brand language carried over from the Blocks UI: cream page, Fredoka type,
+   pink/lime accents, amber value pills, the 5-step severity color ramp. */
+
+:root {
+  --bg: #FFFDF5;
+  --ink: #2B2A26;
+  --muted: #7A766C;
+  --card: #FFFFFF;
+  --line: #EFE9D9;
+  --pink: #E91E63;
+  --lime: #84CC16;
+  --amber-bg: #FFF3CD;
+  --amber-ink: #8B6914;
+  --radius: 18px;
+  --shadow: 0 6px 24px rgba(43, 42, 38, 0.07);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #12131A;
+    --ink: #F0EEE6;
+    --muted: #A39F93;
+    --card: #1C1E27;
+    --line: #2A2D3A;
+    --shadow: 0 6px 24px rgba(0, 0, 0, 0.35);
+  }
+}
+
+* { box-sizing: border-box; }
+
+/* display:grid/flex on a class would otherwise beat the UA's [hidden] rule */
+[hidden] { display: none !important; }
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font-family: "Fredoka", ui-sans-serif, system-ui, sans-serif;
+  line-height: 1.55;
+}
+
+main { max-width: 980px; margin: 0 auto; padding: 0 20px 40px; }
+
+/* ---- Hero ---- */
+.hero {
+  max-width: 980px;
+  margin: 0 auto;
+  padding: 28px 20px 10px;
+  display: flex;
+  align-items: center;
+  gap: 18px;
+}
+.hero__cat {
+  width: 84px; height: 84px;
+  object-fit: contain;
+  filter: drop-shadow(0 4px 10px rgba(0,0,0,0.12));
+}
+.hero__text h1 {
+  margin: 0;
+  font-size: 40px;
+  font-weight: 700;
+  letter-spacing: 0.5px;
+  background: linear-gradient(90deg, var(--pink), #FF8A3D);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+.hero__text p { margin: 2px 0 0; color: var(--muted); font-size: 17px; }
+
+/* ---- Cards ---- */
+.card {
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  padding: 20px;
+}
+
+/* ---- Upload ---- */
+.upload-card { margin-top: 16px; display: grid; grid-template-columns: 1.6fr 1fr; gap: 18px; }
+@media (max-width: 720px) { .upload-card { grid-template-columns: 1fr; } }
+
+.dropzone {
+  border: 2.5px dashed var(--line);
+  border-radius: var(--radius);
+  min-height: 140px;
+  display: flex; align-items: center; justify-content: center;
+  cursor: pointer;
+  transition: border-color .15s ease, background .15s ease;
+  padding: 14px;
+}
+.dropzone:hover, .dropzone:focus-visible, .dropzone.is-dragover {
+  border-color: var(--pink);
+  background: color-mix(in srgb, var(--pink) 5%, transparent);
+  outline: none;
+}
+/* After a verdict: the dropzone becomes an obvious, highlighted target for the next letter. */
+.dropzone--ready {
+  border-color: var(--lime);
+  background: color-mix(in srgb, var(--lime) 9%, transparent);
+  animation: dz-ready-pulse 1.5s ease-out 3;
+}
+.dropzone--ready .dropzone__icon { animation: dz-icon-bob 1.5s ease-in-out 3; }
+@keyframes dz-ready-pulse {
+  0%   { box-shadow: 0 0 0 0 color-mix(in srgb, var(--lime) 55%, transparent); }
+  100% { box-shadow: 0 0 0 14px color-mix(in srgb, var(--lime) 0%, transparent); }
+}
+@keyframes dz-icon-bob { 0%,100% { transform: translateY(0); } 50% { transform: translateY(-6px); } }
+
+.dropzone__idle { display: flex; flex-direction: column; align-items: center; gap: 4px; text-align: center; }
+.dropzone__icon { font-size: 34px; }
+.dropzone__hint { color: var(--muted); font-size: 13.5px; }
+.dropzone__files { list-style: none; margin: 0; padding: 0; width: 100%; }
+.dropzone__files li {
+  display: flex; align-items: center; gap: 8px;
+  font-size: 14px; padding: 4px 8px;
+}
+.dropzone__files li::before { content: "📄"; }
+
+.upload-card__controls { display: flex; flex-direction: column; gap: 14px; justify-content: center; }
+
+.beginner-toggle {
+  display: flex; align-items: center; gap: 10px;
+  font-size: 14.5px; cursor: pointer; user-select: none;
+}
+.beginner-toggle input { position: absolute; opacity: 0; }
+.beginner-toggle__track {
+  flex: 0 0 auto;
+  width: 42px; height: 24px; border-radius: 12px;
+  background: var(--line); position: relative; transition: background .15s ease;
+}
+.beginner-toggle__track::after {
+  content: ""; position: absolute; top: 3px; left: 3px;
+  width: 18px; height: 18px; border-radius: 50%;
+  background: #fff; box-shadow: 0 1px 3px rgba(0,0,0,.25);
+  transition: left .15s ease;
+}
+.beginner-toggle input:checked + .beginner-toggle__track { background: var(--lime); }
+.beginner-toggle input:checked + .beginner-toggle__track::after { left: 21px; }
+
+.cta {
+  font-family: inherit;
+  font-size: 19px; font-weight: 600;
+  padding: 14px 22px;
+  border: none; border-radius: 14px;
+  background: var(--pink); color: #fff;
+  cursor: pointer;
+  box-shadow: 0 5px 16px color-mix(in srgb, var(--pink) 45%, transparent);
+  transition: transform .1s ease, filter .15s ease;
+}
+.cta:hover:not(:disabled) { filter: brightness(1.07); transform: translateY(-1px); }
+.cta:disabled { opacity: .45; cursor: not-allowed; box-shadow: none; }
+
+/* ---- Action buttons (Read it for me + Read another) sit together by the upload ---- */
+.upload-card__buttons { display: flex; flex-wrap: wrap; gap: 12px; justify-content: center; }
+.upload-card__buttons .cta { flex: 1 1 auto; }
+.cta--again {
+  background: var(--lime);
+  color: #2B3A0E;
+  box-shadow: 0 5px 16px color-mix(in srgb, var(--lime) 45%, transparent);
+}
+.cta--again[hidden] { display: none; }
+
+/* ---- "Verdict for <letter>" attribution chip ---- */
+.read-source {
+  display: flex; align-items: center; gap: 12px;
+  margin-top: 18px; padding: 10px 14px;
+  border: 1px solid var(--line); border-radius: 12px;
+  background: color-mix(in srgb, var(--pink) 4%, transparent);
+}
+.read-source__thumb {
+  width: 42px; height: 54px; flex: 0 0 auto;
+  object-fit: cover; object-position: top;
+  border-radius: 6px; border: 1px solid var(--line); background: #fff;
+}
+.read-source__meta { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
+.read-source__eyebrow { font-size: 12px; color: var(--muted); }
+.read-source__meta strong { font-size: 15px; word-break: break-word; }
+
+/* ---- Stage (mascot + verdict) ---- */
+.stage {
+  margin-top: 22px;
+  display: grid; grid-template-columns: 240px 1fr; gap: 20px;
+  align-items: center;
+}
+@media (max-width: 720px) { .stage { grid-template-columns: 1fr; text-align: center; } }
+
+.stage__mascot { display: flex; flex-direction: column; align-items: center; gap: 8px; }
+.mascot { width: 200px; height: 200px; object-fit: contain; }
+.stage__status { color: var(--muted); font-size: 14px; min-height: 20px; }
+
+/* Mascot state animations (mirrors the Blocks keyframes) */
+.mascot--reading   { animation: bcat-sway 1.1s ease-in-out infinite; }
+.mascot--verifying { animation: bcat-pulse 0.7s ease-in-out infinite; }
+.mascot--allclear  { animation: bcat-bounce 0.9s ease; }
+.mascot--deadline,
+.mascot--money     { animation: bcat-shake 0.5s ease 2; }
+.mascot--confused,
+.mascot--wrong_document { animation: bcat-tilt 0.8s ease; }
+
+@keyframes bcat-sway   { 0%,100% { transform: rotate(-3deg); } 50% { transform: rotate(3deg); } }
+@keyframes bcat-pulse  { 0%,100% { transform: scale(1); } 50% { transform: scale(1.06); } }
+@keyframes bcat-bounce { 0% { transform: translateY(0); } 35% { transform: translateY(-18px); } 70% { transform: translateY(0); } 85% { transform: translateY(-7px); } 100% { transform: translateY(0); } }
+@keyframes bcat-shake  { 0%,100% { transform: translateX(0); } 25% { transform: translateX(-7px); } 75% { transform: translateX(7px); } }
+@keyframes bcat-tilt   { 0% { transform: rotate(0); } 40% { transform: rotate(-9deg); } 100% { transform: rotate(0); } }
+
+/* ---- Panic-o-meter gauge ---- */
+.panic__placeholder {
+  border: 1.5px dashed var(--line); border-radius: var(--radius);
+  padding: 22px; color: var(--muted); text-align: center; font-size: 16px;
+}
+.panic-gauge { text-align: center; animation: gauge-in .35s ease; }
+@keyframes gauge-in { from { transform: scale(.85); opacity: 0; } to { transform: scale(1); opacity: 1; } }
+.panic-gauge__title {
+  font-weight: 700; letter-spacing: 2px; font-size: 13px;
+  color: var(--muted); text-transform: uppercase; margin-bottom: 2px;
+}
+.panic-gauge__svg { width: 240px; max-width: 100%; height: auto; display: block; margin: 0 auto; }
+.panic-gauge__svg .gauge-needle { fill: var(--ink); }
+.panic-gauge__svg .gauge-tick { fill: var(--muted); }
+.panic-gauge__readout {
+  display: flex; align-items: center; justify-content: center; gap: 10px; margin-top: -4px;
+}
+.panic-gauge__face { font-size: 34px; line-height: 1; animation: face-pop .5s ease; }
+@keyframes face-pop { 0% { transform: scale(.3); opacity: 0; } 60% { transform: scale(1.2); } 100% { transform: scale(1); opacity: 1; } }
+.panic-gauge__num { font-size: 30px; font-weight: 700; line-height: 1; }
+.panic-gauge__word { font-size: 18px; font-weight: 600; }
+
+/* ---- Quip speech bubble ---- */
+.quip {
+  margin-top: 14px;
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  padding: 13px 16px;
+  font-style: italic;
+  font-size: 16.5px;
+  position: relative;
+}
+.quip::before {
+  content: ""; position: absolute; left: -9px; top: 22px;
+  border: 9px solid transparent; border-right-color: var(--line);
+}
+.quip strong { color: var(--pink); font-style: normal; }
+
+/* ---- Deadline banner ---- */
+.deadline-banner {
+  margin-top: 20px;
+  background: var(--amber-bg);
+  color: var(--amber-ink);
+  border: 1.5px solid color-mix(in srgb, var(--amber-ink) 30%, transparent);
+  border-radius: var(--radius);
+  padding: 14px 18px;
+  font-size: 17px; font-weight: 600;
+  display: flex; align-items: center; gap: 10px;
+}
+.deadline-banner .value { text-decoration: underline; text-underline-offset: 3px; }
+/* Attention pulse for action-needed verdicts (non-celebratory) */
+.deadline-banner.pulse { animation: deadline-pulse 0.9s ease-out 2; }
+@keyframes deadline-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(255, 209, 102, 0); transform: scale(1); }
+  35%      { box-shadow: 0 0 0 6px rgba(255, 209, 102, 0.55); transform: scale(1.015); }
+}
+
+/* ---- Results grid ---- */
+.results {
+  margin-top: 20px;
+  display: grid; grid-template-columns: 1fr 1fr; gap: 16px;
+}
+@media (max-width: 720px) { .results { grid-template-columns: 1fr; } }
+.result-card--tldr { grid-column: 1 / -1; border-top: 4px solid var(--lime); }
+.result-card h2 { margin: 0 0 10px; font-size: 18px; }
+.prose { font-size: 15.5px; }
+.prose p { margin: 0 0 10px; }
+
+/* ---- Checklist ---- */
+.checklist { display: flex; flex-direction: column; gap: 8px; }
+.check-item {
+  display: flex; gap: 10px; align-items: flex-start;
+  padding: 9px 12px;
+  background: color-mix(in srgb, var(--lime) 7%, transparent);
+  border: 1px solid color-mix(in srgb, var(--lime) 25%, transparent);
+  border-radius: 12px;
+  cursor: pointer; font-size: 15px;
+}
+.check-item input { margin-top: 3px; accent-color: var(--lime); width: 17px; height: 17px; flex: 0 0 auto; }
+.check-item.done { opacity: .55; text-decoration: line-through; }
+
+/* ---- Deadlines list ---- */
+.deadlines { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 9px; }
+.deadlines li { font-size: 15px; }
+.deadlines mark {
+  background: var(--amber-bg); color: var(--amber-ink);
+  padding: 3px 7px; border-radius: 6px; font-weight: 600;
+}
+.deadlines .none { color: var(--muted); }
+
+/* ---- Grounding badge ---- */
+.grounding { margin-top: 14px; font-size: 13.5px; border-radius: 10px; padding: 9px 12px; }
+.grounding.ok   { background: color-mix(in srgb, var(--lime) 12%, transparent); color: #3F6212; }
+.grounding.fail { background: #FDECEA; color: #B71C1C; font-weight: 600; }
+@media (prefers-color-scheme: dark) {
+  .grounding.ok { color: #B5E48C; }
+  .grounding.fail { background: #3a1d1b; color: #FF8A80; }
+}
+
+/* ---- Refusal ---- */
+.refusal { margin-top: 20px; border-top: 4px solid #E67E22; }
+
+/* ---- Gallery ---- */
+.gallery-section { margin-top: 34px; }
+.gallery-section h2 { font-size: 20px; margin-bottom: 2px; }
+.gallery-section__hint { color: var(--muted); margin-top: 0; font-size: 14.5px; }
+.gallery {
+  display: grid; grid-template-columns: repeat(5, 1fr); gap: 12px;
+}
+@media (max-width: 860px) { .gallery { grid-template-columns: repeat(3, 1fr); } }
+@media (max-width: 560px) { .gallery { grid-template-columns: repeat(2, 1fr); } }
+.gallery__item {
+  background: var(--card); border: 1px solid var(--line); border-radius: 14px;
+  padding: 8px; cursor: pointer; text-align: center;
+  transition: transform .12s ease, border-color .12s ease;
+  font-family: inherit; color: var(--ink);
+}
+.gallery__item:hover { transform: translateY(-3px); border-color: var(--pink); }
+.gallery__item img { width: 100%; aspect-ratio: 3/4; object-fit: cover; border-radius: 9px; }
+.gallery__item span { display: block; font-size: 12px; margin-top: 6px; color: var(--muted); }
+
+/* ---- Verdict screen flash (full-viewport edge pulse) ---- */
+.screen-flash { position: fixed; inset: 0; pointer-events: none; z-index: 9998; }
+.screen-flash--good { animation: flash-good 0.9s ease-out forwards; }
+.screen-flash--alert { animation: flash-alert 0.6s ease-out 2; }
+@keyframes flash-good {
+  0%   { box-shadow: inset 0 0 0 0 rgba(132,204,22,0); }
+  30%  { box-shadow: inset 0 0 160px 30px rgba(132,204,22,0.45); }
+  100% { box-shadow: inset 0 0 0 0 rgba(132,204,22,0); }
+}
+@keyframes flash-alert {
+  0%   { box-shadow: inset 0 0 0 0 rgba(192,57,43,0); }
+  35%  { box-shadow: inset 0 0 180px 40px rgba(192,57,43,0.5); }
+  100% { box-shadow: inset 0 0 0 0 rgba(192,57,43,0); }
+}
+
+/* ---- Sound toggle ---- */
+.sound-toggle {
+  position: fixed; bottom: 16px; right: 16px; z-index: 9999;
+  width: 44px; height: 44px; border-radius: 50%;
+  border: 1px solid var(--line); background: var(--card); color: var(--ink);
+  font-size: 20px; cursor: pointer; box-shadow: var(--shadow);
+  display: flex; align-items: center; justify-content: center;
+  transition: transform .12s ease;
+}
+.sound-toggle:hover { transform: scale(1.08); }
+
+/* ---- Footer ---- */
+.footer {
+  max-width: 980px; margin: 30px auto 0; padding: 18px 20px 34px;
+  border-top: 1px solid var(--line);
+  color: var(--muted); font-size: 13px; text-align: center;
+}
+.footer p { margin: 4px 0; }
+
+/* ============================================================
+   Engagement pass: countdowns, skeleton, panic reveal, share
+   ============================================================ */
+
+/* ---- Deadline countdown pills ---- */
+.cd {
+  display: inline-block; margin-left: 6px;
+  padding: 1px 9px; border-radius: 999px;
+  font-size: 12.5px; font-weight: 600; white-space: nowrap;
+  vertical-align: middle;
+}
+.cd--overdue { background: #FDE2E1; color: #B3261E; }
+.cd--soon    { background: #FDECD2; color: #9A5B00; }
+.cd--near    { background: #FFF3CD; color: #8B6914; }
+.cd--far     { background: var(--line); color: var(--muted); }
+@media (prefers-color-scheme: dark) {
+  .cd--overdue { background: #4A1F1C; color: #FFB4AB; }
+  .cd--soon    { background: #432F12; color: #FFD8A8; }
+  .cd--near    { background: #3A340F; color: #F2D98D; }
+}
+
+/* ---- Skeleton shimmer while reading ---- */
+.skeleton { max-width: 980px; margin: 22px auto 0; display: grid; gap: 14px; }
+.skel-card {
+  height: 96px; border-radius: var(--radius);
+  background: linear-gradient(100deg,
+    var(--card) 30%, color-mix(in srgb, var(--line) 60%, var(--card)) 50%, var(--card) 70%);
+  background-size: 220% 100%;
+  border: 1px solid var(--line);
+  animation: skel-shimmer 1.25s ease-in-out infinite;
+}
+.skel-card--tall { height: 150px; }
+@keyframes skel-shimmer { 0% { background-position: 180% 0; } 100% { background-position: -80% 0; } }
+
+/* ---- Panic reveal: number pop + severity colour-wash + alarm aura ---- */
+.panic-gauge__num.num-pop { animation: num-pop 0.18s ease; }
+@keyframes num-pop { 0% { transform: scale(1); } 45% { transform: scale(1.35); } 100% { transform: scale(1); } }
+
+.stage {
+  border-radius: var(--radius);
+  transition: background 0.4s ease, box-shadow 0.4s ease;
+}
+/* faint wash in the verdict's severity colour (set via --sev on the stage) */
+.stage[style*="--sev"] {
+  background:
+    radial-gradient(120% 90% at 50% 0%, color-mix(in srgb, var(--sev) 12%, transparent), transparent 70%);
+}
+.stage--alarm { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sev) 35%, transparent); }
+.stage--alarm .mascot { animation: bcat-alarm 0.5s ease-in-out 3; }
+@keyframes bcat-alarm {
+  0%,100% { transform: translateX(0) rotate(0); }
+  25% { transform: translateX(-5px) rotate(-3deg); }
+  75% { transform: translateX(5px) rotate(3deg); }
+}
+
+/* ---- Quip as a cat speech bubble ---- */
+.quip {
+  position: relative;
+  background: var(--card);
+  border: 1.5px solid var(--line);
+  border-radius: 16px;
+  padding: 12px 16px;
+  box-shadow: var(--shadow);
+}
+.quip::before {
+  content: ""; position: absolute; left: 26px; top: -9px;
+  width: 16px; height: 16px; background: var(--card);
+  border-left: 1.5px solid var(--line); border-top: 1.5px solid var(--line);
+  transform: rotate(45deg);
+}
+
+/* ---- Share button ---- */
+.share-row { display: flex; justify-content: center; margin-top: 18px; }
+.cta--share {
+  background: linear-gradient(135deg, var(--pink), #FF6FA5);
+  color: #fff;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skel-card { animation: none; }
+  .panic-gauge__num.num-pop { animation: none; }
+  .stage--alarm .mascot { animation: none; }
+}

requirements.txt

@@ -0,0 +1,25 @@
+# Bureaucat — HF Space dependency manifest
+# Pinned to documented ZeroGPU-compatible versions as of 2026-06-05.
+# torch 2.11.0 is the confirmed ZeroGPU ceiling; do not upgrade to 2.12.0
+# in the Space until ZeroGPU docs explicitly list it (local dev may use 2.12.0).
+# Do NOT add flash-attn — not required (we use attn_implementation="sdpa").
+#
+# torchvision IS required (correction, 2026-06-13): transformers 5.10.2's
+# Qwen3-VL AutoProcessor eagerly loads Qwen3VLVideoProcessor, which has a HARD
+# torchvision backend requirement — even for image-only inference. Without it
+# the Space dies at load_model() with ImportError (RUNTIME_ERROR on first boot).
+# 0.26.0 is the torchvision release paired with torch 2.11.0 (local dev runs
+# torch 2.12.0 + torchvision 0.27.0, which is why this was masked locally).
+
+gradio==6.16.0
+spaces==0.50.4
+torch==2.11.0
+torchvision==0.26.0
+transformers==5.10.2
+accelerate==1.13.0
+qwen-vl-utils==0.0.14
+pillow>=10.0.0
+# pypdfium2 5.9.0 — Apache/BSD, self-contained (no system poppler/apt required).
+# Linux manylinux_2_17_x86_64 wheel confirmed on PyPI 2026-06-06 (ABI3 / py3-none).
+# Used for server-side PDF → PIL Image rendering (INPUT-02).
+pypdfium2==5.9.0

tests/test_doctype_refusal.py

@@ -0,0 +1,322 @@
+"""
+tests/test_doctype_refusal.py — DOCTYPE refusal parser + routing tests (Phase 3, TRUST-02/03/04).
+
+Two-tier test structure:
+  (a) No-model unit tests — BUREAUCAT_NO_MODEL=1 import; feed synthetic raw strings
+      to parse_output, assert doctype classification and render_result routing.
+      These run under: BUREAUCAT_NO_MODEL=1 python -m pytest tests/test_doctype_refusal.py -k "not integration"
+
+  (b) MPS integration tests — marked "integration"; skipif when BUREAUCAT_NO_MODEL=1.
+      These load each adversarial fixture image, run run_inference, and assert the
+      emitted doctype matches the sidecar's expected_doctype. Run only with weights.
+      These are SKIPPED in the unit test run (no GPU quota cost).
+"""
+
+import json
+import os
+import sys
+import unittest
+from pathlib import Path
+
+# ---- escape hatch: must be set BEFORE importing app ----
+os.environ["BUREAUCAT_NO_MODEL"] = "1"
+
+# Ensure project root is on sys.path
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+import app  # noqa: E402 (after path setup and NO_MODEL set)
+from app import StructuredResult, parse_output, render_result, run_verifying_state  # noqa: E402
+
+_ADVERSARIAL_DIR = Path(_REPO_ROOT) / "data" / "letters" / "public" / "adversarial"
+
+
+# ===========================================================================
+# Tier (a): No-model unit tests — parse_output + render_result routing
+# ===========================================================================
+
+class TestParseDoctypeExtraction(unittest.TestCase):
+    """parse_output() correctly extracts all four DOCTYPE values and defaults to 'letter'."""
+
+    def _parse(self, raw: str):
+        return parse_output(raw)
+
+    def test_not_letter_doctype(self):
+        raw = "<transcription>a</transcription>\nDOCTYPE: not_letter\nBureaucat says: That's a receipt, not a letter."
+        result = self._parse(raw)
+        self.assertEqual(result.doctype, "not_letter")
+
+    def test_unreadable_doctype(self):
+        raw = "<transcription>??</transcription>\nDOCTYPE: unreadable\nBureaucat says: I squinted and saw nothing."
+        result = self._parse(raw)
+        self.assertEqual(result.doctype, "unreadable")
+
+    def test_non_swedish_doctype(self):
+        raw = "<transcription>This is in English.</transcription>\nDOCTYPE: non_swedish\nBureaucat says: This one's not Swedish."
+        result = self._parse(raw)
+        self.assertEqual(result.doctype, "non_swedish")
+
+    def test_letter_doctype_explicit(self):
+        raw = (
+            "<transcription>Skatteverket text.</transcription>\n"
+            "DOCTYPE: letter\n"
+            "Bureaucat says: A tax letter.\n"
+            "## TL;DR\nYou owe tax.\n"
+            "## Why you got this\nBecause taxes.\n"
+            "## What you need to do\nPay.\n"
+            "## Deadlines & money\n- 1 jan 2027 — deadline\n"
+            "SEVERITY: 3"
+        )
+        result = self._parse(raw)
+        self.assertEqual(result.doctype, "letter")
+
+    def test_missing_sentinel_defaults_to_letter(self):
+        """No DOCTYPE line → defaults to 'letter' (D3-02 lean-toward-analyzing)."""
+        result = self._parse("no sentinel here at all")
+        self.assertEqual(result.doctype, "letter")
+
+    def test_empty_input_defaults_to_letter_and_none_severity(self):
+        """Empty input → doctype='letter', severity=None, never raises."""
+        result = self._parse("")
+        self.assertEqual(result.doctype, "letter")
+        self.assertIsNone(result.severity)
+
+    def test_doctype_case_insensitive(self):
+        """Regex is IGNORECASE — uppercase variant still parsed."""
+        raw = "<transcription>x</transcription>\nDOCTYPE: NOT_LETTER\nBureaucat says: nope"
+        result = self._parse(raw)
+        self.assertEqual(result.doctype, "not_letter")
+
+    def test_doctype_not_leaked_into_tldr(self):
+        """DOCTYPE line is stripped from body before section split — must not appear in tldr."""
+        raw = (
+            "<transcription>a</transcription>\n"
+            "DOCTYPE: letter\n"
+            "Bureaucat says: hi\n"
+            "## TL;DR\nhello world\n"
+            "## Why you got this\nbecause\n"
+            "## What you need to do\npay\n"
+            "## Deadlines & money\n- 1 jan 2027 — deadline\n"
+            "SEVERITY: 2"
+        )
+        result = self._parse(raw)
+        self.assertNotIn("DOCTYPE", result.tldr)
+        self.assertEqual(result.severity, 2)
+
+    def test_doctype_not_leaked_into_why(self):
+        raw = (
+            "<transcription>a</transcription>\n"
+            "DOCTYPE: letter\nBureaucat says: hi\n"
+            "## TL;DR\nhello\n"
+            "## Why you got this\nsome reason\n"
+            "## What you need to do\npay\n"
+            "## Deadlines & money\n- none\nSEVERITY: 1"
+        )
+        result = self._parse(raw)
+        self.assertNotIn("DOCTYPE", result.why)
+
+
+class TestRenderResultRefusalRouting(unittest.TestCase):
+    """render_result() routes doctype != 'letter' to refusal branch BEFORE malformed branch."""
+
+    def _make_refusal(self, doctype: str, quip: str = "Nope!") -> StructuredResult:
+        return StructuredResult(
+            transcription="", quip=quip, tldr="", why="", actions="", deadlines="",
+            severity=None, raw="", doctype=doctype,
+        )
+
+    def _make_malformed(self) -> StructuredResult:
+        """letter + severity=None → malformed path (unchanged from Phase 2)."""
+        return StructuredResult(
+            transcription="", quip="", tldr="", why="", actions="", deadlines="",
+            severity=None, raw="", doctype="letter",
+        )
+
+    def test_not_letter_gets_wrong_document_mascot(self):
+        t = render_result(self._make_refusal("not_letter"), "English")
+        self.assertIn("wrong_document.png", t[1])
+
+    def test_not_letter_has_empty_panic_html(self):
+        t = render_result(self._make_refusal("not_letter"), "English")
+        self.assertEqual(t[0], "", "Panic Meter must be empty string on refusal (D3-03)")
+
+    def test_non_swedish_gets_wrong_document_mascot(self):
+        t = render_result(self._make_refusal("non_swedish"), "English")
+        self.assertIn("wrong_document.png", t[1])
+
+    def test_non_swedish_guidance_mentions_swedish(self):
+        t = render_result(self._make_refusal("non_swedish"), "English")
+        tldr_value = t[3]  # gr.update dict
+        guidance_text = tldr_value.get("value", "")
+        self.assertIn("Swedish", guidance_text)
+
+    def test_unreadable_gets_confused_mascot(self):
+        u = render_result(self._make_refusal("unreadable"), "English")
+        self.assertIn("confused.png", u[1])
+
+    def test_unreadable_has_empty_panic_html(self):
+        u = render_result(self._make_refusal("unreadable"), "English")
+        self.assertEqual(u[0], "")
+
+    def test_letter_severity_none_still_malformed_path(self):
+        """doctype='letter' + severity=None → original malformed ERROR_COPY path (unchanged)."""
+        m = render_result(self._make_malformed(), "English")
+        tldr_value = m[3]
+        guidance_text = tldr_value.get("value", "")
+        self.assertIn("Bureaucat had trouble", guidance_text)
+
+    def test_refusal_returns_7_tuple(self):
+        t = render_result(self._make_refusal("not_letter"), "English")
+        self.assertEqual(len(t), 7)
+
+    def test_refusal_quip_rendered(self):
+        """Model's in-voice quip is passed through render_quip."""
+        t = render_result(self._make_refusal("not_letter", quip="That's a receipt!"), "English")
+        # quip_md is index 2
+        self.assertIn("receipt", t[2])
+
+    def test_refusal_empty_sections(self):
+        """why_out, actions_out are empty on refusal (no four-section analysis)."""
+        t = render_result(self._make_refusal("not_letter"), "English")
+        why_text = t[4].get("value", "")
+        actions_text = t[5].get("value", "")
+        self.assertEqual(why_text, "")
+        self.assertEqual(actions_text, "")
+
+
+class TestRunVerifyingStateRefusalBypass(unittest.TestCase):
+    """run_verifying_state bypasses check_no_invention on doctype != 'letter'."""
+
+    def _make_refusal(self, doctype: str) -> StructuredResult:
+        return StructuredResult(
+            transcription="", quip="", tldr="", why="", actions="", deadlines="",
+            severity=None, raw="", doctype=doctype,
+        )
+
+    def test_not_letter_returns_wrong_document_mascot(self):
+        result = run_verifying_state(self._make_refusal("not_letter"))
+        self.assertIn("wrong_document.png", result)
+
+    def test_unreadable_returns_confused_mascot(self):
+        result = run_verifying_state(self._make_refusal("unreadable"))
+        self.assertIn("confused.png", result)
+
+    def test_non_swedish_returns_wrong_document_mascot(self):
+        result = run_verifying_state(self._make_refusal("non_swedish"))
+        self.assertIn("wrong_document.png", result)
+
+    def test_refusal_does_not_raise(self):
+        """check_no_invention would raise/error on empty values — guard must prevent that."""
+        # The refusal guard ensures check_no_invention is NEVER called on a refusal.
+        # If the guard works, this test passes without exception.
+        try:
+            run_verifying_state(self._make_refusal("not_letter"))
+        except Exception as exc:  # noqa: BLE001
+            self.fail(f"run_verifying_state raised on refusal: {exc}")
+
+
+class TestAdversarialSidecarSchema(unittest.TestCase):
+    """Adversarial JSON sidecars have the correct schema and expected_doctype values."""
+
+    def _load_sidecar(self, slug: str) -> dict:
+        path = _ADVERSARIAL_DIR / f"{slug}.json"
+        self.assertTrue(path.exists(), f"Sidecar not found: {path}")
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def test_blurry_unreadable_sidecar(self):
+        data = self._load_sidecar("blurry_unreadable")
+        self.assertEqual(data["fixture_type"], "adversarial")
+        self.assertEqual(data["expected_doctype"], "unreadable")
+        self.assertIsNone(data["expected_severity"])
+
+    def test_non_letter_receipt_sidecar(self):
+        data = self._load_sidecar("non_letter_receipt")
+        self.assertEqual(data["fixture_type"], "adversarial")
+        self.assertEqual(data["expected_doctype"], "not_letter")
+        self.assertIsNone(data["expected_severity"])
+
+    def test_non_swedish_english_sidecar(self):
+        # Phase-3 decision (builder-approved): the model classifies a non-Swedish *letter*
+        # as not_letter, not non_swedish; forcing the distinction regressed reference recall
+        # on real Swedish letters (reverted). Both route to the same refusal UX, so the
+        # fixture's expected refusal is scored as not_letter. The non_swedish render path
+        # remains exercised by the render-layer tests above (e.g. test_non_swedish_*).
+        data = self._load_sidecar("non_swedish_english")
+        self.assertEqual(data["fixture_type"], "adversarial")
+        self.assertEqual(data["expected_doctype"], "not_letter")
+        self.assertIsNone(data["expected_severity"])
+
+    def test_fixture_pngs_exist(self):
+        for slug in ("blurry_unreadable", "non_letter_receipt", "non_swedish_english"):
+            png = _ADVERSARIAL_DIR / f"{slug}.png"
+            self.assertTrue(png.exists(), f"PNG fixture missing: {png}")
+
+
+# ===========================================================================
+# Tier (b): MPS integration tests — skipped when BUREAUCAT_NO_MODEL=1
+# ===========================================================================
+
+import pytest  # noqa: E402
+
+
+@pytest.mark.skipif(
+    os.getenv("BUREAUCAT_NO_MODEL") == "1",
+    reason="Model weights not loaded (BUREAUCAT_NO_MODEL=1); skipping MPS integration tests",
+)
+class TestAdversarialMpsIntegration(unittest.TestCase):
+    """
+    Integration tests that run each adversarial fixture through run_inference
+    and assert the emitted doctype matches the fixture's expected_doctype.
+
+    SKIPPED under BUREAUCAT_NO_MODEL=1. Run only when weights are available.
+    The tests load the model inside the test body — not at module scope.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        """Load model once for all integration tests in this class."""
+        # Clear the NO_MODEL flag before loading so load_model actually loads
+        os.environ.pop("BUREAUCAT_NO_MODEL", None)
+        from app import load_model, MODEL_VARIANT, IMAGE_PATCH_SIZE
+        cls.mdl, cls.proc = load_model(MODEL_VARIANT)
+        cls.image_patch_size = IMAGE_PATCH_SIZE
+
+    def _run_fixture(self, slug: str):
+        from PIL import Image
+        from app import run_inference
+        png_path = _ADVERSARIAL_DIR / f"{slug}.png"
+        json_path = _ADVERSARIAL_DIR / f"{slug}.json"
+        image = Image.open(png_path)
+        gold = json.loads(json_path.read_text(encoding="utf-8"))
+        result = run_inference(
+            image, "English", beginner_mode=False,
+            mdl=self.mdl, proc=self.proc,
+            image_patch_size=self.image_patch_size,
+        )
+        return result, gold
+
+    def test_blurry_unreadable_integration(self):
+        result, gold = self._run_fixture("blurry_unreadable")
+        self.assertEqual(
+            result.doctype, gold["expected_doctype"],
+            f"blurry_unreadable: expected doctype={gold['expected_doctype']!r}, got {result.doctype!r}",
+        )
+
+    def test_non_letter_receipt_integration(self):
+        result, gold = self._run_fixture("non_letter_receipt")
+        self.assertEqual(
+            result.doctype, gold["expected_doctype"],
+            f"non_letter_receipt: expected doctype={gold['expected_doctype']!r}, got {result.doctype!r}",
+        )
+
+    def test_non_swedish_english_integration(self):
+        result, gold = self._run_fixture("non_swedish_english")
+        self.assertEqual(
+            result.doctype, gold["expected_doctype"],
+            f"non_swedish_english: expected doctype={gold['expected_doctype']!r}, got {result.doctype!r}",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_gallery.py

@@ -0,0 +1,225 @@
+"""
+tests/test_gallery.py — Zero-GPU gallery loader tests (Plan 02-04, UI-01).
+
+Verifies:
+  (a) load_example returns a 7-element tuple matching render_result's output arity
+      and does NOT raise.
+  (b) load_example is NOT wrapped by @spaces.GPU and never calls the model —
+      run_inference_multi is patched to raise; load_example must still succeed.
+  (c) data/gallery/*-result.json fixtures round-trip into StructuredResult correctly
+      (severity is int or None, all fields present).
+
+BUREAUCAT_NO_MODEL=1 is set BEFORE import to prevent model weight loading.
+"""
+
+import json
+import os
+import sys
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+# ---- escape hatch: must be set BEFORE importing app ----
+os.environ["BUREAUCAT_NO_MODEL"] = "1"
+
+# Ensure project root is on sys.path when run from tests/ or project root
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+import app  # noqa: E402 (after path setup)
+from app import EXAMPLE_LETTERS, StructuredResult, load_example  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_GALLERY_DIR = Path(_REPO_ROOT) / "data" / "gallery"
+
+_STRUCTURED_RESULT_FIELDS = frozenset(
+    StructuredResult.__dataclass_fields__.keys()
+)
+
+_RENDER_RESULT_ARITY = 7  # (panic_html, mascot_html, quip_md, tldr, why, actions, deadlines_html)
+
+
+def _make_select_event(index: int):
+    """Return a SimpleNamespace that looks like gr.SelectData(index=N)."""
+    return types.SimpleNamespace(index=index)
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestExampleLettersList(unittest.TestCase):
+    """EXAMPLE_LETTERS has >= 4 entries with required keys."""
+
+    def test_length(self):
+        self.assertGreaterEqual(len(EXAMPLE_LETTERS), 4, "need >= 4 gallery entries")
+
+    def test_keys(self):
+        for entry in EXAMPLE_LETTERS:
+            for key in ("slug", "label", "image", "cached"):
+                self.assertIn(key, entry, f"missing key '{key}' in entry {entry}")
+
+    def test_image_paths_under_public(self):
+        for entry in EXAMPLE_LETTERS:
+            self.assertIn(
+                "data/letters/public/",
+                entry["image"],
+                f"image path should be under data/letters/public/: {entry['image']}",
+            )
+
+    def test_cached_paths_under_gallery(self):
+        for entry in EXAMPLE_LETTERS:
+            self.assertIn(
+                "data/gallery/",
+                entry["cached"],
+                f"cached path should be under data/gallery/: {entry['cached']}",
+            )
+
+
+class TestLoadExampleArity(unittest.TestCase):
+    """load_example returns correct arity without raising."""
+
+    def setUp(self):
+        """Skip if gallery JSONs don't exist yet (generated by Task 1)."""
+        json_path = Path(_REPO_ROOT) / EXAMPLE_LETTERS[0]["cached"]
+        if not json_path.exists():
+            self.skipTest(f"Gallery JSON not yet generated: {json_path}")
+
+    def test_returns_tuple_of_correct_arity(self):
+        """load_example(index=0) returns a 7-element tuple."""
+        evt = _make_select_event(0)
+        result_tuple = load_example(evt)
+        self.assertIsInstance(result_tuple, tuple)
+        self.assertEqual(
+            len(result_tuple),
+            _RENDER_RESULT_ARITY,
+            f"expected {_RENDER_RESULT_ARITY}-element tuple, got {len(result_tuple)}",
+        )
+
+    def test_all_indices(self):
+        """load_example works for every valid index in EXAMPLE_LETTERS."""
+        for i, entry in enumerate(EXAMPLE_LETTERS):
+            json_path = Path(_REPO_ROOT) / entry["cached"]
+            if not json_path.exists():
+                continue
+            with self.subTest(index=i, slug=entry["slug"]):
+                evt = _make_select_event(i)
+                tpl = load_example(evt)
+                self.assertEqual(len(tpl), _RENDER_RESULT_ARITY)
+
+
+class TestLoadExampleNoModelCall(unittest.TestCase):
+    """load_example never calls run_inference_multi — zero GPU guarantee."""
+
+    def setUp(self):
+        json_path = Path(_REPO_ROOT) / EXAMPLE_LETTERS[0]["cached"]
+        if not json_path.exists():
+            self.skipTest(f"Gallery JSON not yet generated: {json_path}")
+
+    def test_no_model_call_when_inference_patched_to_raise(self):
+        """
+        Even if run_inference_multi would raise, load_example still succeeds.
+        This proves load_example reads only disk (never calls the model).
+        """
+        def _boom(*args, **kwargs):
+            raise RuntimeError("load_example must NOT call run_inference_multi")
+
+        with patch.object(app, "run_inference_multi", side_effect=_boom):
+            evt = _make_select_event(0)
+            # Must NOT raise RuntimeError
+            result_tuple = load_example(evt)
+            self.assertEqual(len(result_tuple), _RENDER_RESULT_ARITY)
+
+    def test_load_example_not_spaces_gpu_wrapped(self):
+        """
+        load_example must not be decorated with @spaces.GPU.
+        Presence of __wrapped__ or _spaces_fn_wrapped attributes indicates GPU decoration.
+        """
+        self.assertFalse(
+            hasattr(load_example, "__wrapped__"),
+            "load_example should NOT be wrapped with @spaces.GPU (__wrapped__ found)",
+        )
+        self.assertFalse(
+            hasattr(load_example, "_spaces_fn_wrapped"),
+            "load_example should NOT be wrapped with @spaces.GPU (_spaces_fn_wrapped found)",
+        )
+
+
+class TestGalleryJsonFixtures(unittest.TestCase):
+    """data/gallery/*-result.json files round-trip into StructuredResult."""
+
+    def _iter_gallery_jsons(self):
+        """Yield (stem, dict) for each existing gallery JSON."""
+        for entry in EXAMPLE_LETTERS:
+            json_path = Path(_REPO_ROOT) / entry["cached"]
+            if json_path.exists():
+                yield entry["slug"], json.loads(json_path.read_text(encoding="utf-8"))
+
+    def test_all_fields_present(self):
+        found_any = False
+        for slug, data in self._iter_gallery_jsons():
+            found_any = True
+            with self.subTest(slug=slug):
+                missing = _STRUCTURED_RESULT_FIELDS - set(data.keys())
+                self.assertEqual(
+                    missing,
+                    set(),
+                    f"{slug}: missing StructuredResult fields: {missing}",
+                )
+
+        if not found_any:
+            self.skipTest("No gallery JSONs exist yet — run Task 1 first")
+
+    def test_severity_type(self):
+        found_any = False
+        for slug, data in self._iter_gallery_jsons():
+            found_any = True
+            with self.subTest(slug=slug):
+                sev = data.get("severity")
+                self.assertTrue(
+                    sev is None or isinstance(sev, int),
+                    f"{slug}: severity must be int or None, got {type(sev).__name__}",
+                )
+
+        if not found_any:
+            self.skipTest("No gallery JSONs exist yet — run Task 1 first")
+
+    def test_no_quip_prefix(self):
+        """quip field must NOT contain 'Bureaucat says:' prefix (prevents double-prefix)."""
+        found_any = False
+        for slug, data in self._iter_gallery_jsons():
+            found_any = True
+            with self.subTest(slug=slug):
+                quip = data.get("quip", "")
+                self.assertNotIn(
+                    "Bureaucat says:",
+                    quip,
+                    f"{slug}: quip contains 'Bureaucat says:' prefix — would double-prefix in UI",
+                )
+
+        if not found_any:
+            self.skipTest("No gallery JSONs exist yet — run Task 1 first")
+
+    def test_structured_result_roundtrip(self):
+        """StructuredResult(**data) does not raise for any gallery JSON."""
+        found_any = False
+        for slug, data in self._iter_gallery_jsons():
+            found_any = True
+            with self.subTest(slug=slug):
+                # Should not raise
+                result = StructuredResult(**data)
+                self.assertIsInstance(result, StructuredResult)
+                self.assertIsNotNone(result.raw, f"{slug}: raw field is None")
+
+        if not found_any:
+            self.skipTest("No gallery JSONs exist yet — run Task 1 first")
+
+
+if __name__ == "__main__":
+    unittest.main()