Add submission readiness rollup

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

FIELD_NOTES.md

@@ -30,6 +30,8 @@ Runtime setup is also data-backed. `/api/runtime-setup` lists the app command, l
 
 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.
 
+Submission readiness lives at `/api/submission-readiness`. It aggregates the demo-critical checks into one payload: model budget, award evidence, custom frontend assets, runtime setup, accessibility audit, image receipts, and executable demo API checks.
+
 Image provenance lives in `/api/image-descriptions`. Each article illustration carries the planned FLUX.2 klein model id, prompt, seed, asset URL, and fallback status, and the session panel renders those receipts so the generated-image claim is inspectable.
 
 Accessibility evidence lives at `/api/accessibility-audit`. It records the reader-mode choices that matter most for this prototype: semantic reading order, keyboard navigation, reader cursor state, shortcut safety, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
@@ -77,4 +79,6 @@ Every model-facing backend path reports `elapsed_ms`. The frontend surfaces the
 
 The app exposes `/api/award-evidence` and renders that data in the session panel, so the live demo can point directly to the hackathon bonus targets it is designed to satisfy.
 
+The app also renders `/api/submission-readiness`, so the Field Notes story has a single rollup of which submission claims are currently backed by app evidence.
+
 `/api/runtime-status` keeps the demo honest: if llama.cpp or Kokoro is unavailable, the UI labels the fallback state instead of silently pretending that every model path is online.

README.md

@@ -52,7 +52,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`, `/api/runtime-setup`, `/api/demo-script`, and `/api/accessibility-audit`.
+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`, `/api/demo-script`, `/api/accessibility-audit`, and `/api/submission-readiness`.
 
 Useful environment variables:
 
@@ -81,6 +81,8 @@ The verifier checks syntax, static assets, Space metadata consistency, determini
 
 `/api/image-descriptions` includes image-generation provenance for every article illustration: the planned FLUX.2 klein model, prompt, seed, bundled asset URL, and fallback-ready status.
 
+`/api/submission-readiness` aggregates the judging receipts into one pass/fail payload covering model budget, award evidence, custom frontend assets, runtime setup, accessibility, image receipts, and demo API checks.
+
 ## Screen Reader Mode
 
 The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:
@@ -120,6 +122,8 @@ Reader-brain, image-description, speech, and image-generation responses include
 
 The session panel also renders a manifest-backed demo checklist for Tiny Titan, Llama Champion, Off-Brand, and Field Notes evidence. A model-budget panel reads `/api/model-budget` so judges can see each role's parameter count in the live app.
 
+A submission-readiness panel reads `/api/submission-readiness`, giving judges one compact rollup of the claims the live app can prove.
+
 A runtime-plan panel reads `/api/runtime-setup` and summarizes each model path's runtime plus fallback, keeping the live demo honest about what is online and what is deterministic.
 
 `/api/runtime-status` performs a short readiness check for llama.cpp and local speech dependencies, then reports which fallback paths are ready for a live demo.

SUBMISSION.md

@@ -43,6 +43,7 @@ The prototype is designed for a live hackathon demo: every model-facing path has
 - `/api/accessibility-audit`: semantic queue, keyboard navigation, reader cursor state, shortcut safety, live narration, alt text, transcript, user control, and fallback evidence.
 - `/api/demo-script`: repeatable judge runbook and API checks.
 - `/api/image-descriptions`: generated article image descriptions plus prompt, seed, model, asset URL, and fallback status receipts.
+- `/api/submission-readiness`: one pass/fail rollup for model budget, award evidence, custom frontend, runtime setup, accessibility, image receipts, and demo API checks.
 
 The POST checks in `/api/demo-script` include sample JSON bodies for `/api/reader-brain` and `/api/speak`.
 
@@ -50,6 +51,8 @@ The accessibility audit also documents two reader-mode details that matter durin
 
 The image receipts keep the generated-asset claim inspectable: each article illustration names the planned `black-forest-labs/FLUX.2-klein-4B` path, prompt, seed, and bundled fallback asset.
 
+The submission-readiness panel and API give judges a compact checklist for the whole build, so the live demo can move from individual receipts to an overall readiness view.
+
 ## Reliability notes
 
 The demo remains navigable when local models are unavailable. The reader brain falls back to deterministic narration, image descriptions fall back to cached alt text, speech falls back to browser speech plus transcript, and generated images fall back to bundled article assets. Fallback states are labeled instead of hidden.

app.py

@@ -252,6 +252,7 @@ def demo_script_core() -> dict[str, Any]:
             {"method": "GET", "path": "/api/runtime-status", "expect": "online or fallback-ready runtime labels"},
             {"method": "GET", "path": "/api/accessibility-audit", "expect": "all reader-mode checks pass"},
             {"method": "GET", "path": "/api/image-descriptions", "expect": "three article image descriptions"},
+            {"method": "GET", "path": "/api/submission-readiness", "expect": "all submission readiness checks pass"},
             {
                 "method": "POST",
                 "path": "/api/reader-brain",
@@ -277,6 +278,82 @@ def demo_script_core() -> dict[str, Any]:
     }
 
 
+def submission_readiness_core() -> dict[str, Any]:
+    model_budget = model_budget_core()
+    runtime_setup = runtime_setup_core()
+    accessibility = accessibility_audit_core()
+    demo_script = demo_script_core()
+    image_descriptions = describe_article_images_core()
+    runtime_roles = {step["role"] for step in runtime_setup["steps"]}
+    expected_roles = set(MODEL_MANIFEST)
+    api_paths = {item["path"] for item in demo_script["api_checks"]}
+    checks = [
+        {
+            "id": "tiny_titan_budget",
+            "label": "Tiny Titan model budget",
+            "status": "pass" if model_budget["all_models_within_limit"] else "fail",
+            "evidence": f"{len(model_budget['models'])} model roles are at or below {TINY_TITAN_LIMIT_B}B parameters.",
+        },
+        {
+            "id": "award_targets",
+            "label": "Targeted award evidence",
+            "status": "pass" if len(AWARD_EVIDENCE) == 4 else "fail",
+            "evidence": "Tiny Titan, Llama Champion, Off-Brand, and Field Notes evidence is exposed.",
+        },
+        {
+            "id": "custom_frontend",
+            "label": "Custom frontend",
+            "status": "pass" if all((STATIC_DIR / name).exists() for name in ["index.html", "app.css", "app.js"]) else "fail",
+            "evidence": "The app serves custom HTML, CSS, and JavaScript through Gradio Server.",
+        },
+        {
+            "id": "runtime_setup",
+            "label": "Runtime setup",
+            "status": "pass" if runtime_roles == expected_roles else "fail",
+            "evidence": "Runtime setup covers reader brain, speech, vision, and image generation paths.",
+        },
+        {
+            "id": "reader_accessibility",
+            "label": "Reader accessibility",
+            "status": "pass" if accessibility["all_passed"] else "fail",
+            "evidence": f"{accessibility['passed_checks']} of {accessibility['total_checks']} accessibility checks pass.",
+        },
+        {
+            "id": "image_receipts",
+            "label": "Image receipts",
+            "status": "pass"
+            if all(
+                item.get("generation_model") == MODEL_MANIFEST["image_generation"]["id"] and isinstance(item.get("seed"), int)
+                for item in image_descriptions["descriptions"]
+            )
+            else "fail",
+            "evidence": "Every article illustration exposes prompt, seed, model, asset URL, and fallback status.",
+        },
+        {
+            "id": "demo_api_checks",
+            "label": "Demo API checks",
+            "status": "pass"
+            if {
+                "/api/model-budget",
+                "/api/runtime-setup",
+                "/api/accessibility-audit",
+                "/api/image-descriptions",
+                "/api/reader-brain",
+                "/api/speak",
+            }.issubset(api_paths)
+            else "fail",
+            "evidence": "The judge runbook includes GET evidence checks and executable POST sample bodies.",
+        },
+    ]
+    return {
+        "ok": True,
+        "all_passed": all(check["status"] == "pass" for check in checks),
+        "passed_checks": sum(1 for check in checks if check["status"] == "pass"),
+        "total_checks": len(checks),
+        "checks": checks,
+    }
+
+
 def accessibility_audit_core() -> dict[str, Any]:
     checks = [
         {
@@ -710,6 +787,11 @@ async def accessibility_audit() -> JSONResponse:
     return _json(accessibility_audit_core())
 
 
+@app.get("/api/submission-readiness")
+async def submission_readiness() -> JSONResponse:
+    return _json(submission_readiness_core())
+
+
 @app.get("/api/runtime-status")
 async def runtime_status() -> JSONResponse:
     return _json(_runtime_status_core())
@@ -775,6 +857,11 @@ def accessibility_audit_api() -> str:
     return json.dumps(accessibility_audit_core())
 
 
+@app.api(name="submission_readiness")
+def submission_readiness_api() -> str:
+    return json.dumps(submission_readiness_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

@@ -39,6 +39,7 @@ def verify_static_assets() -> None:
     assert_true('aria-live="polite"' in index_html, "Article should expose an aria-live narration region")
     assert_true("transcriptLog" in index_html, "Article should expose a visible transcript log")
     assert_true("imageReceiptList" in index_html, "Article should expose generated image receipts")
+    assert_true("submissionReadinessList" in index_html, "Article should expose submission readiness checks")
     assert_true("function haltPlayback" in app_js, "Reader controls should expose a shared playback halt helper")
     assert_true(
         "haltPlayback({ clearAutoAdvance: false });" in app_js,
@@ -52,7 +53,13 @@ def verify_static_assets() -> None:
     submission = (ROOT / "SUBMISSION.md").read_text(encoding="utf-8")
     for target in ["Tiny Titan", "Llama Champion", "Off-Brand", "Field Notes"]:
         assert_true(target in submission, f"Submission packet should mention {target}")
-    for endpoint in ["/api/model-budget", "/api/runtime-setup", "/api/accessibility-audit", "/api/demo-script"]:
+    for endpoint in [
+        "/api/model-budget",
+        "/api/runtime-setup",
+        "/api/accessibility-audit",
+        "/api/demo-script",
+        "/api/submission-readiness",
+    ]:
         assert_true(endpoint in submission, f"Submission packet should mention {endpoint}")
     assert_true(
         "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF" in submission,
@@ -194,6 +201,8 @@ def verify_routes() -> None:
     assert_true("autoAdvanceControl" in home.text, "Home route should include auto-advance control")
     assert_true("transcriptLog" in home.text, "Home route should include transcript log")
     assert_true("awardEvidenceList" in home.text, "Home route should include award evidence list")
+    assert_true("submissionReadinessStatus" in home.text, "Home route should include submission readiness status")
+    assert_true("submissionReadinessList" in home.text, "Home route should include submission readiness list")
     assert_true("budgetStatus" in home.text, "Home route should include model budget status")
     assert_true("modelBudgetList" in home.text, "Home route should include model budget list")
     assert_true("runtimeSetupStatus" in home.text, "Home route should include runtime setup status")
@@ -309,6 +318,10 @@ def verify_routes() -> None:
         any(item["path"] == "/api/accessibility-audit" for item in demo_payload["api_checks"]),
         "Demo script should include the accessibility audit check",
     )
+    assert_true(
+        any(item["path"] == "/api/submission-readiness" for item in demo_payload["api_checks"]),
+        "Demo script should include the submission readiness check",
+    )
     reader_check = next(item for item in demo_payload["api_checks"] if item["path"] == "/api/reader-brain")
     speech_check = next(item for item in demo_payload["api_checks"] if item["path"] == "/api/speak")
     assert_true(reader_check["sample_body"]["mode"] == "narrate", "Reader-brain demo check should include a sample body")
@@ -351,6 +364,25 @@ def verify_routes() -> None:
         "Accessibility audit should cover reader semantics, keyboard use, cursor state, shortcut safety, live narration, alt text, and transcript",
     )
 
+    readiness = client.get("/api/submission-readiness")
+    assert_true(readiness.status_code == 200, "Submission readiness route should return 200")
+    readiness_payload = readiness.json()
+    assert_true(readiness_payload["ok"], "Submission readiness payload should be ok")
+    assert_true(readiness_payload["all_passed"], "Submission readiness checks should pass")
+    assert_true(
+        {item["id"] for item in readiness_payload["checks"]}
+        >= {
+            "tiny_titan_budget",
+            "award_targets",
+            "custom_frontend",
+            "runtime_setup",
+            "reader_accessibility",
+            "image_receipts",
+            "demo_api_checks",
+        },
+        "Submission readiness should aggregate model, award, frontend, runtime, accessibility, image, and demo evidence",
+    )
+
     runtime = client.get("/api/runtime-status")
     assert_true(runtime.status_code == 200, "Runtime status route should return 200")
     runtime_payload = runtime.json()

static/app.css

@@ -290,6 +290,14 @@ dd {
   margin-top: 22px;
 }
 
+.submission-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-top: 22px;
+}
+
 .budget-header,
 .image-receipt-header {
   display: flex;
@@ -309,7 +317,8 @@ dd {
 
 .budget-header span,
 .runtime-header span,
-.image-receipt-header span {
+.image-receipt-header span,
+.submission-header span {
   color: var(--accent-strong);
   font-size: 0.76rem;
   font-weight: 850;

static/app.js

@@ -18,6 +18,8 @@ const transcriptLog = document.querySelector("#transcriptLog");
 const copyTranscriptButton = document.querySelector("#copyTranscriptButton");
 const clearTranscriptButton = document.querySelector("#clearTranscriptButton");
 const awardEvidenceList = document.querySelector("#awardEvidenceList");
+const submissionReadinessStatus = document.querySelector("#submissionReadinessStatus");
+const submissionReadinessList = document.querySelector("#submissionReadinessList");
 const budgetStatus = document.querySelector("#budgetStatus");
 const modelBudgetList = document.querySelector("#modelBudgetList");
 const runtimeSetupStatus = document.querySelector("#runtimeSetupStatus");
@@ -224,6 +226,37 @@ async function loadAwardEvidence() {
   }
 }
 
+async function loadSubmissionReadiness() {
+  try {
+    const payload = await postJson("/api/submission-readiness");
+    submissionReadinessStatus.textContent = payload.all_passed
+      ? `${payload.passed_checks}/${payload.total_checks} pass`
+      : "Review needed";
+    submissionReadinessList.innerHTML = payload.checks
+      .map((item) => `
+        <li>
+          <div class="award-title">
+            <span>${escapeHtml(item.label)}</span>
+            <span class="award-status">${escapeHtml(item.status)}</span>
+          </div>
+          <p class="award-evidence">${escapeHtml(item.evidence)}</p>
+        </li>
+      `)
+      .join("");
+  } catch {
+    submissionReadinessStatus.textContent = "Unavailable";
+    submissionReadinessList.innerHTML = `
+      <li>
+        <div class="award-title">
+          <span>Submission readiness</span>
+          <span class="award-status">offline</span>
+        </div>
+        <p class="award-evidence">Submission readiness evidence is unavailable.</p>
+      </li>
+    `;
+  }
+}
+
 function roleLabel(role) {
   return role
     .split("_")
@@ -651,6 +684,7 @@ controls.play.addEventListener("click", () => {
 
 loadManifest();
 loadAwardEvidence();
+loadSubmissionReadiness();
 loadModelBudget();
 loadRuntimeSetup();
 loadRuntimeStatus();

static/index.html

@@ -126,6 +126,11 @@
           <h3>Demo Checklist</h3>
         </div>
         <ul id="awardEvidenceList" class="award-list" aria-label="Hackathon bonus evidence"></ul>
+        <div class="submission-header">
+          <h3>Submission Readiness</h3>
+          <span id="submissionReadinessStatus">Checking</span>
+        </div>
+        <ul id="submissionReadinessList" class="award-list" aria-label="Submission readiness checks"></ul>
         <div class="budget-header">
           <h3>Model Budget</h3>
           <span id="budgetStatus">Checking</span>