feat: add page-number citations

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

hackathon_advisor/agent.py

@@ -398,7 +398,9 @@ class AdvisorEngine:
                 f"{score.verdict} at {score.overall}/10. Push the AI necessity harder: make the model decide, rank, "
                 "or personalize something a static app cannot."
             )
-        citations = "; ".join(f"page {idx + 1}: {project.title}" for idx, project in enumerate(projects[:3]))
+        citations = "; ".join(
+            f"page {hit.page_number}: {hit.project.title}" for hit in score.echoes[:3]
+        )
         return (
             f"The ink bleeds around {idea.title}. Closest echoes: {citations}. The seal reads "
             f"{score.verdict} at {score.overall}/10. Keep the audience, but change the mechanism or artifact so the "

hackathon_advisor/data.py

@@ -87,6 +87,7 @@ class SearchHit:
     project: Project
     score: float
     matched_terms: tuple[str, ...]
+    page_number: int
 
 
 @dataclass(frozen=True)
@@ -218,7 +219,10 @@ class ProjectIndex:
         query_doc = Counter(query_terms)
         query_norm = self._norm(query_doc)
         hits: list[SearchHit] = []
-        for project, doc, doc_norm in zip(self.projects, self._documents, self._norms, strict=True):
+        for page_number, (project, doc, doc_norm) in enumerate(
+            zip(self.projects, self._documents, self._norms, strict=True),
+            start=1,
+        ):
             if doc_norm == 0.0 or query_norm == 0.0:
                 continue
             raw = 0.0
@@ -233,7 +237,14 @@ class ProjectIndex:
             title_bonus = sum(0.08 for term in matched if term in tokenize(project.title))
             tag_bonus = sum(0.05 for term in matched if term in tokenize(" ".join(project.tags)))
             score = raw / (query_norm * doc_norm) + title_bonus + tag_bonus
-            hits.append(SearchHit(project=project, score=score, matched_terms=tuple(sorted(matched))))
+            hits.append(
+                SearchHit(
+                    project=project,
+                    score=score,
+                    matched_terms=tuple(sorted(matched)),
+                    page_number=page_number,
+                )
+            )
         hits.sort(key=lambda hit: (hit.score, hit.project.likes), reverse=True)
         return hits[:limit]
 

hackathon_advisor/field_notes.py

@@ -67,10 +67,11 @@ def build_field_notes_markdown(session: dict[str, Any], metadata: dict[str, Any]
             title = _clean(dot.get("title"))
             score = _clean(dot.get("score"))
             url = _clean(dot.get("url"))
+            page = _clean(dot.get("page_number")) or "?"
             if url:
-                lines.append(f"- [{title}]({url}) - echo score {score}")
+                lines.append(f"- Page {page}: [{title}]({url}) - echo score {score}")
             else:
-                lines.append(f"- {title} - echo score {score}")
+                lines.append(f"- Page {page}: {title} - echo score {score}")
 
     if last_artifact:
         lines.extend(
@@ -107,10 +108,14 @@ def _idea_section(index: int, idea: dict[str, Any]) -> list[str]:
                 url = _clean(project.get("url") or project.get("host") or "")
                 matched = ", ".join(str(term) for term in echo.get("matched_terms") or [])
                 score_text = _clean(echo.get("score"))
+                page = _clean(echo.get("page_number")) or "?"
                 if url:
-                    lines.append(f"  - [{title}]({url}) - score {score_text}; matched {matched or 'no shared terms'}")
+                    lines.append(
+                        f"  - Page {page}: [{title}]({url}) - score {score_text}; "
+                        f"matched {matched or 'no shared terms'}"
+                    )
                 else:
-                    lines.append(f"  - {title} - score {score_text}; matched {matched or 'no shared terms'}")
+                    lines.append(f"  - Page {page}: {title} - score {score_text}; matched {matched or 'no shared terms'}")
     lines.append("")
     return lines
 

hackathon_advisor/scoring.py

@@ -40,6 +40,7 @@ class ScoreCard:
             "echoes": [
                 {
                     "score": round(hit.score, 3),
+                    "page_number": hit.page_number,
                     "matched_terms": list(hit.matched_terms),
                     "project": hit.project.to_public_dict(),
                 }

hackathon_advisor/wood_map.py

@@ -43,6 +43,7 @@ def _echo_dot(hit: SearchHit) -> dict[str, Any]:
     dot = _project_dot(hit.project, "echo")
     dot["score"] = round(hit.score, 3)
     dot["matched_terms"] = list(hit.matched_terms)
+    dot["page_number"] = hit.page_number
     dot["radius"] = max(5, min(9, round(4 + hit.score * 14)))
     return dot
 

static/app.js

@@ -198,7 +198,11 @@ function handleEvent(event) {
     session = event.state || {};
     session.profile = session.profile || {};
     session.targets = Array.isArray(session.targets) ? session.targets : [];
-    if (event.projects?.length) renderProjects(event.projects);
+    if (event.score?.echoes?.length) {
+      renderCitations(event.score.echoes);
+    } else if (event.projects?.length) {
+      renderProjects(event.projects);
+    }
     if (event.whitespace?.length) renderWhitespace(event.whitespace);
     renderTargets(session.targets);
     renderProfile(session.profile);
@@ -315,6 +319,30 @@ function renderProjects(projects) {
   }
 }
 
+function renderCitations(echoes) {
+  projectsEl.innerHTML = "";
+  if (!echoes.length) {
+    projectsEl.innerHTML = `<div class="empty">No red ink yet.</div>`;
+    return;
+  }
+  for (const echo of echoes.slice(0, 5)) {
+    const project = echo.project || {};
+    const item = document.createElement("a");
+    item.className = "project citation";
+    item.href = project.url || project.host || "#";
+    item.target = "_blank";
+    item.rel = "noreferrer";
+    item.title = project.title || project.id || "Project citation";
+    const matched = (echo.matched_terms || []).slice(0, 5).join(", ") || "no shared terms";
+    item.innerHTML = `
+      <strong>Page ${escapeHtml(echo.page_number || "?")} · ${escapeHtml(project.title || project.id || "Untitled")}</strong>
+      <p>${escapeHtml(project.summary || project.id || "")}</p>
+      <span>${Number(echo.score || 0).toFixed(3)} · ${escapeHtml(matched)}</span>
+    `;
+    projectsEl.append(item);
+  }
+}
+
 function renderWhitespace(items) {
   whitespaceEl.innerHTML = "";
   if (!items.length) {
@@ -414,6 +442,7 @@ function exportArtifact(artifact) {
   ctx.font = "28px Georgia, serif";
   ctx.fillStyle = "#6b4e35";
   wrapText(ctx, artifact.caption || "", 82, 252, 720, 36);
+  drawCitationList(ctx, seal.echoes || [], 742, 330, 330);
 
   ctx.save();
   ctx.translate(930, 226);
@@ -528,6 +557,21 @@ function drawWoodMap(ctx, map, x, y, width, height, verdict) {
   ctx.restore();
 }
 
+function drawCitationList(ctx, echoes, x, y, maxWidth) {
+  if (!echoes.length) return;
+  ctx.save();
+  ctx.fillStyle = "#6b4e35";
+  ctx.font = "800 18px Inter, sans-serif";
+  ctx.fillText("CLOSEST PAGES", x, y);
+  ctx.font = "700 15px Inter, sans-serif";
+  echoes.slice(0, 3).forEach((echo, index) => {
+    const project = echo.project || {};
+    const label = `Page ${echo.page_number || "?"}: ${project.title || project.id || "Untitled"}`;
+    wrapText(ctx, label, x, y + 24 + index * 26, maxWidth, 18);
+  });
+  ctx.restore();
+}
+
 function wrapText(ctx, text, x, y, maxWidth, lineHeight, align = "left") {
   const words = String(text).split(/\s+/);
   let line = "";

static/styles.css

@@ -322,6 +322,15 @@ button:disabled {
   line-height: 1.35;
 }
 
+.project span {
+  display: inline-block;
+  margin-top: 6px;
+  color: #70401e;
+  font-size: 0.74rem;
+  line-height: 1.25;
+  font-weight: 900;
+}
+
 .idea span {
   display: inline-block;
   margin-top: 6px;

tests/test_agent.py

@@ -31,6 +31,8 @@ def test_agent_scores_and_persists_idea() -> None:
     assert result.state["last_artifact"]["title"] == result.artifact["title"]
     assert result.artifact["wood_map"]["caption"]
     assert {dot["kind"] for dot in result.artifact["wood_map"]["dots"]} >= {"idea", "echo", "inked"}
+    assert result.score.to_dict()["echoes"][0]["page_number"] >= 1
+    assert "page " in result.response
     assert result.response
 
 

tests/test_data.py

@@ -11,6 +11,7 @@ def test_project_index_searches_snapshot() -> None:
 
     assert hits
     assert hits[0].project.id.startswith("build-small-hackathon/")
+    assert hits[0].page_number >= 1
     assert index.index_algorithm == "tfidf-sparse-v1"
 
 

tests/test_field_notes.py

@@ -31,6 +31,7 @@ def test_field_notes_markdown_contains_session_decisions() -> None:
     assert "## Build Plan" in markdown
     assert "Record the trace and write Field Notes" in markdown
     assert "Closest cited Spaces" in markdown
+    assert "Page " in markdown
     assert "## Wood Map" in markdown
     assert "echo score" in markdown
     assert "Planner call: `make_plan`" in markdown