feat: export almanac chapters

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

README.md

@@ -69,6 +69,12 @@ The `field_notes` Gradio API endpoint and `Notes` button export a Markdown build
 builder profile, target badges, idea board, cited Spaces, latest build plan, planner calls, and the share caption. This
 keeps the Field Notes badge path tied to auditable app evidence instead of a separate hand-written summary.
 
+## Chapter Artifact
+
+The `chapter` Gradio API endpoint and `Chapter` button export the public-facing idea board as an Almanac chapter:
+one fate page per idea, each with verdict, score, targets, and closest cited pages. It is the shareable companion to
+the private Field Notes artifact.
+
 ## Wood Map
 
 Every scored fate page now carries a deterministic `wood_map` artifact: background dots for inked Spaces, red dots for

app.py

@@ -9,6 +9,7 @@ from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 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.field_notes import build_field_notes_markdown
 from hackathon_advisor.tool_contracts import resolve_tool_call, tool_schemas
@@ -110,6 +111,21 @@ def field_notes_artifact(session_json: str = "{}") -> str:
     )
 
 
+@app.api(name="chapter", concurrency_limit=8)
+def chapter_artifact(session_json: str = "{}") -> str:
+    try:
+        session = json.loads(session_json or "{}")
+    except json.JSONDecodeError:
+        session = {}
+    return build_chapter_markdown(
+        session,
+        {
+            **trace_metadata(index),
+            "project_count": len(index.projects),
+        },
+    )
+
+
 @app.api(name="agent_turn", concurrency_limit=4, stream_every=0.04)
 def agent_turn(message: str, session_json: str = "{}") -> Iterator[str]:
     try:

hackathon_advisor/chapter.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def build_chapter_markdown(session: dict[str, Any], metadata: dict[str, Any]) -> str:
+    ideas = _list_of_dicts(session.get("ideas"))
+    targets = [str(target) for target in session.get("targets") or []]
+    artifact = session.get("last_artifact") if isinstance(session.get("last_artifact"), dict) else {}
+    lines = [
+        "# The Unwritten Almanac Chapter",
+        "",
+        f"Generated: {datetime.now(timezone.utc).isoformat(timespec='seconds')}",
+        f"Snapshot: {_clean(metadata.get('snapshot_generated_at'))} · {_clean(metadata.get('project_count'))} pages",
+        f"Targets: {', '.join(targets) if targets else 'No specific targets'}",
+        "",
+    ]
+
+    if not ideas:
+        lines.extend(["No fate pages have been written yet.", ""])
+        return "\n".join(lines)
+
+    for index, idea in enumerate(ideas, start=1):
+        lines.extend(_idea_page(index, idea))
+
+    caption = _clean(artifact.get("caption")) if artifact else ""
+    if caption:
+        lines.extend(["## Share Caption", "", caption, ""])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _idea_page(index: int, idea: dict[str, Any]) -> list[str]:
+    title = _clean(idea.get("title") or f"Page {index}")
+    pitch = _clean(idea.get("pitch"))
+    targets = [str(target) for target in idea.get("targets") or []]
+    score = idea.get("score") if isinstance(idea.get("score"), dict) else {}
+    verdict = _clean(score.get("verdict")) if score else "DRAFT"
+    overall = _clean(score.get("overall")) if score else "0.0"
+    lines = [
+        f"## Page {index}: {title}",
+        "",
+        f"Verdict: {verdict} · {overall}/10",
+        f"Targets: {', '.join(targets) if targets else 'No specific targets'}",
+        "",
+        pitch or "No prophecy text recorded.",
+        "",
+    ]
+    echoes = _list_of_dicts(score.get("echoes")) if score else []
+    if echoes:
+        lines.extend(["Closest inked pages:", ""])
+        for echo in echoes[:3]:
+            project = echo.get("project") if isinstance(echo.get("project"), dict) else {}
+            page = _clean(echo.get("page_number")) or "?"
+            project_title = _clean(project.get("title") or project.get("id") or "Untitled")
+            url = _clean(project.get("url") or project.get("host") or "")
+            score_text = _clean(echo.get("score"))
+            if url:
+                lines.append(f"- Page {page}: [{project_title}]({url}) · echo {score_text}")
+            else:
+                lines.append(f"- Page {page}: {project_title} · echo {score_text}")
+        lines.append("")
+    return lines
+
+
+def _list_of_dicts(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]
+
+
+def _clean(value: Any) -> str:
+    if value is None:
+        return ""
+    return " ".join(str(value).split())

hackathon_advisor/tools.py

@@ -89,7 +89,7 @@ class AdvisorTools:
         current_id = state.get("current_idea_id")
         targets = targets_from_state(state)
         idea = next((item for item in ideas if item.id == current_id), None)
-        if idea is None:
+        if idea is None or _is_new_idea(idea, title, pitch):
             idea = Idea(id=uuid.uuid4().hex[:8], title=title, pitch=pitch, targets=targets)
             ideas.append(idea)
         else:
@@ -133,6 +133,10 @@ def idea_from_text(text: str) -> tuple[str, str]:
     return _display_title(title), cleaned
 
 
+def _is_new_idea(current: Idea, title: str, pitch: str) -> bool:
+    return current.title.strip().casefold() != title.strip().casefold() or current.pitch.strip() != pitch.strip()
+
+
 def _display_title(title: str) -> str:
     if not title:
         return "Unwritten Page"

static/app.js

@@ -20,6 +20,7 @@ const overallEl = document.querySelector("#overall");
 const exportButton = document.querySelector("#export-artifact");
 const exportTraceButton = document.querySelector("#export-trace");
 const exportNotesButton = document.querySelector("#export-notes");
+const exportChapterButton = document.querySelector("#export-chapter");
 const resetButton = document.querySelector("#reset-session");
 
 const SESSION_STORAGE_KEY = "hackathon-advisor-session-v1";
@@ -60,6 +61,10 @@ exportNotesButton.addEventListener("click", async () => {
   await exportNotes();
 });
 
+exportChapterButton.addEventListener("click", async () => {
+  await exportChapter();
+});
+
 resetButton.addEventListener("click", () => {
   clearSavedSession();
   window.location.reload();
@@ -175,6 +180,7 @@ function renderRestoredSession(data) {
   renderTrace(session.trace || []);
   exportTraceButton.disabled = !(session.trace?.length);
   exportNotesButton.disabled = !(session.trace?.length);
+  exportChapterButton.disabled = !(session.ideas?.length);
 }
 
 function readSavedSession() {
@@ -310,6 +316,7 @@ function handleEvent(event) {
     }
     exportTraceButton.disabled = !(session.trace?.length);
     exportNotesButton.disabled = !(session.trace?.length);
+    exportChapterButton.disabled = !(session.ideas?.length);
     saveSession();
   }
 }
@@ -484,11 +491,13 @@ function setCommandDisabled(disabled) {
     const isArtifact = button.id === "export-artifact";
     const isTrace = button.id === "export-trace";
     const isNotes = button.id === "export-notes";
+    const isChapter = button.id === "export-chapter";
     button.disabled =
       disabled ||
       (isArtifact && !currentArtifact) ||
       (isTrace && !session.trace?.length) ||
-      (isNotes && !session.trace?.length);
+      (isNotes && !session.trace?.length) ||
+      (isChapter && !session.ideas?.length);
   });
 }
 
@@ -543,6 +552,15 @@ async function exportNotes() {
   downloadText("hackathon-advisor-field-notes.md", String(data || ""), "text/markdown;charset=utf-8");
 }
 
+async function exportChapter() {
+  const client = await clientPromise;
+  const result = await client.predict("/chapter", {
+    session_json: JSON.stringify(session),
+  });
+  const data = Array.isArray(result.data) ? result.data[0] : result.data;
+  downloadText("hackathon-advisor-chapter.md", String(data || ""), "text/markdown;charset=utf-8");
+}
+
 function exportArtifact(artifact) {
   const canvas = document.createElement("canvas");
   canvas.width = 1200;

static/index.html

@@ -34,6 +34,7 @@
               <button type="button" data-command="compare ideas" title="Compare the idea board">Rank</button>
               <button type="button" id="export-trace" title="Export the tool trace" disabled>JSONL</button>
               <button type="button" id="export-notes" title="Export Field Notes" disabled>Notes</button>
+              <button type="button" id="export-chapter" title="Export the Almanac chapter" disabled>Chapter</button>
               <button type="button" id="export-artifact" title="Export the current fate page" disabled>PNG</button>
               <button type="button" id="reset-session" title="Clear the saved session">Reset</button>
             </div>

static/styles.css

@@ -184,7 +184,7 @@ button:disabled {
 
 .command-row {
   display: grid;
-  grid-template-columns: repeat(7, minmax(0, 1fr));
+  grid-template-columns: repeat(4, minmax(0, 1fr));
   gap: 8px;
   margin-top: 10px;
 }
@@ -527,7 +527,7 @@ button:disabled {
   }
 
   .command-row {
-    grid-template-columns: repeat(4, minmax(0, 1fr));
+    grid-template-columns: repeat(3, minmax(0, 1fr));
   }
 
   .score-row {

tests/test_agent.py

@@ -70,6 +70,18 @@ def test_plan_command_uses_current_idea() -> None:
     assert planned.state["ideas"][0]["title"] == first.artifact["title"]
 
 
+def test_distinct_idea_turns_append_to_board() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+
+    first = engine.turn("A local-first archive cartographer for family photos", {})
+    second = engine.turn("write bolder and find whitespace", first.state)
+
+    assert len(second.state["ideas"]) == 2
+    assert second.state["ideas"][0]["title"] == first.artifact["title"]
+    assert second.state["ideas"][1]["title"] == second.artifact["title"]
+
+
 def test_plan_preserves_unwritten_whitespace_verdict() -> None:
     index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
     engine = AdvisorEngine(index)

tests/test_app.py

@@ -2,6 +2,7 @@ import json
 
 from app import (
     bootstrap,
+    chapter_artifact,
     engine,
     field_notes_artifact,
     health,
@@ -61,6 +62,18 @@ def test_field_notes_endpoint_exports_markdown() -> None:
     assert "Record the trace and write Field Notes" in payload
 
 
+def test_chapter_endpoint_exports_markdown() -> None:
+    state = engine.turn("A local-first archive cartographer for family photos", {}).state
+    state = engine.turn("write bolder and find whitespace", state).state
+
+    payload = chapter_artifact(json.dumps(state))
+
+    assert payload.startswith("# The Unwritten Almanac Chapter")
+    assert "## Page 1:" in payload
+    assert "## Page 2:" in payload
+    assert "Closest inked pages:" in payload
+
+
 def test_tool_contracts_endpoint_exposes_schemas() -> None:
     payload = tool_contracts()
 

tests/test_chapter.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+from hackathon_advisor.agent import AdvisorEngine
+from hackathon_advisor.chapter import build_chapter_markdown
+from hackathon_advisor.data import ProjectIndex
+from hackathon_advisor.trace_export import trace_metadata
+
+
+def test_chapter_markdown_contains_idea_pages_and_citations() -> None:
+    index = ProjectIndex.from_files(Path("data/projects.json"), Path("data/project_index.json"))
+    engine = AdvisorEngine(index)
+    state = engine.turn("A local-first archive cartographer for family photos", {}).state
+    state = engine.turn("write bolder and find whitespace", state).state
+
+    markdown = build_chapter_markdown(
+        state,
+        {
+            **trace_metadata(index),
+            "project_count": len(index.projects),
+        },
+    )
+
+    assert markdown.startswith("# The Unwritten Almanac Chapter")
+    assert "## Page 1:" in markdown
+    assert "## Page 2:" in markdown
+    assert "Targets:" in markdown
+    assert "Closest inked pages:" in markdown
+    assert "Page 30:" in markdown
+
+
+def test_empty_chapter_markdown_is_explicit() -> None:
+    markdown = build_chapter_markdown(
+        {},
+        {
+            "snapshot_generated_at": "2026-06-06T00:00:00+00:00",
+            "project_count": 100,
+        },
+    )
+
+    assert "No fate pages have been written yet." in markdown