feat: add wood map artifact

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.
 
+## Wood Map
+
+Every scored fate page now carries a deterministic `wood_map` artifact: background dots for inked Spaces, red dots for
+the closest cited echoes, and a green/red "you" dot for the current idea. The live UI and PNG export render the same
+map, so the share artifact visually proves whether the page sits in an empty margin or near existing work.
+
 ## Tool-Call Contract
 
 `/api/tool-contracts` exposes the JSON schemas intended for MiniCPM-style tool calling. `tool_contract_check` accepts a

hackathon_advisor/agent.py

@@ -9,7 +9,16 @@ from hackathon_advisor.data import Project, ProjectIndex, WhitespaceItem
 from hackathon_advisor.model_runtime import ToolPlanner, create_tool_planner, runtime_status
 from hackathon_advisor.scoring import ScoreCard
 from hackathon_advisor.tool_contracts import ToolCall
-from hackathon_advisor.tools import TARGETS, AdvisorTools, Idea, ToolEvent, idea_from_text, normalize_targets, targets_from_state
+from hackathon_advisor.tools import (
+    TARGETS,
+    AdvisorTools,
+    Idea,
+    ToolEvent,
+    idea_from_text,
+    normalize_targets,
+    targets_from_state,
+)
+from hackathon_advisor.wood_map import build_wood_map
 
 
 @dataclass
@@ -440,4 +449,5 @@ class AdvisorEngine:
             "overall": score.overall,
             "caption": f"Mothback inked my Build Small fate page: {idea.title} - {score.verdict}.",
             "seal": score.to_dict(),
+            "wood_map": build_wood_map(self.index, idea, score),
         }

hackathon_advisor/field_notes.py

@@ -58,6 +58,20 @@ def build_field_notes_markdown(session: dict[str, Any], metadata: dict[str, Any]
     else:
         lines.append("No tool trace was recorded.")
 
+    wood_map = last_artifact.get("wood_map") if isinstance(last_artifact.get("wood_map"), dict) else {}
+    if wood_map:
+        lines.extend(["", "## Wood Map", "", _clean(wood_map.get("caption"))])
+        for dot in _list_of_dicts(wood_map.get("dots")):
+            if dot.get("kind") != "echo":
+                continue
+            title = _clean(dot.get("title"))
+            score = _clean(dot.get("score"))
+            url = _clean(dot.get("url"))
+            if url:
+                lines.append(f"- [{title}]({url}) - echo score {score}")
+            else:
+                lines.append(f"- {title} - echo score {score}")
+
     if last_artifact:
         lines.extend(
             [

hackathon_advisor/wood_map.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Any
+
+from hackathon_advisor.data import Project, ProjectIndex, SearchHit
+from hackathon_advisor.scoring import ScoreCard
+from hackathon_advisor.tools import Idea
+
+
+def build_wood_map(index: ProjectIndex, idea: Idea, score: ScoreCard) -> dict[str, Any]:
+    echoes = list(score.echoes)
+    background = _background_projects(index, echoes)
+    dots = [_project_dot(project, "inked") for project in background]
+    dots.extend(_echo_dot(hit) for hit in echoes[:5])
+    dots.append(_idea_dot(idea, score, echoes))
+    return {
+        "caption": _caption(score, echoes),
+        "dots": _dedupe_dots(dots),
+    }
+
+
+def _background_projects(index: ProjectIndex, echoes: list[SearchHit]) -> list[Project]:
+    echo_ids = {hit.project.id for hit in echoes}
+    projects = [project for project in index.top_projects(limit=22) if project.id not in echo_ids]
+    return projects[:16]
+
+
+def _project_dot(project: Project, kind: str) -> dict[str, Any]:
+    x, y = _point(project.id)
+    return {
+        "id": project.id,
+        "kind": kind,
+        "title": project.title,
+        "url": project.url,
+        "x": x,
+        "y": y,
+        "radius": 3,
+    }
+
+
+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["radius"] = max(5, min(9, round(4 + hit.score * 14)))
+    return dot
+
+
+def _idea_dot(idea: Idea, score: ScoreCard, echoes: list[SearchHit]) -> dict[str, Any]:
+    if echoes and not score.verdict.startswith("UNWRITTEN"):
+        lead_x, lead_y = _point(echoes[0].project.id)
+        x = _clamp(lead_x + 7, 8, 92)
+        y = _clamp(lead_y - 5, 8, 92)
+    else:
+        x, y = _point(f"idea:{idea.id}:{idea.title}")
+    return {
+        "id": idea.id,
+        "kind": "idea",
+        "title": idea.title,
+        "x": x,
+        "y": y,
+        "radius": 8,
+        "verdict": score.verdict,
+        "overall": score.overall,
+    }
+
+
+def _caption(score: ScoreCard, echoes: list[SearchHit]) -> str:
+    if score.verdict.startswith("UNWRITTEN"):
+        return "Your page sits in a pale margin beyond the nearest inked clusters."
+    names = ", ".join(hit.project.title for hit in echoes[:2]) or "nearby pages"
+    return f"Your page is pressed close to {names}; the red dots are the strongest echoes."
+
+
+def _point(key: str) -> tuple[int, int]:
+    digest = sha256(key.encode("utf-8")).hexdigest()
+    x = 8 + int(digest[:4], 16) % 84
+    y = 8 + int(digest[4:8], 16) % 84
+    return x, y
+
+
+def _clamp(value: int, low: int, high: int) -> int:
+    return max(low, min(high, value))
+
+
+def _dedupe_dots(dots: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen: set[tuple[str, str]] = set()
+    deduped: list[dict[str, Any]] = []
+    for dot in dots:
+        key = (str(dot.get("kind")), str(dot.get("id")))
+        if key in seen:
+            continue
+        deduped.append(dot)
+        seen.add(key)
+    return deduped

static/app.js

@@ -10,6 +10,7 @@ const whitespaceEl = document.querySelector("#whitespace");
 const ideasEl = document.querySelector("#ideas");
 const targetsEl = document.querySelector("#targets");
 const profileEl = document.querySelector("#profile");
+const woodMapEl = document.querySelector("#wood-map");
 const scoreEl = document.querySelector("#score");
 const planEl = document.querySelector("#plan");
 const traceEl = document.querySelector("#trace");
@@ -126,6 +127,7 @@ async function bootstrap() {
   renderProjects(data.top_projects || []);
   renderWhitespace(data.whitespace || []);
   renderIdeas([]);
+  renderWoodMap(null);
   renderScore(null);
   renderPlan([]);
   renderTrace([]);
@@ -212,6 +214,7 @@ function handleEvent(event) {
     }
     if (event.artifact?.title) {
       currentArtifact = event.artifact;
+      renderWoodMap(event.artifact.wood_map || null);
       exportButton.disabled = false;
     }
     exportTraceButton.disabled = !(session.trace?.length);
@@ -261,6 +264,37 @@ function renderScore(score) {
     .join("");
 }
 
+function renderWoodMap(map) {
+  woodMapEl.innerHTML = "";
+  if (!map?.dots?.length) {
+    woodMapEl.innerHTML = `<div class="empty">No page has been placed yet.</div>`;
+    return;
+  }
+  const field = document.createElement("div");
+  field.className = "wood-map-field";
+  for (const dot of map.dots) {
+    const marker = document.createElement(dot.url ? "a" : "span");
+    const verdictClass = dot.kind === "idea" && String(dot.verdict || "").startsWith("ECHO") ? "echo-idea" : "";
+    marker.className = `wood-dot ${dot.kind || "inked"} ${verdictClass}`.trim();
+    marker.style.left = `${boundedPercent(dot.x)}%`;
+    marker.style.top = `${boundedPercent(dot.y)}%`;
+    const radius = Math.max(3, Math.min(10, Number(dot.radius || 4)));
+    marker.style.width = `${radius * 2}px`;
+    marker.style.height = `${radius * 2}px`;
+    marker.title = dot.kind === "idea" ? `You: ${dot.title}` : `${dot.title}${dot.score ? ` (${dot.score})` : ""}`;
+    if (dot.url) {
+      marker.href = dot.url;
+      marker.target = "_blank";
+      marker.rel = "noreferrer";
+    }
+    field.append(marker);
+  }
+  const caption = document.createElement("p");
+  caption.className = "wood-map-caption";
+  caption.textContent = map.caption || "Your page is plotted against the current Wood.";
+  woodMapEl.append(field, caption);
+}
+
 function renderProjects(projects) {
   projectsEl.innerHTML = "";
   if (!projects.length) {
@@ -415,6 +449,7 @@ function exportArtifact(artifact) {
     ctx.fillStyle = "#25160e";
     ctx.fillText(String(value), 582, y);
   });
+  drawWoodMap(ctx, artifact.wood_map, 742, 396, 330, 184, artifact.verdict);
 
   const link = document.createElement("a");
   link.download = `${slugify(artifact.title || "unwritten-page")}.png`;
@@ -449,6 +484,50 @@ function drawParchment(ctx, width, height) {
   ctx.strokeRect(28, 28, width - 56, height - 56);
 }
 
+function drawWoodMap(ctx, map, x, y, width, height, verdict) {
+  if (!map?.dots?.length) return;
+  ctx.save();
+  ctx.fillStyle = "rgba(255, 241, 196, 0.38)";
+  ctx.strokeStyle = "rgba(80, 47, 22, 0.34)";
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  ctx.roundRect(x, y, width, height, 8);
+  ctx.fill();
+  ctx.stroke();
+
+  ctx.fillStyle = "#6b4e35";
+  ctx.font = "800 18px Inter, sans-serif";
+  ctx.fillText("YOU VS THE WOOD", x, y - 14);
+
+  for (const dot of map.dots) {
+    const px = x + (width * boundedPercent(dot.x)) / 100;
+    const py = y + (height * boundedPercent(dot.y)) / 100;
+    const radius = Math.max(3, Math.min(10, Number(dot.radius || 4)));
+    if (dot.kind === "idea") {
+      ctx.fillStyle = verdict?.startsWith("UNWRITTEN") ? "#2f7a49" : "#8d2d26";
+      ctx.strokeStyle = "#fff0b5";
+      ctx.lineWidth = 3;
+    } else if (dot.kind === "echo") {
+      ctx.fillStyle = "#8d2d26";
+      ctx.strokeStyle = "rgba(255, 240, 181, 0.72)";
+      ctx.lineWidth = 1.5;
+    } else {
+      ctx.fillStyle = "rgba(80, 47, 22, 0.34)";
+      ctx.strokeStyle = "transparent";
+      ctx.lineWidth = 0;
+    }
+    ctx.beginPath();
+    ctx.arc(px, py, radius, 0, Math.PI * 2);
+    ctx.fill();
+    if (ctx.lineWidth) ctx.stroke();
+  }
+
+  ctx.fillStyle = "#6b4e35";
+  ctx.font = "700 15px Inter, sans-serif";
+  wrapText(ctx, map.caption || "", x, y + height + 24, width, 20);
+  ctx.restore();
+}
+
 function wrapText(ctx, text, x, y, maxWidth, lineHeight, align = "left") {
   const words = String(text).split(/\s+/);
   let line = "";
@@ -495,6 +574,10 @@ function fieldLabel(value) {
     .replace(/^\w/, (char) => char.toUpperCase());
 }
 
+function boundedPercent(value) {
+  return Math.max(4, Math.min(96, Number(value || 50)));
+}
+
 function shortDate(value) {
   if (!value) return "unknown";
   return String(value).replace("T", " ").replace(/\+00:00$/, "Z").slice(0, 16);

static/index.html

@@ -47,6 +47,10 @@
             <div id="provenance" class="provenance"></div>
             <div id="score" class="score-grid" aria-label="Seal quadrants"></div>
             <div class="panels">
+              <article class="wide-panel">
+                <h2>You vs the Wood</h2>
+                <div id="wood-map" class="wood-map"></div>
+              </article>
               <article>
                 <h2>Targets</h2>
                 <div id="targets" class="target-list"></div>

static/styles.css

@@ -275,12 +275,17 @@ button:disabled {
   gap: 16px;
 }
 
+.wide-panel {
+  grid-column: 1 / -1;
+}
+
 .project-list,
 .whitespace-list,
 .idea-list,
 .trace-list,
 .target-list,
-.profile-grid {
+.profile-grid,
+.wood-map {
   display: grid;
   gap: 9px;
 }
@@ -395,6 +400,54 @@ button:disabled {
   box-shadow: 0 0 0 3px rgba(47, 122, 73, 0.13);
 }
 
+.wood-map-field {
+  position: relative;
+  min-height: 138px;
+  border: 1px solid rgba(80, 47, 22, 0.3);
+  border-radius: 8px;
+  background:
+    linear-gradient(rgba(80, 47, 22, 0.12) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(80, 47, 22, 0.12) 1px, transparent 1px),
+    rgba(255, 241, 196, 0.28);
+  background-size: 28px 28px;
+  overflow: hidden;
+}
+
+.wood-dot {
+  position: absolute;
+  display: block;
+  border-radius: 50%;
+  transform: translate(-50%, -50%);
+}
+
+.wood-dot.inked {
+  background: rgba(80, 47, 22, 0.38);
+}
+
+.wood-dot.echo {
+  background: var(--red);
+  box-shadow: 0 0 0 2px rgba(255, 240, 181, 0.48);
+}
+
+.wood-dot.idea {
+  background: var(--leaf);
+  box-shadow:
+    0 0 0 3px #fff0b5,
+    0 0 18px rgba(47, 122, 73, 0.42);
+}
+
+.wood-dot.idea.echo-idea {
+  background: var(--red);
+}
+
+.wood-map-caption {
+  margin: 0;
+  color: var(--muted-ink);
+  font-size: 0.84rem;
+  line-height: 1.35;
+  font-weight: 800;
+}
+
 .plan-list {
   display: grid;
   gap: 7px;

tests/test_agent.py

@@ -29,6 +29,8 @@ def test_agent_scores_and_persists_idea() -> None:
     assert result.state["last_tool_resolution"]["call"]["name"] == "save_idea"
     assert result.state["trace"][0]["tool_resolution"]["call"]["name"] == "save_idea"
     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.response
 
 

tests/test_field_notes.py

@@ -31,4 +31,6 @@ 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 "## Wood Map" in markdown
+    assert "echo score" in markdown
     assert "Planner call: `make_plan`" in markdown