Add judge demo script endpoint

Co-authored-by: Codex <codex@openai.com>

FIELD_NOTES.md

@@ -28,6 +28,8 @@ The app exposes the same budget through `/api/model-budget`, including numeric `
 
 Runtime setup is also data-backed. `/api/runtime-setup` lists the app command, llama.cpp launch command, model-specific runtime paths, environment values, and fallbacks. The session panel renders a compact version so the demo can distinguish real model wiring from deterministic safety nets.
 
+The judge runbook lives at `/api/demo-script`. It keeps the live presentation repeatable by pairing visible actions with API checks for health, model budget, runtime setup, runtime status, image descriptions, reader narration, and speech.
+
 ## Reader Mode Behavior
 
 The frontend creates a reading queue from semantic nodes: headings, paragraphs, quotes, figures, captions, and controls. It speaks one item at a time, keeps keyboard focus synchronized with the active node, and exposes the current narration through an `aria-live` region.

README.md

@@ -50,7 +50,7 @@ Start the app:
 python app.py
 ```
 
-Open the local URL printed by Gradio. The custom frontend calls `/api/reader-brain`, `/api/image-descriptions`, `/api/describe-image`, `/api/speak`, `/api/generate-image`, `/api/model-budget`, and `/api/runtime-setup`.
+Open the local URL printed by Gradio. The custom frontend calls `/api/reader-brain`, `/api/image-descriptions`, `/api/describe-image`, `/api/speak`, `/api/generate-image`, `/api/model-budget`, `/api/runtime-setup`, and `/api/demo-script`.
 
 Useful environment variables:
 
@@ -73,6 +73,8 @@ The verifier checks syntax, static assets, deterministic fallback model paths, a
 
 `/api/runtime-setup` exposes the commands, environment values, and fallback paths used for the model stack so the demo can be reproduced from the same data the UI displays.
 
+`/api/demo-script` exposes a compact judge runbook with the visible actions and API checks that prove the submission claims.
+
 ## Screen Reader Mode
 
 The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:

app.py

@@ -201,6 +201,50 @@ def runtime_setup_core() -> dict[str, Any]:
     }
 
 
+def demo_script_core() -> dict[str, Any]:
+    return {
+        "ok": True,
+        "title": "Tiny Narrator judge demo",
+        "goal": "Show a custom article app becoming a small-model screen reader with inspectable evidence.",
+        "estimated_minutes": 3,
+        "actions": [
+            {
+                "step": 1,
+                "label": "Open the article",
+                "action": "Load the home page and scan the article plus session panel.",
+                "evidence": "Custom HTML/CSS/JS interface served by Gradio Server.",
+            },
+            {
+                "step": 2,
+                "label": "Turn on reader mode",
+                "action": "Toggle screen reader mode, then press Space or Next to narrate the first item.",
+                "evidence": "The active article node is focused, outlined, narrated, and logged.",
+            },
+            {
+                "step": 3,
+                "label": "Navigate by meaning",
+                "action": "Use Heading, Image, and Summary controls to jump through semantic article nodes.",
+                "evidence": "The reader uses article structure, image alt text, and section summaries.",
+            },
+            {
+                "step": 4,
+                "label": "Inspect small-model receipts",
+                "action": "Review the checklist, model budget, runtime plan, readiness, latency, and transcript panels.",
+                "evidence": "Tiny Titan, Llama Champion, Off-Brand, and Field Notes evidence is visible.",
+            },
+        ],
+        "api_checks": [
+            {"method": "GET", "path": "/api/health", "expect": "custom Gradio Server app and model manifest"},
+            {"method": "GET", "path": "/api/model-budget", "expect": "all_models_within_limit is true"},
+            {"method": "GET", "path": "/api/runtime-setup", "expect": "llama.cpp, Kokoro, vision, and image paths"},
+            {"method": "GET", "path": "/api/runtime-status", "expect": "online or fallback-ready runtime labels"},
+            {"method": "GET", "path": "/api/image-descriptions", "expect": "three article image descriptions"},
+            {"method": "POST", "path": "/api/reader-brain", "expect": "concise narration or fallback narration"},
+            {"method": "POST", "path": "/api/speak", "expect": "Kokoro audio or audible browser fallback path"},
+        ],
+    }
+
+
 ARTICLE_MANIFEST: dict[str, Any] = {
     "title": "A tiny model reader that turns articles into guided narration",
     "reader_controls": [
@@ -218,6 +262,7 @@ ARTICLE_MANIFEST: dict[str, Any] = {
     "models": MODEL_MANIFEST,
     "model_budget": model_budget_core(),
     "runtime_setup": runtime_setup_core(),
+    "demo_script": demo_script_core(),
     "reader_settings": READER_SETTINGS,
     "award_evidence": AWARD_EVIDENCE,
 }
@@ -538,6 +583,11 @@ async def runtime_setup() -> JSONResponse:
     return _json(runtime_setup_core())
 
 
+@app.get("/api/demo-script")
+async def demo_script() -> JSONResponse:
+    return _json(demo_script_core())
+
+
 @app.get("/api/runtime-status")
 async def runtime_status() -> JSONResponse:
     return _json(_runtime_status_core())
@@ -593,6 +643,11 @@ def runtime_setup_api() -> str:
     return json.dumps(runtime_setup_core())
 
 
+@app.api(name="demo_script")
+def demo_script_api() -> str:
+    return json.dumps(demo_script_core())
+
+
 @app.api(name="speak")
 def speak_api(text: str, voice: str = "af_heart", speed: float = 1.0) -> str:
     return json.dumps(speak_core(text, voice, speed))

scripts/verify.py

@@ -149,6 +149,10 @@ def verify_routes() -> None:
         len(manifest_payload["runtime_setup"]["steps"]) == 4,
         "Manifest should expose setup steps for each model role",
     )
+    assert_true(
+        len(manifest_payload["demo_script"]["actions"]) >= 4,
+        "Manifest should expose a judge demo script",
+    )
 
     awards = client.get("/api/award-evidence")
     assert_true(awards.status_code == 200, "Award evidence route should return 200")
@@ -184,6 +188,23 @@ def verify_routes() -> None:
         "Runtime setup should include the llama.cpp launch command",
     )
 
+    demo = client.get("/api/demo-script")
+    assert_true(demo.status_code == 200, "Demo script route should return 200")
+    demo_payload = demo.json()
+    assert_true(demo_payload["ok"], "Demo script payload should be ok")
+    assert_true(
+        "Tiny Narrator judge demo" == demo_payload["title"],
+        "Demo script should be labeled for judging",
+    )
+    assert_true(
+        {item["path"] for item in demo_payload["api_checks"]} >= {"/api/model-budget", "/api/runtime-setup"},
+        "Demo script should include evidence API checks",
+    )
+    assert_true(
+        any("Tiny Titan" in action["evidence"] for action in demo_payload["actions"]),
+        "Demo script should point to targeted award evidence",
+    )
+
     runtime = client.get("/api/runtime-status")
     assert_true(runtime.status_code == 200, "Runtime status route should return 200")
     runtime_payload = runtime.json()