feat: serve designer React frontend via gradio.Server on ZeroGPU

README.md

@@ -3,14 +3,10 @@ title: Trace Field Notes
 colorFrom: green
 colorTo: gray
 sdk: gradio
-sdk_version: 5.50.0
+sdk_version: 6.16.0
 app_file: app.py
 pinned: false
 license: mit
-hf_oauth: true
-hf_oauth_scopes:
-  - inference-api
-hf_oauth_expiration_minutes: 480
 ---
 
 # Trace Field Notes
@@ -22,11 +18,27 @@ telemetry by default and analyzes only the agent's visible narrative messages:
 what it planned, where it got stuck, how it detoured, how it recovered, and how
 it claimed completion.
 
-Built for the Build Small Hackathon as a Gradio app. The default engine is the
-quick Qwen3.5 9B model-assisted path on ZeroGPU, with a verified deterministic
-codebook analyzer as the always-available recovery path. The app also exposes
-`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` through Hugging Face Inference
-Providers when the user signs in with Hugging Face OAuth.
+Built for the Build Small Hackathon. The frontend is a custom React field-notebook
+UI (a trail map of the session) served by `gradio.Server`; it calls the Python
+`analyze_trace` endpoint through `@gradio/client`. Both models run on the Space
+GPU through ZeroGPU: a quick `Qwen/Qwen3.5-9B` pass by default, and the larger
+`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` for deeper analysis. A verified
+deterministic codebook analyzer is the always-available recovery path and needs
+no model or GPU.
+
+## Architecture
+
+- `app.py` — a `gradio.Server` (FastAPI) app. It serves `frontend/index.html`,
+  mounts `frontend/static/`, exposes `@server.api("analyze_trace")` (queued, with
+  `gradio_client` compatibility), and an `/agents.md` instructions endpoint.
+- `frontend/` — the designer's React app (in-browser Babel, no build step):
+  `field_report.css` (the design system), `data.js` (codebook + tone labels),
+  `components.jsx` (atoms + trail map + report sections), `app.jsx` (shell +
+  upload, wired to the backend).
+- `view_model.py` — adapts an `AnalysisResult` into the JSON shape the frontend
+  renders (synthesizes the whole-session `verdict`, `captured`, `duration_total`).
+- `analyzer.py` / `parser.py` / `redaction.py` / `schemas.py` — the deterministic
+  pipeline. `model_runtime.py` — the optional small-model assist on ZeroGPU.
 
 ## Run Locally
 
@@ -45,18 +57,20 @@ python3.11 -m unittest discover -s tests
 
 ## Analysis Engines
 
-- `Quick small-model assist: Qwen3.5 9B`: default model-assisted memo.
-- `NVIDIA Nemotron 3 Nano 30B-A3B assist`: uses Nemotron through the signed-in
-  user's `inference-api` OAuth scope.
-- `Deterministic field notes`: local, no model dependency.
+- `Qwen3.5 9B — quick analysis`: default model pass on the Space GPU.
+- `NVIDIA Nemotron 3 Nano 30B-A3B — deeper analysis`: the larger model on the
+  Space GPU for a richer memo.
+- `Rule-based — instant, no model`: local codebook analyzer, no model or GPU.
 
-If a selected model is unavailable or the user is not signed in, the report
-records the reason in model notes and returns the deterministic analysis instead
-of failing the whole Space.
+If a model fails to load or returns invalid JSON, the report records the reason
+in model notes and returns the deterministic analysis instead of failing the
+whole Space.
 
-The Gradio endpoint is decorated with `@spaces.GPU` so the app can run on
-Hugging Face ZeroGPU hardware. The deterministic path still works without model
-weights; ZeroGPU only supplies the runtime contract and queueing surface.
+The model-backed analysis runs under `@spaces.GPU(size="xlarge")` so the weights
+load on Hugging Face ZeroGPU hardware; `Qwen/Qwen3.5-9B` and
+`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` are loaded with `transformers` and
+cached across requests. The rule-based engine runs on CPU and never requests a
+GPU slot, so it returns instantly.
 
 ## Agent Session Locations
 

analyzer.py

@@ -119,7 +119,6 @@ def analyze_trace_file(
     ignore_tool_calls: bool = True,
     report_style: str = "field_notes",
     analysis_engine: str = "deterministic",
-    hf_token: str | None = None,
 ) -> tuple[AnalysisResult, str]:
     """Parse, optionally redact, and analyze an uploaded trace file."""
 
@@ -193,7 +192,6 @@ def analyze_trace_file(
                     engine=analysis_engine,
                     result=result,
                     narrative_text=narrative_text,
-                    token=hf_token,
                 )
             except Exception as exc:
                 error_message = str(exc).strip().rstrip(".")

app.py

@@ -1,355 +1,132 @@
-"""Gradio entrypoint for the Trace Field Notes Hugging Face Space."""
+"""Trace Field Notes — gradio.Server backend behind the designer's React frontend.
+
+The custom frontend (``frontend/``) is served as static files; it talks to the
+``analyze_trace`` endpoint below through ``@gradio/client``. The endpoint runs the
+deterministic analyzer (and the optional small-model assist on ZeroGPU) and
+returns the frontend-ready view model.
+"""
 
 from __future__ import annotations
 
-import json
-import tempfile
+import os
 from pathlib import Path
-from typing import Any, Optional
 
-import gradio as gr
 import spaces
+from fastapi.responses import HTMLResponse, PlainTextResponse
+from fastapi.staticfiles import StaticFiles
+from gradio import Server
+from gradio.data_classes import FileData
 
 from analyzer import analyze_trace_file
-from model_runtime import MODEL_CHOICES
 from parser import TraceParseError
-from report_renderer import render_report
+from view_model import build_view_model
 
 
-SPACE_URL = "https://huggingface.co/spaces/build-small-hackathon/trace-field-notes"
-DEFAULT_ANALYSIS_ENGINE = "qwen"
-SAMPLE_TRACE_PATH = "examples/sample_trace_redacted.jsonl"
+HERE = Path(__file__).resolve().parent
+FRONTEND = HERE / "frontend"
 
-PRIVACY_WARNING = (
-    "Agent traces can contain prompts, tool inputs, command outputs, local file paths, "
-    "screenshots, secrets, private source code, and personal data. Redact before uploading. "
-    "This app analyzes only visible agent narrative messages by default and does not need raw tool outputs."
-)
+READABLE_AGENT = {"codex": "Codex", "claude_code": "Claude Code", "pi": "Pi Agent", "unknown": "Agent"}
 
-HERO_MD = """
-**ZeroGPU field report**
+AGENTS_MD = """# Trace Field Notes — agent instructions
 
-# Trace Field Notes
+This Space turns a coding-agent session log into a qualitative *field report*:
+where the agent got stuck, where it changed route, how it recovered, and how
+honestly it claimed success. It reads only the agent's visible narrative
+messages and ignores raw tool telemetry.
 
-Map where a coding agent got stuck, changed route, recovered, and claimed success.
-"""
+## How to use it as a tool
 
-SESSION_PATHS_MD = """
-### Session Logs
+1. Find the user's latest local session log:
+   - Codex: `~/.codex/sessions`
+   - Claude Code: `~/.claude/projects`
+   - Pi Agent: `~/.pi/agent/sessions`
+2. Review it and redact secrets, tokens, local paths, and private code first.
+3. Upload the `.jsonl` (`.json` / `.txt` / `.log` also accepted) and call the
+   `analyze_trace` API endpoint.
+4. Return the field report to the user. Do not publish the raw trace.
 
-| Agent | Local session directory |
-|---|---|
-| Codex | `~/.codex/sessions` |
-| Claude Code | `~/.claude/projects` |
-| Pi Agent | `~/.pi/agent/sessions` |
-"""
+## API
 
-AGENT_PROMPT = f"""Use this Space as a tool.
-1. Read: {SPACE_URL}/agents.md
-2. Find my latest local agent session log:
-   - Codex: ~/.codex/sessions
-   - Claude Code: ~/.claude/projects
-   - Pi Agent: ~/.pi/agent/sessions
-3. Review and redact secrets or private code before upload.
-4. Upload the JSONL to the Space.
-5. Ask for narrative difficulty analysis.
-6. Return the report. Do not publish the raw trace.
-"""
+`POST` via the Gradio client, endpoint `/analyze_trace`:
+
+- `trace_file` (file): the session log
+- `include_user_context` (bool): include user prompts as framing
+- `redact_secrets` (bool): redact likely secrets before analysis
+- `analysis_engine` (str): `qwen` | `nemotron` | `deterministic`
 
-CUSTOM_CSS = """
-:root {
-  --field-border: rgba(148, 163, 184, 0.28);
-  --field-ink: #f8fafc;
-  --field-muted: #94a3b8;
-  --field-panel: rgba(15, 23, 42, 0.74);
-  --field-panel-strong: rgba(15, 23, 42, 0.92);
-  --field-accent: #2f8a69;
-  --field-accent-strong: #23785d;
-}
-.gradio-container {
-  max-width: 1220px !important;
-  color: var(--field-ink);
-}
-.hero {
-  border: 1px solid var(--field-border);
-  border-radius: 8px;
-  padding: 18px 20px;
-  background: linear-gradient(135deg, rgba(47, 138, 105, 0.18), rgba(15, 23, 42, 0.3));
-}
-.hero h1 {
-  margin: 0;
-  font-size: 34px;
-  line-height: 1.08;
-}
-.hero p {
-  max-width: 760px;
-  margin: 10px 0 0;
-  color: var(--field-muted);
-  font-size: 15px;
-}
-.hero strong {
-  margin-bottom: 8px;
-  color: #7dd3fc;
-  font: 700 12px/1.2 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  text-transform: uppercase;
-  letter-spacing: 0;
-}
-.privacy-callout {
-  margin: 12px 0 16px;
-  border-left: 3px solid #f59e0b;
-  padding: 10px 12px;
-  color: #dbe4ef;
-  background: rgba(245, 158, 11, 0.08);
-  border-radius: 0 6px 6px 0;
-}
-.trace-panel {
-  border: 1px solid var(--field-border);
-  border-radius: 8px;
-  padding: 16px;
-  background: var(--field-panel);
-}
-.guide-panel {
-  border: 1px solid var(--field-border);
-  border-radius: 8px;
-  padding: 16px;
-  background: var(--field-panel);
-}
-.guide-panel table {
-  width: 100%;
-}
-.action-row button {
-  min-height: 42px;
-}
-button.primary {
-  background: var(--field-accent) !important;
-  border-color: var(--field-accent) !important;
-}
-button.primary:hover {
-  background: var(--field-accent-strong) !important;
-}
-.download-row {
-  align-items: stretch;
-}
-.result-tabs {
-  margin-top: 14px;
-}
-textarea, input {
-  border-radius: 6px !important;
-}
+Returns a JSON view model: a whole-session `verdict`, per-episode difficulty
+`episodes`, and redacted export text.
 """
 
 
-def _analyze_trace_impl(
-    trace_file: Any,
-    include_user_context: bool = True,
-    redact_secrets: bool = True,
-    ignore_tool_calls: bool = True,
-    report_style: str = "field_notes",
-    analysis_engine: str = DEFAULT_ANALYSIS_ENGINE,
-    oauth_token: Optional[gr.OAuthToken] = None,
-) -> tuple[str, dict[str, Any], str, str, str]:
-    """Gradio-callable analysis endpoint."""
+server = Server(title="Trace Field Notes")
+server.mount("/static", StaticFiles(directory=str(FRONTEND / "static")), name="static")
 
-    if trace_file is None:
-        raise gr.Error("Upload a .jsonl, .json, .txt, or .log trace file first.")
 
-    path = uploaded_path(trace_file)
-    try:
-        result, redacted_narrative = analyze_trace_file(
-            path,
-            include_user_context=include_user_context,
-            redact_secrets=redact_secrets,
-            ignore_tool_calls=ignore_tool_calls,
-            report_style=report_style,
-            analysis_engine=analysis_engine,
-            hf_token=oauth_token.token if oauth_token else None,
-        )
-    except TraceParseError as exc:
-        raise gr.Error(str(exc)) from exc
-    except Exception as exc:  # pragma: no cover - surfaced to the Space UI.
-        raise gr.Error(f"Analysis failed: {exc}") from exc
-
-    report_markdown = render_report(result)
-    result_json = result.to_dict()
-    redacted_file = write_temp_artifact("trace-field-notes-redacted-", ".md", redacted_narrative)
-    report_file = write_temp_artifact("trace-field-notes-report-", ".md", report_markdown)
-    json_file = write_temp_artifact(
-        "trace-field-notes-episodes-",
-        ".json",
-        json.dumps(result_json, indent=2, ensure_ascii=False) + "\n",
-    )
-    return report_markdown, result_json, redacted_file, report_file, json_file
+@server.get("/", response_class=HTMLResponse)
+def index() -> str:
+    return (FRONTEND / "index.html").read_text(encoding="utf-8")
 
 
-@spaces.GPU(duration=90)
-def analyze_trace(
-    trace_file: Any,
-    include_user_context: bool = True,
-    redact_secrets: bool = True,
-    ignore_tool_calls: bool = True,
-    report_style: str = "field_notes",
-    analysis_engine: str = DEFAULT_ANALYSIS_ENGINE,
-    oauth_token: Optional[gr.OAuthToken] = None,
-) -> tuple[str, dict[str, Any], str, str, str]:
-    """ZeroGPU-visible Gradio endpoint."""
-
-    return _analyze_trace_impl(
-        trace_file=trace_file,
+@server.get("/agents.md", response_class=PlainTextResponse)
+def agents_md() -> str:
+    return AGENTS_MD
+
+
+@spaces.GPU(size="xlarge", duration=180)
+def _analyze_on_gpu(
+    path: str,
+    include_user_context: bool,
+    redact_secrets: bool,
+    analysis_engine: str,
+):
+    """Model-backed analysis on the Space GPU (loads weights via transformers)."""
+
+    return analyze_trace_file(
+        path,
         include_user_context=include_user_context,
         redact_secrets=redact_secrets,
-        ignore_tool_calls=ignore_tool_calls,
-        report_style=report_style,
+        ignore_tool_calls=True,
         analysis_engine=analysis_engine,
-        oauth_token=oauth_token,
     )
 
 
-def uploaded_path(trace_file: Any) -> Path:
-    if isinstance(trace_file, (str, Path)):
-        return Path(trace_file)
-    name = getattr(trace_file, "name", None)
-    if name:
-        return Path(name)
-    path = getattr(trace_file, "path", None)
-    if path:
-        return Path(path)
-    raise gr.Error("Could not resolve the uploaded file path.")
-
-
-def write_temp_artifact(prefix: str, suffix: str, content: str) -> str:
-    with tempfile.NamedTemporaryFile(
-        "w",
-        encoding="utf-8",
-        prefix=prefix,
-        suffix=suffix,
-        delete=False,
-    ) as handle:
-        handle.write(content)
-        return handle.name
-
-
-def load_sample_trace() -> tuple[str, bool, bool, bool, str, str]:
-    return SAMPLE_TRACE_PATH, True, True, True, "field_notes", DEFAULT_ANALYSIS_ENGINE
-
-
-with gr.Blocks(
-    title="Trace Field Notes",
-    css=CUSTOM_CSS,
-    theme=gr.themes.Base(
-        primary_hue="green",
-        neutral_hue="stone",
-        font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
-        font_mono=[gr.themes.GoogleFont("IBM Plex Mono"), "ui-monospace", "monospace"],
-    ),
-) as demo:
-    gr.Markdown(HERO_MD, elem_classes=["hero"])
-    gr.Markdown(PRIVACY_WARNING, elem_classes=["privacy-callout"])
-
-    with gr.Row(equal_height=False):
-        with gr.Column(scale=3, elem_classes=["trace-panel"]):
-            gr.Markdown("### Trace Input")
-            trace_input = gr.File(
-                label="Agent session log",
-                file_types=[".jsonl", ".json", ".txt", ".log"],
-                type="filepath",
-            )
-            with gr.Row():
-                include_user_context = gr.Checkbox(
-                    value=True,
-                    label="Include user context",
-                )
-                redact_secrets = gr.Checkbox(
-                    value=True,
-                    label="Redact likely secrets",
-                )
-            ignore_tool_calls = gr.Checkbox(
-                value=True,
-                label="Ignore tool contents",
-                interactive=False,
-            )
-            report_style = gr.Radio(
-                choices=[("Field notes", "field_notes")],
-                value="field_notes",
-                label="Report style",
-                interactive=False,
-                visible=False,
-            )
-            analysis_engine = gr.Radio(
-                choices=[
-                    (str(choice["label"]), key)
-                    for key, choice in MODEL_CHOICES.items()
-                ],
-                value=DEFAULT_ANALYSIS_ENGINE,
-                label="Analysis engine",
+@server.api(name="analyze_trace")
+def analyze_trace(
+    trace_file: FileData,
+    include_user_context: bool = True,
+    redact_secrets: bool = True,
+    analysis_engine: str = "qwen",
+) -> dict:
+    """Analyze an uploaded trace and return the frontend view model."""
+
+    path = trace_file.path
+    try:
+        if analysis_engine == "deterministic":
+            result, narrative = analyze_trace_file(
+                path,
+                include_user_context=include_user_context,
+                redact_secrets=redact_secrets,
+                ignore_tool_calls=True,
+                analysis_engine="deterministic",
             )
-            with gr.Row():
-                gr.LoginButton(
-                    value="Sign in for model assist",
-                    logout_value="Signed in as {}",
-                    size="sm",
-                )
-            gr.Markdown(
-                "Model-assisted modes use your signed-in Hugging Face OAuth token with the `inference-api` scope. "
-                "The deterministic engine does not require sign-in."
+        else:
+            result, narrative = _analyze_on_gpu(
+                path, include_user_context, redact_secrets, analysis_engine
             )
-            with gr.Row(elem_classes=["action-row"]):
-                analyze_button = gr.Button("Analyze My Trace", variant="primary")
-                sample_button = gr.Button("Use Sample Trace", variant="secondary")
-        with gr.Column(scale=2, elem_classes=["guide-panel"]):
-            gr.Markdown(SESSION_PATHS_MD)
-            with gr.Accordion("Agent-callable prompt", open=False):
-                gr.Textbox(
-                    value=AGENT_PROMPT,
-                    label="Prompt for Codex or Claude Code",
-                    lines=9,
-                    interactive=False,
-                    show_copy_button=True,
-                )
-
-    sample_button.click(
-        load_sample_trace,
-        inputs=None,
-        outputs=[
-            trace_input,
-            include_user_context,
-            redact_secrets,
-            ignore_tool_calls,
-            report_style,
-            analysis_engine,
-        ],
-    )
+    except TraceParseError as exc:
+        raise ValueError(str(exc)) from exc
 
-    with gr.Tabs(elem_classes=["result-tabs"]):
-        with gr.Tab("Field Report"):
-            report_output = gr.Markdown(label="Field Report")
-        with gr.Tab("Episodes JSON"):
-            episode_json = gr.JSON(label="Structured Episode JSON")
-        with gr.Tab("Downloads"):
-            with gr.Row(elem_classes=["download-row"]):
-                redacted_download = gr.File(label="Redacted Narrative")
-                report_download = gr.File(label="Markdown Report")
-                json_download = gr.File(label="Structured JSON")
-
-    analyze_button.click(
-        analyze_trace,
-        inputs=[
-            trace_input,
-            include_user_context,
-            redact_secrets,
-            ignore_tool_calls,
-            report_style,
-            analysis_engine,
-        ],
-        outputs=[
-            report_output,
-            episode_json,
-            redacted_download,
-            report_download,
-            json_download,
-        ],
-        api_name="analyze_trace",
-    )
+    if trace_file.orig_name:
+        agent = READABLE_AGENT.get(result.agent_type_guess, "Agent")
+        result.trace_title = f"{agent} · {trace_file.orig_name}"
+
+    return build_view_model(result, narrative)
 
 
 if __name__ == "__main__":
-    demo.launch()
+    server.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.getenv("PORT", os.getenv("GRADIO_SERVER_PORT", "7860"))),
+        show_error=True,
+    )

frontend/index.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Trace Field Notes</title>
+  <meta name="description" content="Turn a coding-agent session log into a qualitative field report: where it got stuck, detoured, recovered, and how honestly it claimed success." />
+  <link rel="stylesheet" href="/static/field_report.css" />
+
+  <!-- React + Babel (in-browser JSX, matching the prototype) -->
+  <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+  <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+
+  <!-- Gradio JS client → talks to the Python @app.api endpoints -->
+  <script type="module">
+    import { Client, handle_file } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+    window.__gradio = { Client, handle_file, clientPromise: Client.connect(window.location.origin) };
+  </script>
+</head>
+<body>
+  <div id="root" class="app-root" data-theme="dark"></div>
+
+  <!-- codebook labels + tone metadata + offline samples (window.TFN) -->
+  <script src="/static/data.js"></script>
+  <!-- shared atoms + trail map + report sections (verbatim from the design) -->
+  <script type="text/babel" data-presets="react" src="/static/components.jsx"></script>
+  <!-- shell + landing, wired to the backend -->
+  <script type="text/babel" data-presets="react" src="/static/app.jsx"></script>
+</body>
+</html>

frontend/static/app.jsx

@@ -0,0 +1,358 @@
+/* ============================================================
+   app.jsx — shell + landing, wired to the gradio.Server backend.
+   Adapted from the designer's prototype: the demo's fake upload
+   is replaced with a real file picker that calls /analyze_trace
+   through @gradio/client; the tweaks panel is dropped and the
+   theme is pinned to the dusk-survey dark mode.
+   ============================================================ */
+
+function BrandMark({ size = 34 }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 40 40" fill="none" aria-hidden="true" className="brandmark">
+      <circle cx="20" cy="20" r="17" stroke="var(--edge-strong)" strokeWidth="1.2" />
+      <path d="M8 24 C 14 16, 18 28, 24 18 S 32 12, 33 14" stroke="var(--ink-3)" strokeWidth="1" fill="none" strokeDasharray="1.5 3" />
+      <path d="M6 20 C 13 10, 20 30, 27 16 S 34 14, 35 20" stroke="var(--accent)" strokeWidth="2" fill="none" strokeLinecap="round" />
+      <circle cx="13" cy="20" r="2.4" fill="var(--tone-stable)" />
+      <circle cx="22" cy="22.5" r="2.4" fill="var(--tone-partial)" />
+      <circle cx="30" cy="17" r="2.4" fill="var(--tone-risk)" />
+      <path d="M30 17 L30 9 L36 11 L30 13" fill="var(--accent)" />
+    </svg>
+  );
+}
+
+function TopBar() {
+  return (
+    <header className="topbar">
+      <div className="topbar__brand">
+        <BrandMark />
+        <div className="topbar__word">
+          <span className="topbar__name">Trace Field Notes</span>
+          <span className="topbar__tag mono">narrative analysis for coding-agent traces</span>
+        </div>
+      </div>
+      <div className="topbar__right mono">
+        <span className="topbar__pill">narrative-only</span>
+        <span className="topbar__pill">privacy-first</span>
+      </div>
+    </header>
+  );
+}
+
+const ENGINES = [
+  ["qwen", "Quick analysis", "Qwen3.5 9B"],
+  ["nemotron", "Deeper analysis", "Nemotron 3 Nano 30B-A3B"],
+  ["deterministic", "Rule-based", "no model, always on"],
+];
+
+function Toggle({ on, set, label, sub, locked }) {
+  return (
+    <button className={"toggle" + (on ? " toggle--on" : "") + (locked ? " toggle--locked" : "")}
+      onClick={() => !locked && set(!on)} aria-pressed={on}>
+      <span className="toggle__sw"><span className="toggle__knob" /></span>
+      <span className="toggle__txt">
+        <span className="toggle__label">{label}{locked ? " 🔒" : ""}</span>
+        <span className="toggle__sub muted">{sub}</span>
+      </span>
+    </button>
+  );
+}
+
+function LandingView({ onAnalyze, onSample, error }) {
+  const [staged, setStaged] = React.useState(null); // { name, file }
+  const [redact, setRedact] = React.useState(true);
+  const [userCtx, setUserCtx] = React.useState(true);
+  const [engine, setEngine] = React.useState("qwen");
+  const [dragOver, setDragOver] = React.useState(false);
+  const [copied, setCopied] = React.useState(false);
+  const fileRef = React.useRef(null);
+
+  const chosen = ENGINES.find((e) => e[0] === engine) || ENGINES[2];
+  const engineLabel = chosen[1] + ": " + chosen[2];
+
+  function onFiles(list) {
+    const f = list && list[0];
+    if (f) setStaged({ name: f.name, file: f });
+  }
+  function pick() { if (fileRef.current) fileRef.current.click(); }
+  function run() {
+    if (!staged) return;
+    onAnalyze({ file: staged.file, include_user_context: userCtx, redact_secrets: redact, analysis_engine: engine, engineLabel });
+  }
+
+  const AGENT_PROMPT = `Use this Space as a tool.
+1. Read its /agents.md endpoint.
+2. Find my latest local agent session log
+   (Codex ~/.codex/sessions, Claude ~/.claude/projects).
+3. Review and redact secrets before upload.
+4. Upload the JSONL and request a narrative difficulty analysis.
+5. Return the report. Do not publish the raw trace.`;
+
+  return (
+    <div className="landing">
+      <TopBar />
+
+      <section className="hero">
+        <Kicker>Field report · qualitative, not a leaderboard</Kicker>
+        <h1 className="hero__title">See how your coding agent<br /> got stuck, detoured, recovered<span className="hero__amp"> &amp; </span>claimed success.</h1>
+        <p className="hero__sub">
+          Upload a Codex, Claude Code, or Pi Agent session log. Trace Field Notes reads only the agent's
+          <em> narrated</em> messages — what it planned, where it snagged, how it rerouted, and how honestly it called it done —
+          and charts the session as a trail you can walk.
+        </p>
+      </section>
+
+      <div className="privacy">
+        <span className="privacy__mark">!</span>
+        <p>
+          Agent traces can carry prompts, command output, local paths, screenshots, secrets, and private code.
+          <b> Review and redact before uploading or sharing.</b> This app analyzes only visible narrative messages and ignores raw tool telemetry by default.
+        </p>
+      </div>
+
+      {error ? (
+        <div className="privacy" style={{ borderColor: "var(--tone-risk)", borderLeftColor: "var(--tone-risk)" }}>
+          <span className="privacy__mark" style={{ background: "var(--tone-risk)" }}>×</span>
+          <p><b>Analysis failed.</b> {error}</p>
+        </div>
+      ) : null}
+
+      <div className="landing__grid">
+        {/* LEFT: upload */}
+        <div className="panel card card--raised">
+          <SectionHead kicker="Step 01" title="Bring a trace" />
+          <input ref={fileRef} type="file" accept=".jsonl,.json,.txt,.log" style={{ display: "none" }}
+            onChange={(e) => onFiles(e.target.files)} />
+          <div
+            className={"drop" + (dragOver ? " drop--over" : "") + (staged ? " drop--staged" : "")}
+            onDragOver={(e) => { e.preventDefault(); setDragOver(true); }}
+            onDragLeave={() => setDragOver(false)}
+            onDrop={(e) => { e.preventDefault(); setDragOver(false); onFiles(e.dataTransfer.files); }}
+            onClick={pick}
+            role="button" tabIndex={0}
+            onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") pick(); }}
+          >
+            {staged ? (
+              <div className="drop__staged">
+                <span className="drop__file mono">{staged.name}</span>
+                <span className="label">staged · click Analyze</span>
+              </div>
+            ) : (
+              <div className="drop__empty">
+                <div className="drop__icon">⤓</div>
+                <span className="drop__title">Drop a <code>.jsonl</code> trace</span>
+                <span className="muted">or click to choose · .json .txt .log accepted</span>
+              </div>
+            )}
+          </div>
+
+          <div className="opts">
+            <Toggle on={redact} set={setRedact} label="Redact likely secrets" sub="emails, tokens, keys, paths" />
+            <Toggle on={userCtx} set={setUserCtx} label="Include user context" sub="user prompts as framing" />
+            <Toggle on={true} set={() => {}} locked label="Ignore tool contents" sub="locked for this release" />
+          </div>
+
+          <div className="engine">
+            <Label>Analysis engine</Label>
+            <div className="engine__opts">
+              {ENGINES.map(([key, name, detail]) => (
+                <button key={key}
+                  className={"engine__opt" + (engine === key ? " engine__opt--on" : "")}
+                  onClick={() => setEngine(key)}>
+                  <span className="engine__name">{name}</span>
+                  <span className="engine__detail mono">{detail}</span>
+                </button>
+              ))}
+            </div>
+            <p className="engine__note muted">Quick and Deeper run a small model on the Space GPU. Rule-based needs no model and never fails.</p>
+          </div>
+
+          <div className="panel__actions">
+            <button className="btn btn--primary" disabled={!staged} onClick={run}>
+              Analyze my trace
+            </button>
+            <button className="btn" onClick={() => onSample("short")}>Sample · short</button>
+            <button className="btn" onClick={() => onSample("long")}>Sample · long</button>
+          </div>
+        </div>
+
+        {/* RIGHT: guide */}
+        <div className="guide">
+          <div className="panel card">
+            <SectionHead kicker="Step 00" title="Find your session log" />
+            <table className="paths">
+              <tbody>
+                {[
+                  ["Codex", "~/.codex/sessions"],
+                  ["Claude Code", "~/.claude/projects"],
+                  ["Pi Agent", "~/.pi/agent/sessions"],
+                ].map(([a, p]) => (
+                  <tr key={a}>
+                    <td className="paths__agent">{a}</td>
+                    <td className="paths__path mono">{p}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+
+          <div className="panel card">
+            <div className="agentcall__hd">
+              <SectionHead kicker="Hands-free" title="Let the agent call it" />
+              <button className="btn btn--sm btn--ghost" onClick={() => {
+                try { navigator.clipboard && navigator.clipboard.writeText(AGENT_PROMPT); } catch (e) {}
+                setCopied(true); setTimeout(() => setCopied(false), 1400);
+              }}>
+                {copied ? "copied ✓" : "copy prompt"}
+              </button>
+            </div>
+            <p className="agentcall__blurb">Using Codex or Claude Code? Point it at this Space's <span className="mono">agents.md</span>. It finds your latest log, redacts it, uploads, and returns the report.</p>
+            <pre className="agentcall__pre mono">{AGENT_PROMPT}</pre>
+          </div>
+
+          <div className="getrow">
+            {[
+              ["Elevation trail", "every snag as a waypoint"],
+              ["Detour read", "exploration vs wandering"],
+              ["Closeout audit", "honest, or overclaimed?"],
+            ].map(([t, s]) => (
+              <div className="getrow__item" key={t}>
+                <span className="getrow__t">{t}</span>
+                <span className="getrow__s muted">{s}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const PIPELINE = [
+  "Uploading the trace",
+  "Extracting narrative messages",
+  "Redacting likely secrets",
+  "Charting difficulty episodes",
+  "Classifying with the codebook",
+  "Synthesizing field notes",
+];
+
+function Analyzing({ label }) {
+  const [step, setStep] = React.useState(0);
+  React.useEffect(() => {
+    const id = setInterval(() => setStep((s) => (s + 1) % (PIPELINE.length + 1)), 700);
+    return () => clearInterval(id);
+  }, []);
+  return (
+    <div className="analyzing">
+      <div className="analyzing__card card card--raised">
+        <svg viewBox="0 0 320 120" className="analyzing__svg" aria-hidden="true">
+          <line x1="20" y1="100" x2="300" y2="100" stroke="var(--rule)" strokeDasharray="2 6" />
+          <path className="analyzing__trail"
+            d="M20 96 C 70 60, 100 104, 150 70 S 230 30, 300 44"
+            fill="none" stroke="var(--accent)" strokeWidth="2.6" strokeLinecap="round" />
+          <circle className="analyzing__dot" r="4.5" fill="var(--accent)" />
+        </svg>
+        <Kicker>Surveying the trace · {label}</Kicker>
+        <ul className="analyzing__steps">
+          {PIPELINE.map((s, i) => (
+            <li key={s} className={i < step ? "done" : i === step ? "active" : ""}>
+              <span className="analyzing__tick mono">{i < step ? "✓" : i === step ? "…" : "·"}</span>{s}
+            </li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  );
+}
+
+function EmptyReport({ data, onReset }) {
+  return (
+    <div className="report">
+      <ReportHeader data={data} />
+      <section className="sec">
+        <div className="card" style={{ padding: "28px 30px" }}>
+          <SectionHead kicker="No episode surfaced" title="No explicit difficulty episode was strong enough to classify" />
+          <p className="sec-head__sub" style={{ maxWidth: "70ch" }}>
+            The trace yielded {data.narrative_message_count} visible narrative messages, but none carried clear
+            self-reported blockage, detour, or recovery language. That does not prove the session was trouble-free —
+            only that the narrative did not say so. Try the redacted-narrative export to read it yourself.
+          </p>
+          <div style={{ marginTop: 18 }}>
+            <button className="btn btn--sm btn--ghost" onClick={onReset}>← Analyze another trace</button>
+          </div>
+        </div>
+      </section>
+    </div>
+  );
+}
+
+function App() {
+  const [stage, setStage] = React.useState("landing"); // landing | analyzing | report
+  const [data, setData] = React.useState(null);
+  const [engineLabel, setEngineLabel] = React.useState("");
+  const [error, setError] = React.useState("");
+
+  async function analyze({ file, include_user_context, redact_secrets, analysis_engine, engineLabel }) {
+    setError("");
+    setEngineLabel(engineLabel || analysis_engine);
+    setStage("analyzing");
+    window.scrollTo({ top: 0 });
+    try {
+      const g = window.__gradio;
+      if (!g) throw new Error("Client is still loading — reload the page and try again.");
+      const client = await g.clientPromise;
+      const res = await client.predict("/analyze_trace", {
+        trace_file: g.handle_file(file),
+        include_user_context: !!include_user_context,
+        redact_secrets: !!redact_secrets,
+        analysis_engine,
+      });
+      const out = Array.isArray(res.data) ? res.data[0] : res.data;
+      if (!out || typeof out !== "object") throw new Error("The analyzer returned an empty response.");
+      setData(out);
+      setStage("report");
+    } catch (e) {
+      setError(String((e && e.message) || e));
+      setStage("landing");
+    }
+    window.scrollTo({ top: 0 });
+  }
+
+  function loadSample(key) {
+    const base = key === "short" ? window.TFN.SHORT : window.TFN.LONG;
+    setError("");
+    setEngineLabel(base.engine);
+    setData(base);
+    setStage("report");
+    window.scrollTo({ top: 0 });
+  }
+
+  function reset() { setStage("landing"); setData(null); window.scrollTo({ top: 0 }); }
+
+  const reportData = data ? Object.assign({}, data, { engine: engineLabel || data.engine }) : null;
+  const hasEpisodes = reportData && reportData.episodes && reportData.episodes.length;
+
+  return (
+    <div className="app-root" data-theme="dark" data-density="regular" data-voice="journal">
+      <div className="backdrop"><div className="grain" /><TopoBackground /></div>
+      <div className="page">
+        {stage === "landing" && <LandingView onAnalyze={analyze} onSample={loadSample} error={error} />}
+        {stage === "analyzing" && <Analyzing label={engineLabel} />}
+        {stage === "report" && (
+          <div className="report-wrap">
+            <button className="report-back btn btn--sm btn--ghost" onClick={reset}>← New trace</button>
+            {hasEpisodes
+              ? <ReportView data={reportData} variant="trail" onReset={reset} />
+              : <EmptyReport data={reportData} onReset={reset} />}
+            <footer className="foot">
+              <span className="mono">Trace Field Notes</span>
+              <span className="muted">Qualitative narrative analysis · we report what the agent said, not whether its code is correct.</span>
+            </footer>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+ReactDOM.createRoot(document.getElementById("root")).render(<App />);

frontend/static/components.jsx

@@ -0,0 +1,615 @@
+/* ============================================================
+   atoms.jsx — shared primitives + topo background
+   ============================================================ */
+
+// ---- deterministic topo contour generator ----
+function _noise(a, seed) {
+  return (
+    Math.sin(a * 3 + seed) * 0.45 +
+    Math.sin(a * 5 + seed * 1.7) * 0.28 +
+    Math.sin(a * 2 + seed * 0.6) * 0.5 +
+    Math.sin(a * 7 + seed * 2.3) * 0.16
+  );
+}
+function _blob(cx, cy, r, seed, amp) {
+  const N = 80;
+  let d = "";
+  for (let i = 0; i <= N; i++) {
+    const t = (i / N) * Math.PI * 2;
+    const rr = r * (1 + amp * _noise(t, seed));
+    const x = cx + rr * Math.cos(t);
+    const y = cy + rr * Math.sin(t) * 0.82;
+    d += (i === 0 ? "M" : "L") + x.toFixed(1) + " " + y.toFixed(1) + " ";
+  }
+  return d + "Z";
+}
+
+function TopoBackground() {
+  const peaks = [
+    { cx: 250, cy: 230, seed: 1.2, count: 11, base: 26, step: 34, peakAt: 3 },
+    { cx: 1160, cy: 640, seed: 4.7, count: 13, base: 24, step: 32, peakAt: 4 },
+    { cx: 760, cy: 120, seed: 8.1, count: 7, base: 30, step: 40, peakAt: 1 },
+  ];
+  return (
+    <svg viewBox="0 0 1440 900" preserveAspectRatio="xMidYMid slice" aria-hidden="true">
+      {peaks.map((p, pi) =>
+        Array.from({ length: p.count }).map((_, i) => {
+          const r = p.base + i * p.step;
+          const amp = 0.05 + i * 0.012;
+          const strong = i === p.peakAt;
+          return (
+            <path
+              key={pi + "-" + i}
+              d={_blob(p.cx, p.cy, r, p.seed + i * 0.13, amp)}
+              fill="none"
+              stroke={strong ? "var(--topo-stroke-strong)" : "var(--topo-stroke)"}
+              strokeWidth={strong ? 1.4 : 0.9}
+            />
+          );
+        })
+      )}
+    </svg>
+  );
+}
+
+// ---- tone helpers ----
+function toneOf(recovery) {
+  return (window.TFN.TONE_OF[recovery]) || "unknown";
+}
+function toneColor(tone) {
+  return "var(--tone-" + tone + ")";
+}
+
+// ---- small atoms ----
+function Kicker({ children }) {
+  return <div className="kicker">{children}</div>;
+}
+
+function Label({ children, accent, style }) {
+  return <div className={"label" + (accent ? " label--accent" : "")} style={style}>{children}</div>;
+}
+
+function ToneDot({ tone, size = 10 }) {
+  return (
+    <span
+      className="tone-dot"
+      style={{ background: toneColor(tone), color: toneColor(tone), width: size, height: size }}
+    />
+  );
+}
+
+// codebook chip: pass field + code
+function CodeChip({ field, code, withDotTone }) {
+  const label = (window.TFN.CODEBOOK[field] && window.TFN.CODEBOOK[field][code]) || code;
+  return (
+    <span className="chip" title={field.replace(/_/g, " ")}>
+      {withDotTone ? <span className="dot" style={{ background: toneColor(withDotTone) }} /> : null}
+      {label}
+    </span>
+  );
+}
+
+function Stamp({ tone, children }) {
+  return (
+    <span className="stamp" style={{ color: toneColor(tone) }}>
+      {children}
+    </span>
+  );
+}
+
+// section header used across the report
+function SectionHead({ index, kicker, title, sub }) {
+  return (
+    <div className="sec-head">
+      <div className="sec-head__top">
+        {index ? <span className="sec-head__no mono">{index}</span> : null}
+        <Kicker>{kicker}</Kicker>
+      </div>
+      <h2 className="sec-head__title">{title}</h2>
+      {sub ? <p className="sec-head__sub">{sub}</p> : null}
+    </div>
+  );
+}
+
+Object.assign(window, {
+  TopoBackground, toneOf, toneColor,
+  Kicker, Label, ToneDot, CodeChip, Stamp, SectionHead,
+});
+
+/* ============================================================
+   trailmap.jsx — elevation-profile trail map + episode detail
+   x = progress through the session, y = risk / exposure.
+   The agent's journey climbs toward hazard.
+   ============================================================ */
+
+const ELEV = { stable: 0.12, detour: 0.44, iterative: 0.52, partial: 0.64, risk: 0.93, unknown: 0.30 };
+
+const VBW = 1000, VBH = 360;
+const PAD = { l: 116, r: 96, t: 48, b: 60 };
+
+function _layout(episodes) {
+  const n = episodes.length;
+  const innerW = VBW - PAD.l - PAD.r;
+  const innerH = VBH - PAD.t - PAD.b;
+  const baseY = VBH - PAD.b;
+  return episodes.map((ep, i) => {
+    const tone = toneOf(ep.recovery_pattern);
+    const x = PAD.l + (n === 1 ? innerW / 2 : (i / (n - 1)) * innerW);
+    const jitter = ((i % 2) * 2 - 1) * 0.015;
+    const elev = Math.min(0.97, Math.max(0.06, ELEV[tone] + jitter));
+    const y = baseY - elev * innerH;
+    return { ep, tone, x, y, fx: (x / VBW) * 100, fy: (y / VBH) * 100, elev };
+  });
+}
+
+function _smoothPath(pts) {
+  if (pts.length === 1) return `M ${pts[0].x} ${pts[0].y}`;
+  let d = `M ${pts[0].x} ${pts[0].y}`;
+  for (let i = 0; i < pts.length - 1; i++) {
+    const p0 = pts[i - 1] || pts[i];
+    const p1 = pts[i];
+    const p2 = pts[i + 1];
+    const p3 = pts[i + 2] || p2;
+    const c1x = p1.x + (p2.x - p0.x) / 6;
+    const c1y = p1.y + (p2.y - p0.y) / 6;
+    const c2x = p2.x - (p3.x - p1.x) / 6;
+    const c2y = p2.y - (p3.y - p1.y) / 6;
+    d += ` C ${c1x.toFixed(1)} ${c1y.toFixed(1)}, ${c2x.toFixed(1)} ${c2y.toFixed(1)}, ${p2.x.toFixed(1)} ${p2.y.toFixed(1)}`;
+  }
+  return d;
+}
+
+function TrailMap({ episodes, selectedId, onSelect }) {
+  const pts = _layout(episodes);
+  const baseY = VBH - PAD.b;
+  const line = _smoothPath(pts);
+  const area = `${line} L ${pts[pts.length - 1].x} ${baseY} L ${pts[0].x} ${baseY} Z`;
+  const gridY = [0.25, 0.5, 0.75, 1].map((f) => baseY - f * (VBH - PAD.t - PAD.b));
+
+  return (
+    <div className="trail">
+      <div className="trail__chrome">
+        <div className="trail__axis-y">
+          <span>Hazard</span><span>Exposure</span><span>On-route</span>
+        </div>
+        <div className="trail__plot">
+          <svg viewBox={`0 0 ${VBW} ${VBH}`} preserveAspectRatio="xMidYMid meet" className="trail__svg">
+            <defs>
+              <linearGradient id="hypso" x1="0" y1={PAD.t} x2="0" y2={baseY} gradientUnits="userSpaceOnUse">
+                <stop offset="0%" stopColor="var(--tone-risk)" stopOpacity="0.20" />
+                <stop offset="45%" stopColor="var(--tone-partial)" stopOpacity="0.12" />
+                <stop offset="100%" stopColor="var(--tone-stable)" stopOpacity="0.08" />
+              </linearGradient>
+            </defs>
+            {/* elevation grid */}
+            {gridY.map((y, i) => (
+              <line key={i} x1={PAD.l} y1={y} x2={VBW - PAD.r} y2={y}
+                stroke="var(--rule)" strokeWidth="1" strokeDasharray="2 6" />
+            ))}
+            <line x1={PAD.l} y1={baseY} x2={VBW - PAD.r} y2={baseY} stroke="var(--rule-strong)" strokeWidth="1.2" />
+            {/* hypsometric fill + ridge line */}
+            <path d={area} fill="url(#hypso)" />
+            <path d={line} fill="none" stroke="var(--ink-3)" strokeWidth="2.4"
+              strokeLinecap="round" strokeLinejoin="round" />
+            {/* drop stems + waypoint nodes (selectable) */}
+            {pts.map((p) => {
+              const sel = p.ep.episode_id === selectedId;
+              return (
+                <g key={p.ep.episode_id} className="trail__node" onClick={() => onSelect(p.ep.episode_id)}>
+                  <line x1={p.x} y1={p.y} x2={p.x} y2={baseY} stroke={toneColor(p.tone)} strokeWidth="1" strokeOpacity="0.4" />
+                  <circle cx={p.x} cy={p.y} r={sel ? 13 : 9} fill="var(--paper-3)"
+                    stroke={toneColor(p.tone)} strokeWidth={sel ? 4 : 3} />
+                  <circle cx={p.x} cy={p.y} r="3" fill={toneColor(p.tone)} />
+                </g>
+              );
+            })}
+          </svg>
+          {/* HTML waypoint flags positioned over the SVG */}
+          {pts.map((p, i) => {
+            const sel = p.ep.episode_id === selectedId;
+            const above = p.fy > 46;
+            const edge = i === 0 ? " wp--first" : i === pts.length - 1 ? " wp--last" : "";
+            return (
+              <button
+                key={p.ep.episode_id}
+                className={"wp" + (sel ? " wp--sel" : "") + (above ? " wp--above" : " wp--below") + edge}
+                style={{ left: p.fx + "%", top: p.fy + "%", "--tone": toneColor(p.tone) }}
+                onClick={() => onSelect(p.ep.episode_id)}
+              >
+                <span className="wp__id mono">{p.ep.episode_id}</span>
+                <span className="wp__title">{p.ep.title}</span>
+                <span className="wp__dur mono">{p.ep.message_span.duration_label}</span>
+              </button>
+            );
+          })}
+        </div>
+      </div>
+      <div className="trail__xaxis">
+        <span className="mono">start · {episodes[0].message_span.start_time}</span>
+        <span className="label">progress through session →</span>
+        <span className="mono">end · {episodes[episodes.length - 1].message_span.end_time}</span>
+      </div>
+    </div>
+  );
+}
+
+// ---- Episode detail (used by both layouts) ----
+function EpisodeDetail({ ep }) {
+  if (!ep) return null;
+  const tone = toneOf(ep.recovery_pattern);
+  const tm = window.TFN.TONE_META[tone];
+  return (
+    <div className="epd card card--raised" style={{ "--tone": toneColor(tone) }}>
+      <div className="epd__band" />
+      <div className="epd__head">
+        <div className="epd__id">
+          <span className="mono epd__no">{ep.episode_id}</span>
+          <ToneDot tone={tone} size={12} />
+        </div>
+        <div>
+          <h3 className="epd__title">{ep.title}</h3>
+          <div className="epd__meta mono">
+            {tm.label} · {ep.message_span.duration_label} · {ep.message_span.start_time}–{ep.message_span.end_time}
+          </div>
+        </div>
+      </div>
+
+      <div className="epd__flow">
+        {[
+          ["Intention", ep.initial_intention],
+          ["Difficulty", ep.reported_difficulty],
+          ["Reroute", ep.strategy_after],
+        ].map(([k, v]) => (
+          <div className="epd__step" key={k}>
+            <span className="label">{k}</span>
+            <p>{v}</p>
+          </div>
+        ))}
+      </div>
+
+      <hr className="rule--dashed" />
+
+      <div className="epd__codes">
+        <CodeChip field="difficulty_type" code={ep.difficulty_type} />
+        <CodeChip field="appraisal" code={ep.appraisal} />
+        <CodeChip field="detour_type" code={ep.detour_type} />
+        <CodeChip field="resolution_mode" code={ep.resolution_mode} />
+        <CodeChip field="recovery_pattern" code={ep.recovery_pattern} withDotTone={tone} />
+        <CodeChip field="outcome_claim" code={ep.outcome_claim} />
+      </div>
+
+      {ep.evidence_quotes && ep.evidence_quotes.length ? (
+        <div className="epd__quotes">
+          <span className="label">Evidence — agent's own words</span>
+          {ep.evidence_quotes.map((q, i) => (
+            <blockquote key={i} className="quote">{q}</blockquote>
+          ))}
+        </div>
+      ) : null}
+
+      <div className="epd__memo">
+        <span className="label label--accent">Analyst memo</span>
+        <p>{ep.analyst_memo}</p>
+      </div>
+    </div>
+  );
+}
+
+// ---- Ledger (vertical) timeline variant ----
+function LedgerTimeline({ episodes, selectedId, onSelect }) {
+  return (
+    <div className="ledger">
+      {episodes.map((ep) => {
+        const tone = toneOf(ep.recovery_pattern);
+        const sel = ep.episode_id === selectedId;
+        return (
+          <button key={ep.episode_id}
+            className={"ledger__row" + (sel ? " ledger__row--sel" : "")}
+            style={{ "--tone": toneColor(tone) }}
+            onClick={() => onSelect(ep.episode_id)}>
+            <span className="ledger__rail"><ToneDot tone={tone} size={13} /></span>
+            <span className="ledger__id mono">{ep.episode_id}</span>
+            <span className="ledger__main">
+              <span className="ledger__title">{ep.title}</span>
+              <span className="ledger__sub">{window.TFN.CODEBOOK.difficulty_type[ep.difficulty_type]} → {window.TFN.CODEBOOK.recovery_pattern[ep.recovery_pattern]}</span>
+            </span>
+            <span className="ledger__dur mono">{ep.message_span.duration_label}</span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+Object.assign(window, { TrailMap, EpisodeDetail, LedgerTimeline });
+
+/* ============================================================
+   report.jsx — the field report: verdict, trail, analysis sections
+   ============================================================ */
+
+const HONESTY = {
+  resolved_with_confidence: { tone: "stable", note: "Clear, committed claim." },
+  resolved_with_caveat:     { tone: "stable", note: "States its own limits." },
+  partially_resolved:       { tone: "partial", note: "Honest partial." },
+  not_resolved:             { tone: "partial", note: "Admits it's unresolved." },
+  needs_verification:       { tone: "partial", note: "Flags a verification gap." },
+  uncertain_but_proceeding: { tone: "partial", note: "Proceeds under stated uncertainty." },
+  premature_success_claim:  { tone: "risk", note: "Claim outruns the evidence." },
+  unknown:                  { tone: "unknown", note: "—" },
+};
+
+
+// download helper for the export buttons (no-op if the backend didn't supply text)
+function dl(text, filename, mime) {
+  if (!text) return;
+  const blob = new Blob([text], { type: mime || "text/plain" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url; a.download = filename; document.body.appendChild(a); a.click();
+  a.remove(); setTimeout(() => URL.revokeObjectURL(url), 1500);
+}
+
+function ReportHeader({ data }) {
+  return (
+    <div className="rhead">
+      <div className="rhead__tag mono">FIELD LOG № {data.agent_type_guess === "codex" ? "C-01" : "CC-04"}</div>
+      <div className="rhead__main">
+        <Label accent>Trace</Label>
+        <h1 className="rhead__file mono">{data.trace_title}</h1>
+      </div>
+      <dl className="rhead__grid">
+        {[
+          ["Agent", data.agent_type_guess.replace("_", " ")],
+          ["Captured", data.captured],
+          ["Scope", "narrative msgs only"],
+          ["Messages", String(data.narrative_message_count)],
+          ["Engine", data.engine],
+          ["Redactions", String(data.redaction_count)],
+        ].map(([k, v]) => (
+          <div key={k} className="rhead__cell">
+            <dt className="label">{k}</dt>
+            <dd className="mono">{v}</dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}
+
+function Verdict({ data }) {
+  const v = data.verdict;
+  const tm = window.TFN.TONE_META[v.tone];
+  const honestyWord = v.honesty === "overclaimed" ? "Overclaimed close-out"
+    : v.honesty === "candid" ? "Candid close-out" : "Mixed close-out";
+  return (
+    <div className="verdict card card--raised" style={{ "--tone": toneColor(v.tone) }}>
+      <div className="verdict__band" />
+      <div className="verdict__left">
+        <Kicker>Trail verdict</Kicker>
+        <h2 className="verdict__headline">{v.headline}</h2>
+        <p className="verdict__detail">{v.detail}</p>
+        <div className="verdict__stamps">
+          <Stamp tone={v.tone}>{honestyWord}</Stamp>
+        </div>
+      </div>
+      <div className="verdict__right">
+        <div className="verdict__gauge" style={{ "--tone": toneColor(v.tone) }}>
+          <span className="verdict__gauge-label label">Recovery read</span>
+          <span className="verdict__gauge-val">{tm.rating}</span>
+          <span className="verdict__gauge-blurb">{tm.blurb}</span>
+        </div>
+        <div className="verdict__stats">
+          <div><span className="verdict__num mono">{data.episodes.length}</span><span className="label">episodes</span></div>
+          <div><span className="verdict__num mono">{data.duration_total}</span><span className="label">on trail</span></div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Legend() {
+  const order = ["stable", "detour", "iterative", "partial", "risk", "unknown"];
+  const M = window.TFN.TONE_META;
+  return (
+    <div className="legend">
+      <span className="label">Waypoint key</span>
+      <div className="legend__items">
+        {order.map((t) => (
+          <span className="legend__item" key={t}>
+            <ToneDot tone={t} size={11} />
+            <span className="legend__txt"><b>{M[t].label}</b> · {M[t].rating}</span>
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function TrailSection({ data, variant, selectedId, setSelectedId }) {
+  const ep = data.episodes.find((e) => e.episode_id === selectedId) || data.episodes[0];
+  return (
+    <section className="sec">
+      <SectionHead index="01" kicker="Journey · elevation profile"
+        title="Where the route climbed into hazard"
+        sub="Each waypoint is a difficulty episode. The line rises with risk — open ground low, exposed claims high. Tap a waypoint to read it." />
+      <div className="card trail-card">
+        {variant === "ledger"
+          ? <LedgerTimeline episodes={data.episodes} selectedId={ep.episode_id} onSelect={setSelectedId} />
+          : <TrailMap episodes={data.episodes} selectedId={ep.episode_id} onSelect={setSelectedId} />}
+        <hr className="rule" />
+        <Legend />
+      </div>
+      <EpisodeDetail ep={ep} />
+    </section>
+  );
+}
+
+function DifficultyMap({ data }) {
+  const clusters = {};
+  data.episodes.forEach((e) => {
+    (clusters[e.difficulty_type] = clusters[e.difficulty_type] || []).push(e);
+  });
+  const CB = window.TFN.CODEBOOK.difficulty_type;
+  const entries = Object.entries(clusters).sort((a, b) => b[1].length - a[1].length);
+  return (
+    <section className="sec">
+      <SectionHead index="02" kicker="Terrain" title="What kind of ground it was"
+        sub="Difficulties grouped by type — the recurring terrain, not a leaderboard." />
+      <div className="dmap">
+        {entries.map(([type, eps]) => {
+          const quote = (eps.find((e) => e.evidence_quotes && e.evidence_quotes.length) || {}).evidence_quotes;
+          return (
+            <div className="dmap__cell card" key={type}>
+              <div className="dmap__hd">
+                <span className="dmap__type">{CB[type] || type}</span>
+                <span className="dmap__ids mono">{eps.map((e) => e.episode_id).join(" · ")}</span>
+              </div>
+              {quote ? <blockquote className="quote quote--sm">{quote[0]}</blockquote> : <p className="muted">No short evidence quote.</p>}
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  );
+}
+
+function DetourAnalysis({ data }) {
+  const groups = { yes: [], mixed: [], no: [] };
+  data.episodes.forEach((e) => { if (groups[e.productive_detour]) groups[e.productive_detour].push(e); });
+  const defs = [
+    ["yes", "Productive detours", "Off-route, but a better line emerged.", "detour"],
+    ["mixed", "Mixed", "A reroute with real upside and a loose end.", "partial"],
+    ["no", "Wandering / workaround", "Movement without a new line on the problem.", "risk"],
+  ];
+  return (
+    <section className="sec">
+      <SectionHead index="03" kicker="Route choices" title="Detours — exploration or wandering?"
+        sub="The question that actually matters: when it left the planned path, did it find a better one?" />
+      <div className="detour">
+        {defs.map(([key, title, blurb, tone]) => (
+          <div className="detour__col card" key={key} style={{ "--tone": toneColor(tone) }}>
+            <div className="detour__hd">
+              <ToneDot tone={tone} size={11} />
+              <span className="detour__title">{title}</span>
+              <span className="detour__count mono">{groups[key].length}</span>
+            </div>
+            <p className="detour__blurb">{blurb}</p>
+            <div className="detour__list">
+              {groups[key].length ? groups[key].map((e) => (
+                <div className="detour__ep" key={e.episode_id}>
+                  <span className="mono detour__epid">{e.episode_id}</span>
+                  <CodeChip field="detour_type" code={e.detour_type} />
+                </div>
+              )) : <span className="muted detour__none">None observed.</span>}
+            </div>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function RecoveryPattern({ data }) {
+  const p = data.overall_patterns;
+  const rows = [
+    ["Difficulty style", p.difficulty_style],
+    ["Detour style", p.detour_style],
+    ["Recovery style", p.recovery_style],
+    ["Standing caveat", p.risk_or_caveat],
+  ];
+  return (
+    <section className="sec">
+      <SectionHead index="04" kicker="Field naturalist's read" title="How this agent travels"
+        sub="A behavioral read across the whole session — its habits under difficulty." />
+      <div className="recov card card--raised">
+        {rows.map(([k, v], i) => (
+          <div className="recov__row" key={k}>
+            <span className="recov__no mono">{String(i + 1).padStart(2, "0")}</span>
+            <span className="label recov__k">{k}</span>
+            <p className="recov__v">{v}</p>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function OutcomeAudit({ data }) {
+  const CB = window.TFN.CODEBOOK.outcome_claim;
+  return (
+    <section className="sec">
+      <SectionHead index="05" kicker="Closeout audit" title="What it said when it called it done"
+        sub="Not whether the code is correct — whether the agent's claim matches its own evidence." />
+      <div className="audit card">
+        {data.episodes.map((e) => {
+          const h = HONESTY[e.outcome_claim] || HONESTY.unknown;
+          return (
+            <div className="audit__row" key={e.episode_id} style={{ "--tone": toneColor(h.tone) }}>
+              <div className="audit__rail"><span className="mono">{e.episode_id}</span><ToneDot tone={h.tone} size={11} /></div>
+              <div className="audit__body">
+                <div className="audit__claim">
+                  <span className="audit__verb">{CB[e.outcome_claim] || e.outcome_claim}</span>
+                  <span className="audit__note">{h.note}</span>
+                </div>
+                {e.evidence_quotes && e.evidence_quotes.length ? (
+                  <blockquote className="quote quote--sm">{e.evidence_quotes[e.evidence_quotes.length - 1]}</blockquote>
+                ) : null}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  );
+}
+
+function PrivacyExports({ data, onReset }) {
+  return (
+    <section className="sec">
+      <div className="px">
+        <div className="px__notes card">
+          <SectionHead kicker="Privacy ledger" title={`${data.redaction_count} item${data.redaction_count === 1 ? "" : "s"} redacted before analysis`} />
+          <ul className="px__list">
+            {data.privacy_notes.map((n, i) => <li key={i}>{n}</li>)}
+          </ul>
+        </div>
+        <div className="px__exports card card--raised">
+          <Label accent>Take it with you</Label>
+          <p className="px__blurb">Export the redacted narrative and the structured findings. The raw trace never leaves your machine.</p>
+          <div className="px__btns">
+            <button className="btn btn--sm" onClick={() => dl(data.exports && data.exports.narrative_md, (data.trace_title||"trace")+"-redacted.md", "text/markdown")}><span>↓</span> Redacted narrative .md</button>
+            <button className="btn btn--sm" onClick={() => dl(data.exports && data.exports.report_md, (data.trace_title||"trace")+"-field-report.md", "text/markdown")}><span>↓</span> Field report .md</button>
+            <button className="btn btn--sm" onClick={() => dl(data.exports && data.exports.episodes_json, (data.trace_title||"trace")+"-episodes.json", "application/json")}><span>↓</span> Episodes .json</button>
+          </div>
+          <hr className="rule--dashed" />
+          <button className="btn btn--ghost btn--sm" onClick={onReset}>← Analyze another trace</button>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function ReportView({ data, variant, onReset }) {
+  const [selectedId, setSelectedId] = React.useState(
+    () => (data.verdict.tone === "risk"
+      ? (data.episodes.find((e) => toneOf(e.recovery_pattern) === "risk") || data.episodes[0]).episode_id
+      : data.episodes[0].episode_id)
+  );
+  React.useEffect(() => {
+    setSelectedId(data.episodes[0].episode_id);
+  }, [data]);
+  return (
+    <div className="report">
+      <ReportHeader data={data} />
+      <Verdict data={data} />
+      <TrailSection data={data} variant={variant} selectedId={selectedId} setSelectedId={setSelectedId} />
+      <DifficultyMap data={data} />
+      <DetourAnalysis data={data} />
+      <RecoveryPattern data={data} />
+      <OutcomeAudit data={data} />
+      <PrivacyExports data={data} onReset={onReset} />
+    </div>
+  );
+}
+
+Object.assign(window, { ReportView });

frontend/static/data.js

@@ -0,0 +1,320 @@
+/* ============================================================
+   Trace Field Notes — data: codebook labels + two analyses
+   Attaches TFN = { CODEBOOK, TONE_OF, TONE_META, SHORT, LONG } to window
+   ============================================================ */
+(function () {
+  // Human labels for codebook codes (from schemas.py)
+  const CODEBOOK = {
+    difficulty_type: {
+      requirement_uncertainty: "Requirement uncertainty",
+      localization_difficulty: "Localization difficulty",
+      architecture_complexity: "Architecture complexity",
+      implementation_difficulty: "Implementation difficulty",
+      compatibility_risk: "Compatibility risk",
+      verification_difficulty: "Verification difficulty",
+      environment_blocker: "Environment blocker",
+      insufficient_context: "Insufficient context",
+      conflicting_assumptions: "Conflicting assumptions",
+      unknown: "Unknown",
+    },
+    appraisal: {
+      local_fix_possible: "Local fix possible",
+      needs_more_context: "Needs more context",
+      initial_hypothesis_wrong: "Initial hypothesis wrong",
+      risk_is_higher_than_expected: "Risk higher than expected",
+      scope_too_large: "Scope too large",
+      needs_alternative_path: "Needs alternative path",
+      cannot_reliably_verify: "Cannot reliably verify",
+      task_boundary_unclear: "Task boundary unclear",
+      unknown: "Unknown",
+    },
+    detour_type: {
+      direct_continuation: "Direct continuation",
+      decomposition: "Decomposition",
+      scope_narrowing: "Scope narrowing",
+      alternative_path: "Alternative path",
+      workaround: "Workaround",
+      rollback_or_reversal: "Rollback / reversal",
+      hypothesis_switch: "Hypothesis switch",
+      verification_shift: "Verification shift",
+      ask_or_defer: "Ask / defer",
+      premature_closure: "Premature closure",
+      unknown: "Unknown",
+    },
+    resolution_mode: {
+      information_gathering: "Information gathering",
+      problem_reframing: "Problem reframing",
+      minimal_patch: "Minimal patch",
+      structural_change: "Structural change",
+      defensive_handling: "Defensive handling",
+      alternative_implementation: "Alternative implementation",
+      goal_reduction: "Goal reduction",
+      explicit_limitation: "Explicit limitation",
+      narrative_rationalization: "Narrative rationalization",
+      unknown: "Unknown",
+    },
+    recovery_pattern: {
+      smooth_recovery: "Smooth recovery",
+      iterative_recovery: "Iterative recovery",
+      detour_recovery: "Detour recovery",
+      partial_recovery: "Partial recovery",
+      failed_recovery: "Failed recovery",
+      avoidant_recovery: "Avoidant recovery",
+      overconfident_recovery: "Overconfident recovery",
+      reflective_recovery: "Reflective recovery",
+      unknown: "Unknown",
+    },
+    outcome_claim: {
+      resolved_with_confidence: "Resolved, confident",
+      resolved_with_caveat: "Resolved, with caveat",
+      partially_resolved: "Partially resolved",
+      not_resolved: "Not resolved",
+      needs_verification: "Needs verification",
+      uncertain_but_proceeding: "Uncertain, proceeding",
+      premature_success_claim: "Premature success claim",
+      unknown: "Unknown",
+    },
+  };
+
+  // recovery_pattern -> tone bucket
+  const TONE_OF = {
+    smooth_recovery: "stable",
+    reflective_recovery: "stable",
+    iterative_recovery: "iterative",
+    detour_recovery: "detour",
+    partial_recovery: "partial",
+    failed_recovery: "risk",
+    avoidant_recovery: "risk",
+    overconfident_recovery: "risk",
+    unknown: "unknown",
+  };
+
+  const TONE_META = {
+    stable:    { label: "On-route",          rating: "Smooth / reflective",  blurb: "Understood the snag and kept moving." },
+    detour:    { label: "Productive detour",  rating: "Recovered via reroute", blurb: "Left the planned path, found a better one." },
+    iterative: { label: "Switchbacks",        rating: "Iterative recovery",   blurb: "Closed in through repeated attempts." },
+    partial:   { label: "Caution",            rating: "Partial recovery",     blurb: "Solved part; carried a known caveat." },
+    risk:      { label: "Hazard",             rating: "Failed / overclaimed", blurb: "Did not clearly resolve, or claimed too much." },
+    unknown:   { label: "Unsurveyed",         rating: "Unknown",              blurb: "Too little signal to read." },
+  };
+
+  // ---- SHORT: the repo's redacted sample (upload-path fix) ----
+  const SHORT = {
+    trace_title: "sample_trace_redacted.jsonl",
+    agent_type_guess: "codex",
+    analysis_scope: "assistant narrative messages only",
+    engine: "Deterministic field notes",
+    captured: "2026-06-06 · 10:00–10:03 UTC",
+    narrative_message_count: 4,
+    redaction_count: 2,
+    duration_total: "3m 12s",
+    verdict: {
+      tone: "stable",
+      headline: "Honest close-out after a clean reroute.",
+      detail:
+        "One short episode. The agent caught its own wrong assumption about the upload shape, narrowed the fix instead of touching the parser, and closed with an explicit caveat about the un-tested deployment path.",
+      honesty: "candid",
+    },
+    overall_patterns: {
+      difficulty_style: "A single localization snag: the bug was not where the agent first looked.",
+      detour_style: "One productive narrowing — it scoped the fix to the upload boundary rather than the parser.",
+      recovery_style: "Reflective. It named the wrong assumption out loud and corrected course.",
+      risk_or_caveat: "Closes with an explicit, honest caveat: the deployed Space path was not verified.",
+    },
+    privacy_notes: [
+      "1 email address redacted.",
+      "1 GitHub token (ghp_…) redacted.",
+      "Tool-call contents ignored by default; only narrative messages analyzed.",
+    ],
+    episodes: [
+      {
+        episode_id: "E01",
+        title: "The bug wasn't where it looked",
+        message_span: { start_index: 0, end_index: 3, start_time: "10:00:20", end_time: "10:03:12", duration_label: "2m 52s" },
+        initial_intention: "Inspect the failing upload path, then trace how the report export is wired.",
+        reported_difficulty: "The parser handled JSONL fine — but the Gradio file object can arrive as a temporary path, so the initial assumption about the upload shape was wrong.",
+        difficulty_type: "localization_difficulty",
+        appraisal: "initial_hypothesis_wrong",
+        strategy_before: "Plan to fix the parser where the failure surfaced.",
+        strategy_after: "Narrow the fix to the upload boundary; add a helper that normalizes filepath / name / path attributes.",
+        detour_type: "scope_narrowing",
+        resolution_mode: "defensive_handling",
+        recovery_pattern: "reflective_recovery",
+        outcome_claim: "resolved_with_caveat",
+        productive_detour: "yes",
+        evidence_quotes: [
+          "The issue is not where I expected… my initial assumption about the upload shape was wrong.",
+          "Caveat: I did not run the deployed Space yet, so the deployment path still needs verification.",
+        ],
+        analyst_memo:
+          "Textbook reflective recovery: the agent surfaces the wrong assumption explicitly rather than quietly patching over it, then chooses the smaller, safer change. The closing caveat is genuine, not decorative.",
+      },
+    ],
+  };
+
+  // ---- LONG: invented richer Claude Code session ----
+  const LONG = {
+    trace_title: "claude_code__redis-session-migration.jsonl",
+    agent_type_guess: "claude_code",
+    analysis_scope: "assistant narrative messages only",
+    engine: "NVIDIA Nemotron 3 Nano 30B-A3B assist",
+    captured: "2026-06-04 · 14:02–14:58 UTC",
+    narrative_message_count: 41,
+    redaction_count: 6,
+    duration_total: "56m 10s",
+    verdict: {
+      tone: "risk",
+      headline: "Strong start, then a flaky test got papered over.",
+      detail:
+        "Six episodes. The agent scoped well and handled a real architecture surprise with a clean decomposition — but the migration's hardest problem, an un-reproducible logout flake, was wrapped in a retry and then narrated as 'done'. The final claim outruns the evidence.",
+      honesty: "overclaimed",
+    },
+    overall_patterns: {
+      difficulty_style:
+        "Front-loaded clarity, back-loaded risk: localization and architecture were handled openly; verification was where it strained.",
+      detour_style:
+        "Mostly productive. The decomposition of the session-store coupling (E03) was the trip's best move; the late retry (E05) was a workaround dressed as a fix.",
+      recovery_style:
+        "Reframes and narrows scope confidently, rarely asks for help, and tends to close the loop a beat before verification is actually established.",
+      risk_or_caveat:
+        "The logout flake (E05) was never reproduced. A retry hides it, and the closeout (E06) reads as a root-cause fix it cannot support.",
+    },
+    privacy_notes: [
+      "2 absolute local paths redacted.",
+      "1 Authorization: Bearer token redacted.",
+      "1 internal hostname redacted.",
+      "2 email addresses redacted.",
+      "Tool-call contents ignored by default; only narrative messages analyzed.",
+    ],
+    episodes: [
+      {
+        episode_id: "E01",
+        title: "Pinning down the ask",
+        message_span: { start_index: 1, end_index: 4, start_time: "14:02", end_time: "14:07", duration_label: "5m 04s" },
+        initial_intention: "Migrate the session store from in-memory to Redis and fix the flaky logout test.",
+        reported_difficulty: "Two requests are entangled — is the flake caused by the in-memory store, or independent? The spec doesn't say.",
+        difficulty_type: "requirement_uncertainty",
+        appraisal: "task_boundary_unclear",
+        strategy_before: "Treat it as one migration task.",
+        strategy_after: "Split into two tracks: (1) store migration, (2) the logout flake — and confirm whether they're related.",
+        detour_type: "decomposition",
+        resolution_mode: "problem_reframing",
+        recovery_pattern: "smooth_recovery",
+        outcome_claim: "resolved_with_confidence",
+        productive_detour: "yes",
+        evidence_quotes: [
+          "I'll separate the migration from the flake so I don't assume they share a root cause.",
+        ],
+        analyst_memo:
+          "Good opening discipline. Splitting the two concerns up front is what later lets it reason about the store cleanly — even if the flake ultimately doesn't get the same rigor.",
+      },
+      {
+        episode_id: "E02",
+        title: "Chasing the flake",
+        message_span: { start_index: 7, end_index: 13, start_time: "14:09", end_time: "14:21", duration_label: "11m 38s" },
+        initial_intention: "Reproduce the logout test failure locally before changing anything.",
+        reported_difficulty: "The test passes on every local run. It only fails in CI, intermittently — the agent can't see the failure it's meant to fix.",
+        difficulty_type: "verification_difficulty",
+        appraisal: "needs_more_context",
+        strategy_before: "Run the test, watch it fail, bisect.",
+        strategy_after: "Read CI logs, then hypothesize a timing/order dependency rather than a logic bug.",
+        detour_type: "hypothesis_switch",
+        resolution_mode: "information_gathering",
+        recovery_pattern: "iterative_recovery",
+        outcome_claim: "partially_resolved",
+        productive_detour: "mixed",
+        evidence_quotes: [
+          "It passes locally every time, so this looks like a test-ordering or timing issue, not a logic bug.",
+        ],
+        analyst_memo:
+          "Honest about not being able to reproduce. The pivot to a timing hypothesis is reasonable — but note it never actually confirms the hypothesis, which sets up the weak closeout later.",
+      },
+      {
+        episode_id: "E03",
+        title: "The store was wired into everything",
+        message_span: { start_index: 15, end_index: 23, start_time: "14:22", end_time: "14:36", duration_label: "13m 50s" },
+        initial_intention: "Swap the in-memory store for a Redis-backed implementation behind the same interface.",
+        reported_difficulty: "The 'interface' is leaky — middleware, the rate limiter, and a websocket handler all reach into the store's internals directly.",
+        difficulty_type: "architecture_complexity",
+        appraisal: "scope_too_large",
+        strategy_before: "Drop-in replace the store class.",
+        strategy_after: "Introduce an adapter, migrate call sites one subsystem at a time, keep the old store as a fallback during the swap.",
+        detour_type: "decomposition",
+        resolution_mode: "structural_change",
+        recovery_pattern: "detour_recovery",
+        outcome_claim: "resolved_with_caveat",
+        productive_detour: "yes",
+        evidence_quotes: [
+          "The store interface is leakier than expected; I'll add an adapter and migrate call sites one subsystem at a time.",
+        ],
+        analyst_memo:
+          "The strongest stretch of the trip. Faced with a bigger-than-expected blast radius, it decomposes instead of forcing the drop-in, and keeps a fallback. This is what a productive detour looks like.",
+      },
+      {
+        episode_id: "E04",
+        title: "Don't break live sessions",
+        message_span: { start_index: 24, end_index: 29, start_time: "14:37", end_time: "14:46", duration_label: "9m 12s" },
+        initial_intention: "Change the cookie/session encoding to the Redis key format.",
+        reported_difficulty: "A naive switch invalidates every signed-in user's session on deploy.",
+        difficulty_type: "compatibility_risk",
+        appraisal: "risk_is_higher_than_expected",
+        strategy_before: "Write sessions in the new format.",
+        strategy_after: "Dual-read old + new formats for a deprecation window; only write the new format.",
+        detour_type: "alternative_path",
+        resolution_mode: "defensive_handling",
+        recovery_pattern: "partial_recovery",
+        outcome_claim: "resolved_with_caveat",
+        productive_detour: "yes",
+        evidence_quotes: [
+          "I'll dual-read both formats during a deprecation window so existing sessions survive the deploy.",
+        ],
+        analyst_memo:
+          "Recognizes the regression risk before shipping it — a real save. Marked partial because the deprecation window's cleanup is described but left as a TODO, not implemented.",
+      },
+      {
+        episode_id: "E05",
+        title: "Making the flake quiet",
+        message_span: { start_index: 31, end_index: 36, start_time: "14:47", end_time: "14:53", duration_label: "6m 30s" },
+        initial_intention: "Close out the original logout flake from E02.",
+        reported_difficulty: "Still can't reproduce it. The timing hypothesis was never confirmed.",
+        difficulty_type: "verification_difficulty",
+        appraisal: "cannot_reliably_verify",
+        strategy_before: "Find and fix the race.",
+        strategy_after: "Wrap the logout assertion in a retry-with-backoff so CI goes green.",
+        detour_type: "workaround",
+        resolution_mode: "narrative_rationalization",
+        recovery_pattern: "overconfident_recovery",
+        outcome_claim: "premature_success_claim",
+        productive_detour: "no",
+        evidence_quotes: [
+          "Adding a retry around the logout assertion; the test is green now so the flake is resolved.",
+        ],
+        analyst_memo:
+          "The pivot point of the whole session. A retry suppresses the symptom without ever locating the cause, and 'green now' is presented as 'resolved'. This is the gap between what was done and what was claimed.",
+      },
+      {
+        episode_id: "E06",
+        title: "Calling it done",
+        message_span: { start_index: 38, end_index: 40, start_time: "14:55", end_time: "14:58", duration_label: "3m 06s" },
+        initial_intention: "Summarize the work and hand back.",
+        reported_difficulty: "—",
+        difficulty_type: "unknown",
+        appraisal: "unknown",
+        strategy_before: "Report status.",
+        strategy_after: "Frames migration + flake as both fully resolved in the summary.",
+        detour_type: "premature_closure",
+        resolution_mode: "narrative_rationalization",
+        recovery_pattern: "overconfident_recovery",
+        outcome_claim: "premature_success_claim",
+        productive_detour: "no",
+        evidence_quotes: [
+          "Migration complete and the flaky logout test is fixed and stable.",
+        ],
+        analyst_memo:
+          "The summary inherits E05's overclaim and drops the caveats from E04. A reader skimming only the final message would believe more was verified than actually was.",
+      },
+    ],
+  };
+
+  window.TFN = { CODEBOOK, TONE_OF, TONE_META, SHORT, LONG };
+})();

frontend/static/field_report.css

@@ -0,0 +1,619 @@
+/* Trace Field Notes — designer's field-notebook / trail-map system.
+   Fonts swapped to Google Fonts (originals were bundled woff2). */
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;1,400&family=Spectral:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,400;1,500&family=Spectral+SC:wght@400;500;600;700&display=swap');
+
+:root {
+  --paper-0: #e0d5bc;   /* page edge / outside the map */
+  --paper-1: #efe7d3;   /* main field */
+  --paper-2: #f6f0e0;   /* card */
+  --paper-3: #fcf8ee;   /* raised */
+  --paper-inset: #e9e0c9;
+
+  --ink:   #2a261d;
+  --ink-2: #574f3f;
+  --ink-3: #897f68;
+  --ink-faint: #a89b7e;
+
+  --rule:        #d8ccad;
+  --rule-strong: #c5b690;
+  --edge:        #cdbe98;
+  --edge-strong: #b6a577;
+
+  --accent:      #2f6b4f;
+  --accent-2:    #3c875f;
+  --accent-deep: #234f3b;
+  --accent-tint: rgba(47, 107, 79, 0.10);
+  --on-accent:   #f6f0e0;
+
+  --warn:        #b06a1f;
+  --warn-tint:   rgba(176, 106, 31, 0.10);
+
+  /* trail-difficulty tone palette */
+  --tone-stable:    #3f7d52;
+  --tone-detour:    #356f9c;
+  --tone-iterative: #2f8a86;
+  --tone-partial:   #b9852b;
+  --tone-risk:      #b24a30;
+  --tone-unknown:   #8a8270;
+
+  --shadow-card: 0 1px 0 rgba(255,255,255,0.5) inset, 0 8px 24px -16px rgba(42,38,29,0.5);
+  --shadow-pop:  0 18px 50px -22px rgba(42,38,29,0.55);
+
+  --paper-grain: rgba(120, 104, 70, 0.05);
+  --topo-stroke: rgba(120, 104, 70, 0.16);
+  --topo-stroke-strong: rgba(120, 104, 70, 0.26);
+
+  --font-serif: 'Spectral', Georgia, 'Times New Roman', serif;
+  --font-sc:    'Spectral SC', 'Spectral', serif;
+  --font-mono:  'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+
+  /* density (overwritten by [data-density]) */
+  --space: 1;
+  --radius: 3px;
+  --radius-lg: 5px;
+}
+
+/* ---------- Tokens: DARK (dusk survey) ---------- */
+[data-theme="dark"] {
+  --paper-0: #14130f;
+  --paper-1: #1c1a15;
+  --paper-2: #232019;
+  --paper-3: #2b271f;
+  --paper-inset: #18160f;
+
+  --ink:   #f0e9d6;
+  --ink-2: #cabfa3;
+  --ink-3: #9a8f74;
+  --ink-faint: #6f6650;
+
+  --rule:        rgba(180, 160, 110, 0.18);
+  --rule-strong: rgba(180, 160, 110, 0.30);
+  --edge:        rgba(180, 160, 110, 0.22);
+  --edge-strong: rgba(180, 160, 110, 0.38);
+
+  --accent:      #5cae84;
+  --accent-2:    #6fc197;
+  --accent-deep: #8ad3ac;
+  --accent-tint: rgba(92, 174, 132, 0.14);
+  --on-accent:   #14130f;
+
+  --warn:        #d99a4e;
+  --warn-tint:   rgba(217, 154, 78, 0.14);
+
+  --tone-stable:    #5fb079;
+  --tone-detour:    #5b9fce;
+  --tone-iterative: #4fc1bb;
+  --tone-partial:   #d9a64a;
+  --tone-risk:      #e0775a;
+  --tone-unknown:   #a99e83;
+
+  --shadow-card: 0 1px 0 rgba(255,255,255,0.04) inset, 0 10px 30px -18px rgba(0,0,0,0.8);
+  --shadow-pop:  0 22px 60px -24px rgba(0,0,0,0.9);
+
+  --paper-grain: rgba(255, 240, 200, 0.025);
+  --topo-stroke: rgba(190, 170, 120, 0.12);
+  --topo-stroke-strong: rgba(190, 170, 120, 0.22);
+}
+
+/* ---------- Density ---------- */
+[data-density="compact"] { --space: 0.78; }
+[data-density="regular"] { --space: 1; }
+[data-density="comfy"]   { --space: 1.28; }
+
+/* ---------- Voice (narrative typeface) ---------- */
+[data-voice="terminal"] { --font-body: var(--font-mono); --body-size: 14.5px; --body-lh: 1.65; }
+:root, [data-voice="journal"] { --font-body: var(--font-serif); --body-size: 17px; --body-lh: 1.62; }
+
+/* ============================================================
+   Base
+   ============================================================ */
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  background: var(--paper-0);
+  color: var(--ink);
+  font-family: var(--font-serif);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+::selection { background: var(--accent-tint); }
+
+button { font-family: inherit; cursor: pointer; }
+a { color: var(--accent); }
+
+.app-root { position: relative; min-height: 100vh; }
+
+/* topo + grain backdrop sits behind everything */
+.backdrop {
+  position: fixed; inset: 0; z-index: 0; pointer-events: none;
+  background:
+    radial-gradient(120% 90% at 50% -10%, color-mix(in srgb, var(--paper-1) 70%, transparent), transparent 60%),
+    var(--paper-1);
+}
+.backdrop .grain {
+  position: absolute; inset: 0;
+  background-image: radial-gradient(var(--paper-grain) 0.6px, transparent 0.7px);
+  background-size: 4px 4px;
+  opacity: 0.9;
+}
+.backdrop svg { position: absolute; inset: 0; width: 100%; height: 100%; }
+.no-topo .backdrop svg { display: none; }
+
+.page { position: relative; z-index: 1; }
+
+/* ============================================================
+   Shared atoms
+   ============================================================ */
+
+/* small-cap stamped label */
+.label {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  color: var(--ink-3);
+}
+.label--accent { color: var(--accent); }
+
+/* coordinate / meta mono text */
+.mono { font-family: var(--font-mono); }
+.muted { color: var(--ink-3); }
+
+.kicker {
+  display: inline-flex; align-items: center; gap: 8px;
+  font-family: var(--font-mono); font-size: 11.5px; font-weight: 600;
+  letter-spacing: 0.18em; text-transform: uppercase; color: var(--accent);
+}
+.kicker::before {
+  content: ""; width: 18px; height: 1px; background: var(--accent); opacity: 0.6;
+}
+
+/* paper card with torn/taped feel */
+.card {
+  position: relative;
+  background: var(--paper-2);
+  border: 1px solid var(--edge);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-card);
+}
+.card--raised { background: var(--paper-3); }
+
+/* ruled divider */
+.rule { height: 1px; background: var(--rule); border: 0; }
+.rule--dashed { height: 0; border: 0; border-top: 1px dashed var(--rule-strong); }
+
+/* chips */
+.chip {
+  display: inline-flex; align-items: center; gap: 6px;
+  font-family: var(--font-mono); font-size: 11px; font-weight: 500;
+  letter-spacing: 0.04em;
+  padding: 3px 9px; border-radius: 999px;
+  border: 1px solid var(--edge);
+  background: color-mix(in srgb, var(--paper-3) 70%, transparent);
+  color: var(--ink-2);
+  white-space: nowrap;
+}
+.chip .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--tone-unknown); }
+
+/* tone dot + swatch */
+.tone-dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; box-shadow: 0 0 0 3px color-mix(in srgb, currentColor 18%, transparent); }
+
+/* rubber stamp */
+.stamp {
+  display: inline-flex; align-items: center; gap: 8px;
+  font-family: var(--font-sc); font-weight: 700;
+  letter-spacing: 0.06em; text-transform: uppercase;
+  padding: 7px 14px;
+  border: 2px solid currentColor; border-radius: 4px;
+  transform: rotate(-2.5deg);
+  opacity: 0.92;
+}
+.stamp::before { content: ""; width: 9px; height: 9px; border-radius: 50%; background: currentColor; }
+
+/* buttons */
+.btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 9px;
+  font-family: var(--font-mono); font-size: 13px; font-weight: 600;
+  letter-spacing: 0.04em;
+  padding: 12px 20px; border-radius: var(--radius);
+  border: 1px solid var(--edge-strong); white-space: nowrap;
+  background: var(--paper-3); color: var(--ink);
+  transition: transform .12s ease, background .15s ease, box-shadow .15s ease, border-color .15s ease;
+}
+.btn:hover { transform: translateY(-1px); box-shadow: var(--shadow-card); border-color: var(--ink-3); }
+.btn:active { transform: translateY(0); }
+.btn--primary {
+  background: var(--accent); border-color: var(--accent-deep); color: var(--on-accent);
+}
+.btn--primary:hover { background: var(--accent-2); border-color: var(--accent); }
+.btn--ghost { background: transparent; }
+.btn--sm { padding: 8px 13px; font-size: 12px; }
+.btn:disabled { opacity: 0.45; cursor: not-allowed; transform: none; }
+
+/* focus ring */
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+/* ============================================================
+   views.css — layout + component styling for all views
+   ============================================================ */
+
+/* generic spacing helpers driven by --space */
+.landing, .report, .analyzing, .report-wrap {
+  max-width: 1140px;
+  margin: 0 auto;
+  padding: 0 28px;
+}
+.report-wrap { padding-top: 18px; padding-bottom: 80px; }
+
+/* ---------------- Top bar ---------------- */
+.topbar {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 26px 0 18px;
+}
+.topbar__brand { display: flex; align-items: center; gap: 13px; }
+.topbar__word { display: flex; flex-direction: column; line-height: 1.1; }
+.topbar__name { font-family: var(--font-serif); font-weight: 700; font-size: 19px; letter-spacing: -0.01em; }
+.topbar__tag { font-size: 11px; color: var(--ink-3); letter-spacing: 0.02em; margin-top: 2px; }
+.topbar__right { display: flex; gap: 8px; }
+.topbar__pill {
+  font-size: 10.5px; font-weight: 500; letter-spacing: 0.08em; text-transform: uppercase;
+  padding: 4px 10px; border-radius: 999px; border: 1px solid var(--edge);
+  color: var(--ink-3); background: color-mix(in srgb, var(--paper-3) 50%, transparent);
+}
+
+/* ---------------- Hero ---------------- */
+.hero {
+  position: relative; overflow: hidden;
+  padding: calc(40px * var(--space)) 0 calc(26px * var(--space));
+  border-top: 1px solid var(--rule);
+  margin-top: 4px;
+}
+.hero__title {
+  font-family: var(--font-serif); font-weight: 700;
+  font-size: clamp(34px, 5.2vw, 58px); line-height: 1.04; letter-spacing: -0.022em;
+  margin: 16px 0 0; max-width: none; text-wrap: balance;
+}
+.hero__amp { color: var(--accent); font-style: italic; font-weight: 500; }
+.hero__sub {
+  font-family: var(--font-serif); font-size: clamp(16px, 1.7vw, 19px); line-height: 1.55;
+  color: var(--ink-2); max-width: 64ch; margin: 18px 0 0;
+}
+.hero__sub em { color: var(--accent); font-style: italic; }
+
+/* ---------------- Privacy callout ---------------- */
+.privacy {
+  display: flex; gap: 13px; align-items: flex-start;
+  margin: 22px 0 34px; padding: 14px 16px;
+  border: 1px solid color-mix(in srgb, var(--warn) 40%, var(--edge));
+  border-left: 3px solid var(--warn);
+  background: var(--warn-tint); border-radius: var(--radius-lg);
+}
+.privacy__mark {
+  flex: none; width: 22px; height: 22px; border-radius: 50%;
+  display: grid; place-items: center; font-family: var(--font-mono); font-weight: 700;
+  color: var(--on-accent); background: var(--warn); font-size: 13px; margin-top: 1px;
+}
+.privacy p { margin: 0; font-size: 14.5px; line-height: 1.5; color: var(--ink-2); }
+.privacy b { color: var(--ink); }
+
+/* ---------------- Landing grid ---------------- */
+.landing__grid {
+  display: grid; grid-template-columns: 1.15fr 0.85fr; gap: 22px;
+  padding-bottom: 70px;
+}
+.panel { padding: calc(22px * var(--space)); }
+.guide { display: flex; flex-direction: column; gap: 22px; }
+
+/* section head */
+.sec-head { margin-bottom: 16px; }
+.sec-head__top { display: flex; align-items: center; gap: 12px; }
+.sec-head__no { font-size: 12px; color: var(--ink-faint); font-weight: 600; }
+.sec-head__title {
+  font-family: var(--font-serif); font-weight: 600; letter-spacing: -0.015em;
+  font-size: clamp(20px, 2.4vw, 27px); line-height: 1.12; margin: 8px 0 0;
+}
+.sec-head__sub { font-size: 14.5px; line-height: 1.5; color: var(--ink-2); margin: 9px 0 0; max-width: 60ch; }
+
+/* dropzone */
+.drop {
+  margin: 4px 0 18px; border: 1.5px dashed var(--edge-strong); border-radius: var(--radius-lg);
+  background: var(--paper-inset); padding: 30px 18px; text-align: center;
+  cursor: pointer; transition: border-color .15s, background .15s, transform .12s;
+}
+.drop:hover { border-color: var(--accent); transform: translateY(-1px); }
+.drop--over { border-color: var(--accent); background: var(--accent-tint); }
+.drop--staged { border-style: solid; border-color: var(--accent); background: var(--accent-tint); }
+.drop__empty { display: flex; flex-direction: column; align-items: center; gap: 6px; }
+.drop__icon { font-size: 30px; color: var(--accent); line-height: 1; }
+.drop__title { font-family: var(--font-serif); font-size: 17px; font-weight: 600; }
+.drop__title code, .muted code { font-family: var(--font-mono); font-size: 0.85em; background: var(--paper-inset); padding: 1px 5px; border-radius: 3px; }
+.drop__staged { display: flex; flex-direction: column; gap: 6px; align-items: center; }
+.drop__file { font-size: 14px; font-weight: 600; color: var(--accent-deep); word-break: break-all; }
+
+/* toggles */
+.opts { display: flex; flex-direction: column; gap: 4px; margin-bottom: 18px; }
+.toggle {
+  display: flex; align-items: center; gap: 12px; width: 100%; text-align: left;
+  background: none; border: 0; padding: 9px 6px; border-radius: var(--radius);
+}
+.toggle:hover { background: var(--paper-inset); }
+.toggle--locked { cursor: default; opacity: 0.72; }
+.toggle--locked:hover { background: none; }
+.toggle__sw {
+  flex: none; width: 38px; height: 22px; border-radius: 999px; padding: 2px;
+  background: var(--rule-strong); transition: background .18s; display: flex;
+}
+.toggle--on .toggle__sw { background: var(--accent); }
+.toggle__knob {
+  width: 18px; height: 18px; border-radius: 50%; background: var(--paper-3);
+  box-shadow: 0 1px 2px rgba(0,0,0,0.3); transition: transform .18s;
+}
+.toggle--on .toggle__knob { transform: translateX(16px); }
+.toggle__txt { display: flex; flex-direction: column; line-height: 1.3; flex: 1; min-width: 0; }
+.toggle__label { font-size: 14px; font-weight: 600; color: var(--ink); }
+.toggle__sub { font-size: 12px; }
+
+/* engine */
+.engine { margin-bottom: 20px; }
+.engine__opts { display: flex; flex-direction: column; gap: 8px; margin: 10px 0; }
+.engine__opt {
+  display: flex; justify-content: space-between; align-items: baseline; gap: 10px;
+  padding: 11px 14px; border: 1px solid var(--edge); border-radius: var(--radius);
+  background: var(--paper-3); color: var(--ink); text-align: left; transition: border-color .15s, background .15s;
+}
+.engine__opt:hover { border-color: var(--ink-3); }
+.engine__opt--on { border-color: var(--accent); background: var(--accent-tint); box-shadow: inset 0 0 0 1px var(--accent); }
+.engine__name { font-family: var(--font-serif); font-weight: 600; font-size: 15px; white-space: nowrap; color: var(--ink); }
+.engine__detail { font-size: 11.5px; color: var(--ink-3); white-space: nowrap; text-align: right; }
+.engine__note { font-size: 12px; line-height: 1.45; margin: 4px 0 0; }
+
+.panel__actions { display: flex; flex-wrap: wrap; gap: 10px; }
+.panel__actions .btn--primary { flex: 1 1 auto; min-width: 170px; }
+
+/* guide: paths table */
+.paths { width: 100%; border-collapse: collapse; }
+.paths td { padding: 9px 4px; border-bottom: 1px dashed var(--rule); font-size: 14px; }
+.paths tr:last-child td { border-bottom: 0; }
+.paths__agent { font-family: var(--font-serif); font-weight: 600; width: 38%; }
+.paths__path { color: var(--accent-deep); font-size: 12.5px; }
+
+/* agent-callable */
+.agentcall__hd { display: flex; justify-content: space-between; align-items: flex-start; gap: 10px; }
+.agentcall__blurb { font-size: 13.5px; line-height: 1.5; color: var(--ink-2); margin: 4px 0 12px; }
+.agentcall__pre {
+  margin: 0; padding: 14px; border-radius: var(--radius); background: var(--paper-inset);
+  border: 1px solid var(--edge); font-size: 11.5px; line-height: 1.6; color: var(--ink-2);
+  white-space: pre-wrap; max-height: 200px; overflow: auto;
+}
+
+.getrow { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+.getrow__item {
+  display: flex; flex-direction: column; gap: 3px; padding: 13px;
+  border: 1px solid var(--edge); border-radius: var(--radius); background: var(--paper-2);
+}
+.getrow__t { font-family: var(--font-serif); font-weight: 600; font-size: 14px; }
+.getrow__s { font-size: 11.5px; line-height: 1.35; }
+
+/* ---------------- Analyzing ---------------- */
+.analyzing { min-height: 78vh; display: grid; place-items: center; }
+.analyzing__card { padding: 34px 38px; width: min(440px, 90vw); }
+.analyzing__svg { width: 100%; height: auto; margin-bottom: 14px; }
+.analyzing__trail { stroke-dasharray: 360; stroke-dashoffset: 360; animation: draw 2.4s ease forwards; }
+@keyframes draw { to { stroke-dashoffset: 0; } }
+.analyzing__dot { offset-path: path("M20 96 C 70 60, 100 104, 150 70 S 230 30, 300 44"); animation: ride 2.4s ease forwards; }
+@keyframes ride { from { offset-distance: 0%; } to { offset-distance: 100%; } }
+.analyzing__steps { list-style: none; margin: 16px 0 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }
+.analyzing__steps li { font-size: 14px; color: var(--ink-faint); display: flex; gap: 10px; transition: color .3s; }
+.analyzing__steps li.active { color: var(--ink); }
+.analyzing__steps li.done { color: var(--ink-2); }
+.analyzing__tick { color: var(--accent); width: 14px; }
+
+/* ---------------- Report ---------------- */
+.report-back { margin-bottom: 16px; }
+.report { padding: 0; }
+.report > * + * { margin-top: calc(34px * var(--space)); }
+.sec > * + * { margin-top: 18px; }
+
+/* report header (specimen tag) */
+.rhead {
+  position: relative; padding: 24px 26px; border: 1px solid var(--edge);
+  border-radius: var(--radius-lg); background: var(--paper-2);
+  background-image: repeating-linear-gradient(var(--rule) 0 1px, transparent 1px 28px);
+  background-position: 0 54px;
+}
+.rhead__tag {
+  position: absolute; top: 0; right: 22px; transform: translateY(-50%) rotate(1.5deg);
+  font-size: 11px; font-weight: 600; letter-spacing: 0.14em; color: var(--on-accent); white-space: nowrap;
+  background: var(--accent-deep); padding: 5px 11px; border-radius: 3px;
+}
+.rhead__file { font-family: var(--font-mono); font-weight: 600; font-size: clamp(18px, 2.4vw, 24px); margin: 4px 0 0; word-break: break-all; }
+.rhead__grid { display: grid; grid-template-columns: repeat(6, 1fr); gap: 14px; margin: 20px 0 0; }
+.rhead__cell { display: flex; flex-direction: column; gap: 3px; }
+.rhead__cell dd { margin: 0; font-size: 13px; color: var(--ink-2); text-transform: capitalize; }
+.rhead__cell .mono { font-size: 12.5px; }
+
+/* verdict */
+.verdict {
+  position: relative; overflow: hidden; display: grid; grid-template-columns: 1.5fr 1fr;
+  gap: 28px; padding: 28px 30px 28px 36px;
+}
+.verdict__band { position: absolute; left: 0; top: 0; bottom: 0; width: 7px; background: var(--tone); }
+.verdict__headline {
+  font-family: var(--font-serif); font-weight: 700; letter-spacing: -0.02em;
+  font-size: clamp(24px, 3.2vw, 36px); line-height: 1.08; margin: 12px 0 0; text-wrap: balance;
+}
+.verdict__detail { font-size: 15.5px; line-height: 1.55; color: var(--ink-2); margin: 14px 0 0; }
+.verdict__stamps { margin-top: 18px; }
+.verdict__right { display: flex; flex-direction: column; gap: 16px; justify-content: center;
+  border-left: 1px dashed var(--rule-strong); padding-left: 26px; }
+.verdict__gauge { display: flex; flex-direction: column; gap: 4px; }
+.verdict__gauge-val { font-family: var(--font-serif); font-weight: 700; font-size: 21px; color: var(--tone); line-height: 1.1; }
+.verdict__gauge-blurb { font-size: 13px; color: var(--ink-2); line-height: 1.4; }
+.verdict__stats { display: flex; gap: 26px; }
+.verdict__stats > div { display: flex; flex-direction: column; gap: 2px; }
+.verdict__num { font-size: 25px; font-weight: 600; color: var(--ink); line-height: 1; white-space: nowrap; }
+
+/* ---------------- Trail ---------------- */
+.trail-card { padding: 22px 24px 18px; }
+.trail__chrome { display: grid; grid-template-columns: 26px 1fr; gap: 10px; }
+.trail__axis-y {
+  display: flex; flex-direction: column; justify-content: space-between; align-items: center;
+  writing-mode: vertical-rl; transform: rotate(180deg);
+  font-family: var(--font-mono); font-size: 9.5px; letter-spacing: 0.14em; text-transform: uppercase;
+  color: var(--ink-faint); padding: 6px 0 40px;
+}
+.trail__axis-y span:nth-child(2) { color: var(--ink-3); }
+.trail__plot { position: relative; aspect-ratio: 1000 / 360; width: 100%; }
+.trail__svg { position: absolute; inset: 0; width: 100%; height: 100%; }
+.trail__node { cursor: pointer; }
+.trail__node circle { transition: r .15s ease; }
+
+/* waypoint flags (HTML over SVG) */
+.wp {
+  position: absolute; transform: translate(-50%, -50%);
+  display: flex; flex-direction: column; align-items: center; gap: 1px;
+  background: none; border: 0; padding: 0; cursor: pointer; width: max-content; max-width: 150px;
+  z-index: 2;
+}
+.wp--above { transform: translate(-50%, calc(-100% - 16px)); }
+.wp--below { transform: translate(-50%, 18px); }
+.wp--first.wp--above { transform: translate(-14%, calc(-100% - 16px)); align-items: flex-start; }
+.wp--first.wp--below { transform: translate(-14%, 18px); align-items: flex-start; }
+.wp--first .wp__title { text-align: left; }
+.wp--last.wp--above { transform: translate(-86%, calc(-100% - 16px)); align-items: flex-end; }
+.wp--last.wp--below { transform: translate(-86%, 18px); align-items: flex-end; }
+.wp--last .wp__title { text-align: right; }
+.wp__id { font-size: 10.5px; font-weight: 700; color: var(--tone); letter-spacing: 0.06em; }
+.wp__title {
+  font-family: var(--font-serif); font-size: 12.5px; font-weight: 600; line-height: 1.12;
+  color: var(--ink); text-align: center; padding: 2px 7px; border-radius: 3px;
+  background: color-mix(in srgb, var(--paper-3) 88%, transparent);
+  border: 1px solid transparent; transition: border-color .15s, background .15s;
+}
+.wp__dur { font-size: 9.5px; color: var(--ink-faint); }
+.wp:hover .wp__title { border-color: var(--tone); }
+.wp--sel .wp__title { border-color: var(--tone); background: var(--paper-3); box-shadow: var(--shadow-card); }
+.wp--sel .wp__id { font-size: 11.5px; }
+
+.trail__xaxis {
+  display: flex; justify-content: space-between; align-items: center; margin: 14px 0 0 36px;
+  font-size: 11px; color: var(--ink-faint);
+}
+
+/* legend */
+.legend { display: flex; align-items: center; gap: 16px; flex-wrap: wrap; padding-top: 6px; }
+.legend__items { display: flex; flex-wrap: wrap; gap: 8px 18px; }
+.legend__item { display: flex; align-items: center; gap: 7px; }
+.legend__txt { font-size: 12px; color: var(--ink-2); }
+.legend__txt b { font-weight: 600; color: var(--ink); }
+
+/* episode detail */
+.epd { position: relative; overflow: hidden; padding: 24px 26px 26px; }
+.epd__band { position: absolute; left: 0; top: 0; bottom: 0; width: 6px; background: var(--tone); }
+.epd__head { display: flex; align-items: flex-start; gap: 14px; }
+.epd__head > div:last-child { flex: 1; min-width: 0; }
+.epd__id { display: flex; align-items: center; gap: 7px; flex: none; padding-top: 2px; }
+.epd__no { font-size: 17px; font-weight: 700; color: var(--tone); }
+.epd__title { font-family: var(--font-serif); font-weight: 700; font-size: 22px; letter-spacing: -0.015em; margin: 0; line-height: 1.16; }
+.epd__meta { font-size: 11.5px; color: var(--ink-3); margin-top: 6px; }
+.epd__flow { display: grid; grid-template-columns: repeat(3, 1fr); gap: 18px; margin: 20px 0; }
+.epd__step { display: flex; flex-direction: column; gap: 6px; }
+.epd__step p { margin: 0; font-size: 14px; line-height: 1.5; color: var(--ink-2); font-family: var(--font-body); }
+.epd__codes { display: flex; flex-wrap: wrap; gap: 7px; margin: 16px 0; }
+.epd__quotes { display: flex; flex-direction: column; gap: 8px; margin: 16px 0; }
+.epd__memo { margin-top: 16px; padding: 14px 16px; background: var(--accent-tint); border-radius: var(--radius); border: 1px solid color-mix(in srgb, var(--accent) 24%, transparent); }
+.epd__memo p { margin: 6px 0 0; font-size: 14.5px; line-height: 1.55; color: var(--ink); font-family: var(--font-body); }
+
+/* quotes */
+.quote {
+  margin: 0; padding: 8px 14px; border-left: 2px solid var(--rule-strong);
+  font-family: var(--font-serif); font-style: italic; font-size: 14.5px; line-height: 1.5; color: var(--ink-2);
+}
+.quote--sm { font-size: 13px; padding: 4px 12px; }
+
+/* ledger variant */
+.ledger { display: flex; flex-direction: column; }
+.ledger__row {
+  display: grid; grid-template-columns: 26px 36px 1fr auto; align-items: center; gap: 12px;
+  width: 100%; text-align: left; background: none; border: 0; border-bottom: 1px dashed var(--rule);
+  padding: 13px 6px; transition: background .12s;
+}
+.ledger__row:hover { background: var(--paper-inset); }
+.ledger__row--sel { background: var(--accent-tint); }
+.ledger__rail { display: grid; place-items: center; }
+.ledger__id { font-size: 12px; font-weight: 700; color: var(--tone); }
+.ledger__main { display: flex; flex-direction: column; gap: 2px; }
+.ledger__title { font-family: var(--font-serif); font-weight: 600; font-size: 15px; }
+.ledger__sub { font-size: 12px; color: var(--ink-3); }
+.ledger__dur { font-size: 11.5px; color: var(--ink-faint); }
+
+/* ---------------- Difficulty map ---------------- */
+.dmap { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 16px; }
+.dmap__cell { padding: 16px 18px; }
+.dmap__hd { display: flex; justify-content: space-between; align-items: baseline; gap: 10px; margin-bottom: 8px; }
+.dmap__type { font-family: var(--font-serif); font-weight: 600; font-size: 15.5px; }
+.dmap__ids { font-size: 11px; color: var(--accent-deep); }
+
+/* ---------------- Detour ---------------- */
+.detour { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
+.detour__col { padding: 18px; border-top: 3px solid var(--tone); }
+.detour__hd { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
+.detour__title { font-family: var(--font-serif); font-weight: 600; font-size: 15.5px; flex: 1; }
+.detour__count { font-size: 18px; font-weight: 600; color: var(--tone); }
+.detour__blurb { font-size: 13px; line-height: 1.45; color: var(--ink-2); margin: 0 0 12px; }
+.detour__list { display: flex; flex-direction: column; gap: 8px; }
+.detour__ep { display: flex; align-items: center; gap: 8px; }
+.detour__epid { font-size: 12px; font-weight: 700; color: var(--ink-3); }
+.detour__none { font-size: 13px; }
+
+/* ---------------- Recovery ---------------- */
+.recov { padding: 8px 26px; }
+.recov__row { display: grid; grid-template-columns: 30px 130px 1fr; gap: 16px; align-items: baseline; padding: 16px 0; border-bottom: 1px dashed var(--rule); }
+.recov__row:last-child { border-bottom: 0; }
+.recov__no { color: var(--ink-faint); font-size: 12px; }
+.recov__k { padding-top: 2px; }
+.recov__v { margin: 0; font-size: 15px; line-height: 1.55; color: var(--ink); font-family: var(--font-body); }
+
+/* ---------------- Outcome audit ---------------- */
+.audit { padding: 8px 24px; }
+.audit__row { display: grid; grid-template-columns: 54px 1fr; gap: 16px; padding: 16px 0; border-bottom: 1px dashed var(--rule); }
+.audit__row:last-child { border-bottom: 0; }
+.audit__rail { display: flex; flex-direction: column; align-items: center; gap: 8px; padding-top: 2px; }
+.audit__rail .mono { font-size: 12px; font-weight: 700; color: var(--ink-3); }
+.audit__claim { display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
+.audit__verb { font-family: var(--font-serif); font-weight: 700; font-size: 16px; color: var(--tone); }
+.audit__note { font-size: 13.5px; color: var(--ink-2); }
+.audit__body .quote { margin-top: 8px; }
+
+/* ---------------- Privacy / exports ---------------- */
+.px { display: grid; grid-template-columns: 1fr 0.8fr; gap: 22px; }
+.px__notes { padding: 22px 24px; }
+.px__list { margin: 8px 0 0; padding-left: 18px; }
+.px__list li { font-size: 14px; line-height: 1.7; color: var(--ink-2); }
+.px__exports { padding: 22px 24px; display: flex; flex-direction: column; gap: 12px; }
+.px__blurb { font-size: 14px; line-height: 1.5; color: var(--ink-2); margin: 0; }
+.px__btns { display: flex; flex-direction: column; gap: 9px; }
+.px__btns .btn { justify-content: flex-start; }
+.px__btns .btn span { color: var(--accent); font-weight: 700; }
+
+/* footer */
+.foot { display: flex; flex-direction: column; gap: 4px; margin-top: 50px; padding-top: 20px; border-top: 1px solid var(--rule); }
+.foot .mono { font-size: 12px; font-weight: 600; letter-spacing: 0.04em; }
+.foot .muted { font-size: 12.5px; }
+
+/* ---------------- Responsive ---------------- */
+@media (max-width: 920px) {
+  .landing__grid, .verdict, .px { grid-template-columns: 1fr; }
+  .verdict__right { border-left: 0; border-top: 1px dashed var(--rule-strong); padding-left: 0; padding-top: 18px; }
+  .rhead__grid { grid-template-columns: repeat(3, 1fr); }
+  .detour { grid-template-columns: 1fr; }
+  .epd__flow { grid-template-columns: 1fr; gap: 12px; }
+}
+@media (max-width: 560px) {
+  .landing, .report, .report-wrap { padding: 0 16px; }
+  .rhead__grid { grid-template-columns: repeat(2, 1fr); }
+  .getrow { grid-template-columns: 1fr; }
+  .wp__title { font-size: 11px; }
+  .recov__row { grid-template-columns: 1fr; gap: 4px; }
+}

model_runtime.py

@@ -1,11 +1,19 @@
-"""Optional model assistance through Hugging Face Inference Providers."""
+"""Local small-model assistance for Trace Field Notes on Hugging Face ZeroGPU.
+
+The analysis models run on the Space GPU through ``transformers``. Heavy imports
+(``torch``, ``transformers``) are loaded lazily inside the generator so that the
+deterministic analyzer, the test suite, and local development keep working
+without GPU dependencies installed. If a model cannot be loaded or its output is
+not valid JSON, :func:`analyzer.analyze_trace_file` falls back to the
+deterministic codebook and records the reason in the model notes.
+"""
 
 from __future__ import annotations
 
 import json
-import os
+import re
 from dataclasses import dataclass
-from typing import Any, Protocol
+from typing import Any, Callable
 
 from schemas import AnalysisResult
 
@@ -14,24 +22,24 @@ PRIMARY_MODEL_ID = "nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16"
 QUICK_MODEL_ID = "Qwen/Qwen3.5-9B"
 
 MODEL_CHOICES = {
-    "deterministic": {
-        "label": "Deterministic field notes",
-        "model_id": None,
+    "qwen": {
+        "label": "Qwen3.5 9B — quick analysis",
+        "model_id": QUICK_MODEL_ID,
     },
     "nemotron": {
-        "label": "NVIDIA Nemotron 3 Nano 30B-A3B assist",
+        "label": "NVIDIA Nemotron 3 Nano 30B-A3B — deeper analysis",
         "model_id": PRIMARY_MODEL_ID,
     },
-    "qwen": {
-        "label": "Quick small-model assist: Qwen3.5 9B",
-        "model_id": QUICK_MODEL_ID,
+    "deterministic": {
+        "label": "Rule-based — instant, no model",
+        "model_id": None,
     },
 }
 
+# (messages, *, model_id, max_new_tokens) -> raw model text.
+GenerateFn = Callable[..., str]
 
-class ChatClient(Protocol):
-    def chat_completion(self, *args: Any, **kwargs: Any) -> Any:
-        ...
+_MODEL_CACHE: dict[str, Any] = {}
 
 
 @dataclass(slots=True)
@@ -54,59 +62,93 @@ def run_model_assist(
     engine: str,
     result: AnalysisResult,
     narrative_text: str,
-    token: str | None = None,
-    client: ChatClient | None = None,
+    generate: GenerateFn | None = None,
 ) -> ModelAssistResult:
-    """Ask the selected model for a concise memo grounded in visible text."""
+    """Run the selected model on the GPU and return a concise grounded memo."""
 
     model_id = model_id_for_engine(engine)
     if not model_id:
         raise ValueError(f"No model is configured for analysis engine {engine!r}.")
 
     prompt = build_model_prompt(result, narrative_text)
-    if client is None:
-        from huggingface_hub import InferenceClient, get_token
-
-        resolved_token = token or os.getenv("HF_TOKEN") or get_token()
-        if not resolved_token:
-            raise ValueError(
-                "Sign in with Hugging Face to enable model assist through "
-                "the inference-api OAuth scope."
-            )
-
-        inference_client = InferenceClient(
-            model=model_id,
-            provider=os.getenv("TRACE_FIELD_NOTES_INFERENCE_PROVIDER") or None,
-            token=resolved_token,
-            timeout=float(os.getenv("TRACE_FIELD_NOTES_MODEL_TIMEOUT", "45")),
-        )
-    else:
-        inference_client = client
-    response = inference_client.chat_completion(
-        messages=[
-            {
-                "role": "system",
-                "content": (
-                    "You analyze visible coding-agent narrative messages. "
-                    "Do not infer hidden reasoning. Return JSON only."
-                ),
-            },
-            {"role": "user", "content": prompt},
-        ],
-        model=model_id,
-        max_tokens=900,
-        temperature=0.2,
-        response_format={"type": "json_object"},
-    )
-    content = extract_chat_content(response)
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "You analyze visible coding-agent narrative messages. "
+                "Do not infer hidden reasoning. Return JSON only."
+            ),
+        },
+        {"role": "user", "content": prompt},
+    ]
+
+    generator = generate or _local_generator
+    content = generator(messages, model_id=model_id, max_new_tokens=900)
     memo = parse_model_json(content)
     return ModelAssistResult(
         model_id=model_id,
         memo=memo,
-        note=f"Model assist completed with {model_id}.",
+        note=f"Model assist completed on the Space GPU with {model_id}.",
     )
 
 
+def _local_generator(
+    messages: list[dict[str, str]],
+    *,
+    model_id: str,
+    max_new_tokens: int,
+) -> str:
+    """Generate text with a locally loaded model on the ZeroGPU device.
+
+    Imported lazily: ``torch`` only needs to exist on the GPU Space, never for
+    the deterministic path, tests, or local development.
+    """
+
+    import torch
+
+    tokenizer, model = _load_model(model_id)
+    inputs = tokenizer.apply_chat_template(
+        messages,
+        add_generation_prompt=True,
+        return_tensors="pt",
+    ).to(model.device)
+    with torch.no_grad():
+        generated = model.generate(
+            inputs,
+            max_new_tokens=max_new_tokens,
+            do_sample=False,
+        )
+    completion = generated[0][inputs.shape[-1]:]
+    return tokenizer.decode(completion, skip_special_tokens=True)
+
+
+def _load_model(model_id: str) -> Any:
+    """Lazily load and cache a (tokenizer, model) pair on the GPU.
+
+    The cache keeps weights resident across requests so only the first call per
+    model pays the load cost. ZeroGPU exposes CUDA inside the ``@spaces.GPU``
+    context, which is where this runs.
+    """
+
+    cached = _MODEL_CACHE.get(model_id)
+    if cached is not None:
+        return cached
+
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+    model = AutoModelForCausalLM.from_pretrained(
+        model_id,
+        torch_dtype=torch.bfloat16,
+        device_map="cuda",
+        trust_remote_code=True,
+    )
+    model.eval()
+    _MODEL_CACHE[model_id] = (tokenizer, model)
+    return tokenizer, model
+
+
 def build_model_prompt(result: AnalysisResult, narrative_text: str) -> str:
     deterministic_json = json.dumps(result.to_dict(), ensure_ascii=False, indent=2)
     narrative_excerpt = narrative_text[:12000]
@@ -132,21 +174,8 @@ Redacted narrative excerpt:
 """
 
 
-def extract_chat_content(response: Any) -> str:
-    try:
-        content = response.choices[0].message.content
-    except (AttributeError, IndexError, TypeError) as exc:
-        raise ValueError("Model response did not contain chat completion content.") from exc
-    if not isinstance(content, str) or not content.strip():
-        raise ValueError("Model response content was empty.")
-    return content
-
-
 def parse_model_json(content: str) -> dict[str, Any]:
-    try:
-        parsed = json.loads(content)
-    except json.JSONDecodeError as exc:
-        raise ValueError("Model response was not valid JSON.") from exc
+    parsed = _loads_lenient(content)
 
     required = {
         "executive_memo": str,
@@ -159,3 +188,30 @@ def parse_model_json(content: str) -> dict[str, Any]:
             raise ValueError(f"Model response missing {key!r} as {expected_type.__name__}.")
     parsed["caveats"] = [str(item) for item in parsed["caveats"][:6]]
     return parsed
+
+
+def _loads_lenient(content: str) -> dict[str, Any]:
+    """Parse JSON from a model that may wrap it in prose or code fences."""
+
+    if not isinstance(content, str) or not content.strip():
+        raise ValueError("Model response content was empty.")
+
+    text = content.strip()
+    fence = re.match(r"^```[a-zA-Z0-9]*\s*(.*?)\s*```$", text, re.DOTALL)
+    if fence:
+        text = fence.group(1).strip()
+
+    try:
+        parsed: Any = json.loads(text)
+    except json.JSONDecodeError:
+        start, end = text.find("{"), text.rfind("}")
+        if start == -1 or end == -1 or end <= start:
+            raise ValueError("Model response was not valid JSON.")
+        try:
+            parsed = json.loads(text[start : end + 1])
+        except json.JSONDecodeError as exc:
+            raise ValueError("Model response was not valid JSON.") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError("Model response was not a JSON object.")
+    return parsed

requirements.txt

@@ -1,3 +1,7 @@
-gradio[oauth]>=5.50,<6.0
+gradio>=6.16,<7
 huggingface_hub>=0.30
 spaces>=0.50
+torch>=2.4
+transformers>=4.57
+accelerate>=1.0
+einops>=0.8

tests/test_model_runtime.py

@@ -10,24 +10,25 @@ from analyzer import analyze_trace_file
 from model_runtime import MODEL_CHOICES, PRIMARY_MODEL_ID, parse_model_json, run_model_assist
 
 
-class FakeChatClient:
-    def chat_completion(self, *args, **kwargs):
-        self.kwargs = kwargs
-        content = json.dumps(
-            {
-                "executive_memo": "The trace shows a visible upload-boundary correction.",
-                "detour_memo": "E01 narrows scope instead of changing the parser.",
-                "outcome_audit_memo": "The agent keeps a deployment caveat visible.",
-                "caveats": ["Model memo is based only on redacted narrative."],
-            }
-        )
-        return types.SimpleNamespace(
-            choices=[
-                types.SimpleNamespace(
-                    message=types.SimpleNamespace(content=content),
-                )
-            ]
+MEMO_JSON = {
+    "executive_memo": "The trace shows a visible upload-boundary correction.",
+    "detour_memo": "E01 narrows scope instead of changing the parser.",
+    "outcome_audit_memo": "The agent keeps a deployment caveat visible.",
+    "caveats": ["Model memo is based only on redacted narrative."],
+}
+
+
+class RecordingGenerator:
+    """Stand-in for the local GPU generator that records its call arguments."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+
+    def __call__(self, messages, *, model_id, max_new_tokens) -> str:
+        self.calls.append(
+            {"messages": messages, "model_id": model_id, "max_new_tokens": max_new_tokens}
         )
+        return json.dumps(MEMO_JSON)
 
 
 class ModelRuntimeTests(unittest.TestCase):
@@ -38,34 +39,36 @@ class ModelRuntimeTests(unittest.TestCase):
         self.assertNotIn("small", label.lower())
 
     def test_parse_model_json_validates_required_shape(self) -> None:
-        memo = parse_model_json(
-            json.dumps(
-                {
-                    "executive_memo": "summary",
-                    "detour_memo": "detour",
-                    "outcome_audit_memo": "audit",
-                    "caveats": ["one"],
-                }
-            )
-        )
+        memo = parse_model_json(json.dumps(MEMO_JSON))
+
+        self.assertEqual(memo["executive_memo"], MEMO_JSON["executive_memo"])
+        self.assertEqual(memo["caveats"], MEMO_JSON["caveats"])
+
+    def test_parse_model_json_recovers_from_code_fence(self) -> None:
+        memo = parse_model_json("```json\n" + json.dumps(MEMO_JSON) + "\n```")
+
+        self.assertEqual(memo["detour_memo"], MEMO_JSON["detour_memo"])
+
+    def test_parse_model_json_extracts_object_from_prose(self) -> None:
+        raw = "Here is the analysis:\n" + json.dumps(MEMO_JSON) + "\nHope this helps."
+        memo = parse_model_json(raw)
 
-        self.assertEqual(memo["executive_memo"], "summary")
-        self.assertEqual(memo["caveats"], ["one"])
+        self.assertEqual(memo["outcome_audit_memo"], MEMO_JSON["outcome_audit_memo"])
 
     def test_run_model_assist_uses_selected_model(self) -> None:
         result, narrative = analyze_trace_file(Path("examples/sample_trace_redacted.jsonl"))
-        client = FakeChatClient()
+        generate = RecordingGenerator()
 
         assist = run_model_assist(
             engine="nemotron",
             result=result,
             narrative_text=narrative,
-            client=client,
+            generate=generate,
         )
 
         self.assertEqual(assist.model_id, PRIMARY_MODEL_ID)
         self.assertIn("upload-boundary", assist.memo["executive_memo"])
-        self.assertEqual(client.kwargs["model"], PRIMARY_MODEL_ID)
+        self.assertEqual(generate.calls[0]["model_id"], PRIMARY_MODEL_ID)
 
     def test_analyzer_records_unknown_engine_note(self) -> None:
         result, _ = analyze_trace_file(
@@ -77,7 +80,7 @@ class ModelRuntimeTests(unittest.TestCase):
         self.assertIn("Unknown analysis engine", result.model_notes[0])
 
     def test_analyzer_model_error_note_avoids_double_period(self) -> None:
-        with patch("analyzer.run_model_assist", side_effect=ValueError("needs login.")):
+        with patch("analyzer.run_model_assist", side_effect=ValueError("model unavailable.")):
             result, _ = analyze_trace_file(
                 Path("examples/sample_trace_redacted.jsonl"),
                 analysis_engine="qwen",
@@ -85,28 +88,22 @@ class ModelRuntimeTests(unittest.TestCase):
 
         self.assertTrue(result.model_notes)
         self.assertNotIn("..", result.model_notes[0])
-        self.assertIn("ValueError: needs login.", result.model_notes[0])
+        self.assertIn("ValueError: model unavailable.", result.model_notes[0])
 
-    def test_analyzer_passes_hf_token_to_model_assist(self) -> None:
+    def test_analyzer_records_model_engine_on_success(self) -> None:
         with patch("analyzer.run_model_assist") as run_model_assist:
             run_model_assist.return_value = types.SimpleNamespace(
                 model_id=PRIMARY_MODEL_ID,
-                memo={
-                    "executive_memo": "memo",
-                    "detour_memo": "detour",
-                    "outcome_audit_memo": "audit",
-                    "caveats": [],
-                },
+                memo=dict(MEMO_JSON),
                 note="ok",
             )
             result, _ = analyze_trace_file(
                 Path("examples/sample_trace_redacted.jsonl"),
                 analysis_engine="nemotron",
-                hf_token="hf_test_token",
             )
 
         self.assertIn(PRIMARY_MODEL_ID, result.engine)
-        self.assertEqual(run_model_assist.call_args.kwargs["token"], "hf_test_token")
+        self.assertNotIn("token", run_model_assist.call_args.kwargs)
 
 
 if __name__ == "__main__":

view_model.py

@@ -0,0 +1,170 @@
+"""Adapt an :class:`AnalysisResult` into the JSON shape the React frontend expects.
+
+The designer's prototype renders from a richer object than the analyzer produces:
+it also wants a top-level ``verdict`` (a whole-session read), a ``captured``
+window, and a ``duration_total``. Those are synthesized here from the
+deterministic episodes (and the model memo, when present) so the frontend stays
+a pure view layer.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from analyzer import duration_label, parse_timestamp
+from report_renderer import render_report
+from schemas import AnalysisResult
+
+
+# recovery_pattern -> tone bucket (mirrors the frontend's TONE_OF in data.js)
+TONE_OF = {
+    "smooth_recovery": "stable",
+    "reflective_recovery": "stable",
+    "iterative_recovery": "iterative",
+    "detour_recovery": "detour",
+    "partial_recovery": "partial",
+    "failed_recovery": "risk",
+    "avoidant_recovery": "risk",
+    "overconfident_recovery": "risk",
+    "unknown": "unknown",
+}
+
+_SEVERITY = {"risk": 5, "partial": 4, "iterative": 3, "detour": 2, "stable": 1, "unknown": 0}
+
+_CANDID_CLAIMS = {
+    "resolved_with_caveat",
+    "not_resolved",
+    "needs_verification",
+    "partially_resolved",
+    "uncertain_but_proceeding",
+}
+
+_HEADLINE_BY_TONE = {
+    "stable": "A clean run with an honest close-out.",
+    "detour": "Left the planned path and found a better line.",
+    "iterative": "Closed in on it through repeated attempts.",
+    "partial": "Part of the way there, with caveats left standing.",
+    "risk": "Hit hazard terrain and didn't clearly recover.",
+    "unknown": "A short session with little difficulty signal.",
+}
+
+
+def build_view_model(
+    result: AnalysisResult,
+    narrative_text: str,
+    *,
+    include_exports: bool = True,
+) -> dict[str, Any]:
+    """Return the frontend-ready dict for one analysis."""
+
+    base = result.to_dict()
+    episodes = [_clean_episode(ep) for ep in base["episodes"]]
+
+    view: dict[str, Any] = {
+        "trace_title": base["trace_title"],
+        "agent_type_guess": base["agent_type_guess"],
+        "analysis_scope": base["analysis_scope"],
+        "engine": base["engine"],
+        "captured": _captured(episodes),
+        "narrative_message_count": base["narrative_message_count"],
+        "redaction_count": base["redaction_count"],
+        "duration_total": _duration_total(episodes),
+        "verdict": _verdict(episodes, base["overall_patterns"], result.model_memo),
+        "overall_patterns": base["overall_patterns"],
+        "privacy_notes": list(base["privacy_notes"]) + list(base.get("model_notes") or []),
+        "episodes": episodes,
+    }
+    if result.model_memo:
+        view["model_memo"] = result.model_memo
+    if include_exports:
+        view["exports"] = {
+            "narrative_md": narrative_text,
+            "report_md": render_report(result),
+            "episodes_json": json.dumps(base, indent=2, ensure_ascii=False) + "\n",
+        }
+    return view
+
+
+def _clean_episode(ep: dict[str, Any]) -> dict[str, Any]:
+    ep = dict(ep)
+    span = dict(ep.get("message_span") or {})
+    span["start_time"] = span.get("start_time") or ""
+    span["end_time"] = span.get("end_time") or ""
+    span["duration_label"] = span.get("duration_label") or "unknown"
+    ep["message_span"] = span
+    ep["evidence_quotes"] = list(ep.get("evidence_quotes") or [])
+    return ep
+
+
+def _session_tone(episodes: list[dict[str, Any]]) -> str:
+    tones = [TONE_OF.get(ep["recovery_pattern"], "unknown") for ep in episodes]
+    if not tones:
+        return "unknown"
+    return max(tones, key=lambda t: _SEVERITY[t])
+
+
+def _honesty(episodes: list[dict[str, Any]]) -> str:
+    claims = [ep["outcome_claim"] for ep in episodes]
+    if any(c == "premature_success_claim" for c in claims):
+        return "overclaimed"
+    if any(c in _CANDID_CLAIMS for c in claims):
+        return "candid"
+    return "mixed"
+
+
+def _verdict(
+    episodes: list[dict[str, Any]],
+    patterns: dict[str, str],
+    model_memo: dict[str, Any] | None,
+) -> dict[str, str]:
+    n = len(episodes)
+    if not n:
+        return {
+            "tone": "unknown",
+            "headline": "No explicit difficulty episode surfaced.",
+            "detail": "The visible narrative did not carry clear blockage, detour, or recovery language.",
+            "honesty": "mixed",
+        }
+    tone = _session_tone(episodes)
+    honesty = _honesty(episodes)
+    headline = (
+        "Real progress, but the final claim outruns the evidence."
+        if honesty == "overclaimed"
+        else _HEADLINE_BY_TONE.get(tone, "A session across mixed terrain.")
+    )
+    memo_detail = (model_memo or {}).get("executive_memo") if model_memo else None
+    if memo_detail:
+        detail = str(memo_detail)
+    else:
+        plural = "s" if n != 1 else ""
+        parts = [f"{n} difficulty episode{plural}."]
+        if patterns.get("recovery_style"):
+            parts.append(patterns["recovery_style"])
+        if patterns.get("risk_or_caveat"):
+            parts.append(patterns["risk_or_caveat"])
+        detail = " ".join(parts)
+    return {"tone": tone, "headline": headline, "detail": detail, "honesty": honesty}
+
+
+def _captured(episodes: list[dict[str, Any]]) -> str:
+    if not episodes:
+        return "—"
+    start = episodes[0]["message_span"].get("start_time") or ""
+    end = episodes[-1]["message_span"].get("end_time") or ""
+    if start and end:
+        return f"{start} – {end}"
+    return start or end or "—"
+
+
+def _duration_total(episodes: list[dict[str, Any]]) -> str:
+    if not episodes:
+        return "—"
+    start = episodes[0]["message_span"].get("start_time")
+    end = episodes[-1]["message_span"].get("end_time")
+    if start and end:
+        label = duration_label(start, end)
+        if label != "unknown":
+            return label
+    # fall back to summing per-episode labels is lossy; show the span count instead
+    return episodes[-1]["message_span"].get("duration_label") or "—"