feat: add demo rehearsal session

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

README.md

@@ -89,6 +89,13 @@ session: live links, snapshot provenance, a timed demo script, artifact checklis
 session trace summary, social post draft, and open badge gaps. This keeps the final submission story tied to the same
 auditable state as the app instead of a separate hand-curated checklist.
 
+## Demo Rehearsal
+
+`/api/demo-session` and the `Demo` button load a deterministic two-turn rehearsal: a complete project idea, profile,
+target badges, score seal, build plan, trace, wood map, and export-ready artifacts. It is built by running the same
+advisor engine as a normal user session, so the demo state can be used immediately with JSONL, Notes, Chapter, LoRA,
+Packet, and PNG exports.
+
 ## Prize Ledger
 
 `/api/prize-ledger` and the in-app Prize Ledger panel expose submission evidence: the documented model stack, total

app.py

@@ -11,6 +11,7 @@ from gradio import Server
 from hackathon_advisor.agent import AdvisorEngine
 from hackathon_advisor.chapter import build_chapter_markdown
 from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.demo_rehearsal import build_demo_rehearsal
 from hackathon_advisor.field_notes import build_field_notes_markdown
 from hackathon_advisor.lora_dataset import build_lora_dataset_jsonl
 from hackathon_advisor.prize_ledger import prize_ledger
@@ -92,6 +93,11 @@ def tool_contracts() -> dict:
     }
 
 
+@app.get("/api/demo-session")
+def demo_session() -> dict:
+    return build_demo_rehearsal(engine)
+
+
 @app.api(name="tool_contract_check", concurrency_limit=8)
 def tool_contract_check(model_output: str, fallback_query: str = "") -> dict:
     return resolve_tool_call(model_output, fallback_query=fallback_query).to_dict()

hackathon_advisor/demo_rehearsal.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+DEMO_PROMPT = (
+    "A local-first archive cartographer for family photos that runs offline, cites nearby Spaces, "
+    "and exports Field Notes."
+)
+DEMO_PLAN_PROMPT = "make a build plan"
+DEMO_PROFILE = {
+    "skills": "frontend prototyping, Python, small-model evaluation",
+    "time": "one focused weekend",
+    "preferences": "auditable artifacts, local-first runtime, strong demo beat",
+    "constraints": "CPU Space runtime; no proprietary inference API",
+}
+DEMO_TARGETS = [
+    "Off the Grid",
+    "Well-Tuned",
+    "Off-Brand",
+    "Sharing is Caring",
+    "Field Notes",
+]
+
+
+def build_demo_rehearsal(engine: Any) -> dict[str, Any]:
+    initial_state = {
+        "profile": dict(DEMO_PROFILE),
+        "targets": list(DEMO_TARGETS),
+    }
+    first = engine.turn(DEMO_PROMPT, initial_state)
+    second = engine.turn(DEMO_PLAN_PROMPT, first.state)
+    score = second.score or first.score
+    artifact = second.artifact or first.artifact
+    projects = first.projects or second.projects
+    whitespace = first.whitespace or second.whitespace
+    session = second.state
+    return {
+        "prompt": DEMO_PROMPT,
+        "plan_prompt": DEMO_PLAN_PROMPT,
+        "response": second.response,
+        "session": session,
+        "score": score.to_dict() if score else None,
+        "plan": list(second.plan),
+        "artifact": artifact,
+        "projects": [project.to_public_dict() for project in projects],
+        "whitespace": [item.to_dict() for item in whitespace],
+        "turn_count": len(session.get("trace") or []),
+        "export_ready": {
+            "trace": bool(session.get("trace")),
+            "notes": bool(session.get("trace")),
+            "chapter": bool(session.get("ideas")),
+            "lora_dataset": bool(session.get("trace")),
+            "submission_packet": bool(session.get("trace")),
+            "png": bool(artifact),
+        },
+    }

static/app.js

@@ -18,6 +18,7 @@ const traceEl = document.querySelector("#trace");
 const provenanceEl = document.querySelector("#provenance");
 const verdictEl = document.querySelector("#verdict");
 const overallEl = document.querySelector("#overall");
+const demoButton = document.querySelector("#load-demo");
 const exportButton = document.querySelector("#export-artifact");
 const exportTraceButton = document.querySelector("#export-trace");
 const exportNotesButton = document.querySelector("#export-notes");
@@ -51,6 +52,10 @@ document.querySelectorAll("[data-command]").forEach((button) => {
   });
 });
 
+demoButton.addEventListener("click", async () => {
+  await loadDemoSession();
+});
+
 exportButton.addEventListener("click", () => {
   if (!currentArtifact) return;
   exportArtifact(currentArtifact);
@@ -161,6 +166,64 @@ async function bootstrap() {
   renderWhitespace(data.whitespace || []);
 }
 
+async function loadDemoSession() {
+  submit.disabled = true;
+  setCommandDisabled(true);
+  ink.classList.remove("bleed", "gold");
+  ink.classList.add("thinking");
+  ink.textContent = "The demo pages are turning.";
+  corrections.textContent = "";
+  try {
+    const response = await fetch("/api/demo-session");
+    if (!response.ok) throw new Error(`demo rehearsal failed with ${response.status}`);
+    applyDemoSession(await response.json());
+  } catch (error) {
+    ink.textContent = `The demo rehearsal could not be loaded: ${error.message}`;
+    ink.classList.remove("thinking");
+    ink.classList.add("bleed");
+  } finally {
+    submit.disabled = false;
+    setCommandDisabled(false);
+    input.focus();
+  }
+}
+
+function applyDemoSession(data) {
+  session = data.session || {};
+  session.profile = session.profile || {};
+  session.targets = Array.isArray(session.targets) ? session.targets : [];
+  currentArtifact = data.artifact || session.last_artifact || null;
+  ink.textContent = data.response || "Demo rehearsal loaded.";
+  ink.classList.remove("thinking");
+  if (data.score) {
+    verdictEl.textContent = data.score.verdict;
+    overallEl.textContent = Number(data.score.overall).toFixed(1);
+    renderScore(data.score);
+    ink.classList.toggle("bleed", data.score.verdict.startsWith("ECHO"));
+    ink.classList.toggle("gold", data.score.verdict.startsWith("UNWRITTEN"));
+  }
+  renderTargets(session.targets);
+  renderProfile(session.profile);
+  renderIdeas(session.ideas || []);
+  renderTrace(session.trace || []);
+  renderPlan(data.plan || session.last_plan || []);
+  renderWhitespace(data.whitespace || []);
+  if (currentArtifact?.wood_map) renderWoodMap(currentArtifact.wood_map);
+  if (data.score?.echoes?.length) {
+    renderCitations(data.score.echoes);
+  } else {
+    renderProjects(data.projects || []);
+  }
+  exportButton.disabled = !currentArtifact;
+  exportTraceButton.disabled = !(session.trace?.length);
+  exportNotesButton.disabled = !(session.trace?.length);
+  exportChapterButton.disabled = !(session.ideas?.length);
+  exportLoraButton.disabled = !(session.trace?.length);
+  exportPacketButton.disabled = !(session.trace?.length);
+  corrections.textContent = `demo: ${data.turn_count || 0} recorded turns`;
+  saveSession();
+}
+
 function renderProvenance(data) {
   const snapshot = shortDate(data.snapshot_generated_at);
   const index = shortDate(data.index_generated_at);

static/index.html

@@ -27,6 +27,7 @@
               <button id="submit" type="submit" title="Ink the page">Ink</button>
             </form>
             <div class="command-row" aria-label="Advisor commands">
+              <button type="button" id="load-demo" title="Load a complete demo session">Demo</button>
               <button type="button" data-command="write bolder and find whitespace" title="Find a gold margin">
                 Gap
               </button>

tests/test_app.py

@@ -3,6 +3,7 @@ import json
 from app import (
     bootstrap,
     chapter_artifact,
+    demo_session,
     engine,
     field_notes_artifact,
     health,
@@ -117,6 +118,17 @@ def test_tool_contracts_endpoint_exposes_schemas() -> None:
     assert any(tool["function"]["name"] == "search_projects" for tool in payload["tools"])
 
 
+def test_demo_session_endpoint_returns_export_ready_state() -> None:
+    payload = demo_session()
+
+    assert payload["turn_count"] == 2
+    assert payload["session"]["trace"]
+    assert payload["session"]["ideas"]
+    assert payload["plan"]
+    assert payload["artifact"]["wood_map"]["dots"]
+    assert payload["export_ready"]["submission_packet"] is True
+
+
 def test_tool_contract_check_endpoint_defaults_safely() -> None:
     payload = tool_contract_check("broken", "family archive")
 

tests/test_demo_rehearsal.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.demo_rehearsal import DEMO_TARGETS, build_demo_rehearsal
+
+
+def test_demo_rehearsal_builds_complete_session() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+
+    payload = build_demo_rehearsal(engine)
+    session = payload["session"]
+
+    assert payload["turn_count"] == 2
+    assert payload["score"]["overall"] > 0
+    assert payload["artifact"]["title"]
+    assert payload["artifact"]["wood_map"]["dots"]
+    assert payload["plan"]
+    assert any("LoRA" in step for step in payload["plan"])
+    assert session["targets"] == DEMO_TARGETS
+    assert session["profile"]["constraints"] == "CPU Space runtime; no proprietary inference API"
+    assert len(session["trace"]) == 2
+    assert payload["export_ready"] == {
+        "trace": True,
+        "notes": True,
+        "chapter": True,
+        "lora_dataset": True,
+        "submission_packet": True,
+        "png": True,
+    }