@erclx/canon 5.15.0 → 5.17.0

package/src/teach/nav.ts

@@ -10,6 +10,14 @@ import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
 import { stripFrontmatter } from '@/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
+import { compileScript } from '@/teach/browser/compile'
+import { dismiss } from '@/teach/browser/dismiss'
+import { focusLine } from '@/teach/browser/focus-line'
+import { glossaryFilter } from '@/teach/browser/glossary-filter'
+import { head } from '@/teach/browser/head'
+import { quiz } from '@/teach/browser/quiz'
+import { sidebar } from '@/teach/browser/sidebar'
+import { theme } from '@/teach/browser/theme'
 import { linkLessonReferences } from '@/teach/cross-references'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
 import { LESSON_NUMBER } from '@/teach/lesson'
@@ -82,76 +90,6 @@ const CARET =
 const THEME_BUTTON =
   '<button class="theme" type="button" aria-label="Switch between light and dark"><svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg><svg class="moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg></button>'
 
-const THEME_SCRIPT =
-  '<script>(function(){var r=document.documentElement;try{var s=localStorage.getItem("course-theme");if(s)r.dataset.theme=s;}catch(e){}document.addEventListener("click",function(e){var b=e.target.closest(".theme");if(!b)return;var d=r.dataset.theme==="dark"||(!r.dataset.theme&&matchMedia("(prefers-color-scheme: dark)").matches);r.dataset.theme=d?"light":"dark";try{localStorage.setItem("course-theme",r.dataset.theme);}catch(e){}});})();</script>'
-
-const CLOSE_OUTSIDE_CLICK_SCRIPT = `<script>
-(function () {
-  var MENUS = "details.jump[open], details.sb-ws[open]";
-
-  function close(except) {
-    document.querySelectorAll(MENUS).forEach(function (d) {
-      if (d !== except) d.open = false;
-    });
-  }
-  document.addEventListener("click", function (e) {
-    var inside = e.target.closest("details.jump, details.sb-ws");
-    close(inside);
-  });
-  document.addEventListener("keydown", function (e) {
-    if (e.key !== "Escape") return;
-    var open = document.querySelector(MENUS);
-    if (!open) return;
-    open.open = false;
-    var s = open.querySelector("summary");
-    if (s) s.focus();
-  });
-
-  /* Hover intent on the breadcrumb only. The sidebar's workspace switcher stays
-     click-only on purpose: its panel opens directly over the lesson list, which
-     is where the pointer is headed, so hovering it would cover the thing
-     being reached for. The breadcrumb's panel drops over body text instead. */
-  var OPEN = 120, SHUT = 260;
-
-  document.querySelectorAll("details.jump").forEach(function (d) {
-    var host = d.closest(".crumb-item") || d;
-    var timer = null;
-    var openedByHover = false;
-
-    function arm(want) {
-      clearTimeout(timer);
-      timer = setTimeout(function () {
-        if (want) close(d);
-        d.open = want;
-      }, want ? OPEN : SHUT);
-    }
-
-    host.addEventListener("mouseenter", function () {
-      if (!d.open) openedByHover = true;
-      arm(true);
-    });
-    host.addEventListener("mouseleave", function () {
-      openedByHover = false;
-      arm(false);
-    });
-    /* Keeps it open while the pointer is inside the panel, without cancelling a
-       pending open, which is what silently disabled this on one of two menus. */
-    d.addEventListener("mouseenter", function () { if (d.open) clearTimeout(timer); });
-
-    /* Hover and click were wired to one disclosure and fought: hover opened the
-       panel, then the summary's native click toggled what hover had already
-       opened, so reaching for an item shut it. A click on a panel hover opened
-       keeps it open, and a second click closes. The click path stays live for
-       touch, where no hover exists, and for the keyboard, where Enter is the
-       only way in. */
-    var summary = d.querySelector("summary");
-    if (summary) summary.addEventListener("click", function (e) {
-      if (d.open && openedByHover) { e.preventDefault(); openedByHover = false; }
-    });
-  });
-})();
-</script>`
-
 /**
  * The stepper, as CSS over the radio inputs a lesson's quiz is written from.
  *
@@ -195,307 +133,6 @@ const QUIZ_CSS = `@supports selector(:has(*)) {
  */
 const LEGACY_OPTION = '<button class="opt"'
 
-/**
- * What reveals feedback in a lesson written against `LEGACY_OPTION`. The radio
- * shape needs none of it, so a lesson carrying no button option gets no script,
- * and removing this outright would leave the lessons already written showing no
- * feedback at all.
- */
-const QUIZ_SCRIPT =
-  '<script>document.querySelectorAll(".q").forEach(function(q){var f=q.querySelector(".fb");q.querySelectorAll(".opt").forEach(function(b){b.addEventListener("click",function(){if(f.classList.contains("show"))return;q.querySelectorAll(".opt").forEach(function(o){o.dataset.state=o.dataset.a==="1"?"right":(o===b?"chosen":"wrong");});f.classList.add("show");});});});</script>'
-
-const GLOSSARY_FILTER_SCRIPT = `<script>
-(function () {
-  var input = document.getElementById("gfilter");
-  var list = document.getElementById("gloss");
-  var count = document.getElementById("gloss-count");
-  if (!input || !list) return;
-  function updateGroups() {
-    list.querySelectorAll(".gloss-group").forEach(function (heading) {
-      var el = heading.nextElementSibling;
-      var any = false;
-      while (el && !el.classList.contains("gloss-group")) {
-        if (el.style.display !== "none") any = true;
-        el = el.nextElementSibling;
-      }
-      heading.style.display = any ? "" : "none";
-    });
-  }
-  input.addEventListener("input", function () {
-    var q = input.value.toLowerCase();
-    var n = 0;
-    list.querySelectorAll(".gterm").forEach(function (entry) {
-      var match = entry.textContent.toLowerCase().includes(q);
-      entry.style.display = match ? "" : "none";
-      if (match) n++;
-    });
-    list.classList.toggle("none", n === 0);
-    updateGroups();
-    if (count) {
-      var total = list.querySelectorAll(".gterm").length;
-      count.textContent = (n === total ? total : n + " of " + total) + (total === 1 ? " term" : " terms");
-    }
-  });
-  var clear = list.querySelector(".clear");
-  if (clear) {
-    clear.addEventListener("click", function () {
-      input.value = "";
-      input.dispatchEvent(new Event("input"));
-      input.focus();
-    });
-  }
-})();
-</script>`
-
-/**
- * The outline rail's focus-line ramp, as the JavaScript source `OUTLINE_SCRIPT`
- * embeds verbatim, so there is one copy of the formula rather than a TS
- * reimplementation that could drift from what a browser actually runs.
- *
- * It ramps the line from near the top at scroll 0 to the viewport's bottom
- * edge at max scroll, so the last heading is reachable regardless of how
- * little content trails it. The prior formula ended the ramp 120px short of
- * the edge, which left a heading followed by under 120px of trailing content
- * permanently unmarked, since its top never fell below the line even at max
- * scroll.
- */
-const FOCUS_LINE_BODY = `if (max <= 0) return innerHeight;
-    var progress = Math.min(1, Math.max(0, scrollY / max));
-    return 120 + progress * Math.max(0, innerHeight - 120);`
-
-/**
- * Compiles and runs `FOCUS_LINE_BODY`, so a test exercises the exact source
- * the browser runs rather than a parallel copy of it.
- */
-export function focusLine(
-  scrollY: number,
-  max: number,
-  innerHeight: number,
-): number {
-  const compiled = new Function(
-    'scrollY',
-    'max',
-    'innerHeight',
-    FOCUS_LINE_BODY,
-  ) as (scrollY: number, max: number, innerHeight: number) => number
-
-  return compiled(scrollY, max, innerHeight)
-}
-
-/**
- * The panel's state, settled before the first paint rather than after it. An
- * arm that set the narrow default afterwards slid the panel in and back out on
- * every load, and a restored custom width animated in from the default.
- *
- * A listing page starts shut because the body already lists what the panel
- * would, and a lesson starts open because there the panel is the only
- * cross-lesson navigation on the page. A stored preference beats both. A count
- * threshold on its own was built and reverted, since it hides the panel on a
- * lesson too.
- */
-function headScript(page: 'index' | 'lesson'): string {
-  return `<script>(function(){var r=document.documentElement,s=null;
-r.dataset.page="${page}";
-if(matchMedia("(max-width: ${TEACH_SIDEBAR_BREAKPOINT}px)").matches){r.classList.add("sb-shut");return}
-try{s=localStorage.getItem("teach-sb")}catch(e){}
-var idx=r.dataset.page==="index";
-if(s==="shut"||(s===null&&idx))r.classList.add("sb-shut");
-var w=null;try{w=localStorage.getItem("teach-sb-w")}catch(e){}
-if(w)r.style.setProperty("--sb-w",w+"px")})();</script>`
-}
-
-const SIDEBAR_SCRIPT = `<script>
-(function () {
-  var root = document.documentElement;
-  var panel = document.querySelector(".sb");
-  if (!panel) return;
-
-  var fold = document.querySelector(".sb-fold");
-  var narrow = matchMedia("(max-width: ${TEACH_SIDEBAR_BREAKPOINT}px)");
-
-  var FOCUSABLE = "a[href], button:not([disabled]), summary, input, [tabindex]:not([tabindex='-1'])";
-
-  function panelStops() {
-    return Array.prototype.slice.call(panel.querySelectorAll(FOCUSABLE))
-      .filter(function (el) { return el.offsetParent !== null || el === document.activeElement; });
-  }
-
-  /* The focus return belongs here rather than on the close control, because all
-     three routes out land here and only one of them used to move focus. The
-     shut panel takes visibility: hidden 180ms later, so a reader who pressed
-     Escape kept focus on a control that then disappeared under them and the
-     browser dropped them at the top of the document. */
-  function shut() {
-    var inside = panel.contains(document.activeElement);
-    root.classList.add("sb-shut");
-    try { localStorage.setItem("teach-sb", "shut"); } catch (e) {}
-    if (inside && fold) fold.focus();
-  }
-
-  if (fold) fold.addEventListener("click", function () {
-    root.classList.toggle("sb-shut");
-    try {
-      localStorage.setItem("teach-sb", root.classList.contains("sb-shut") ? "shut" : "open");
-    } catch (e) {}
-    /* An overlay takes focus with it. Without this a keyboard reader opens the
-       panel and goes on tabbing through the lesson behind the scrim. */
-    if (!narrow.matches || root.classList.contains("sb-shut")) return;
-    var first = panel.querySelector("a, button, summary, input");
-    if (first) first.focus();
-  });
-
-  var scrim = document.createElement("div");
-  scrim.className = "sb-scrim";
-  document.body.appendChild(scrim);
-  scrim.addEventListener("click", shut);
-
-  document.addEventListener("keydown", function (e) {
-    if (e.key === "Escape" && narrow.matches) { shut(); return; }
-
-    /* The scrim says the lesson is unavailable, so Tab must not reach it.
-       Moving focus into the panel on open only defers this by however many
-       controls the panel holds. */
-    if (e.key !== "Tab") return;
-    if (!narrow.matches || root.classList.contains("sb-shut")) return;
-
-    var stops = panelStops();
-    if (!stops.length) return;
-
-    var first = stops[0];
-    var last = stops[stops.length - 1];
-
-    if (!panel.contains(document.activeElement)) {
-      (e.shiftKey ? last : first).focus();
-      e.preventDefault();
-    } else if (e.shiftKey && document.activeElement === first) {
-      last.focus();
-      e.preventDefault();
-    } else if (!e.shiftKey && document.activeElement === last) {
-      first.focus();
-      e.preventDefault();
-    }
-  });
-
-  /* The panel covers the masthead and the toggle that opened it, so it carries
-     its own way out rather than leaving the scrim as the only route. */
-  var close = document.createElement("button");
-  close.type = "button";
-  close.className = "sb-close";
-  close.setAttribute("aria-label", "Close the course panel");
-  close.textContent = "\\u00d7";
-  close.addEventListener("click", shut);
-  panel.appendChild(close);
-
-  var MIN = 208, MAX = 296, DEF = 256;
-  var grip = document.querySelector(".sb-grip");
-  var lastWidth = parseInt(root.style.getPropertyValue("--sb-w"), 10) || DEF;
-
-  function setWidth(px, save) {
-    var w = Math.max(MIN, Math.min(MAX, Math.round(px)));
-    root.style.setProperty("--sb-w", w + "px");
-    lastWidth = w;
-    if (save) { try { localStorage.setItem("teach-sb-w", String(w)); } catch (e) {} }
-  }
-
-  if (grip) {
-    var dragging = false;
-    grip.addEventListener("pointerdown", function (e) {
-      dragging = true;
-      grip.setPointerCapture(e.pointerId);
-      root.classList.add("sb-drag");
-      e.preventDefault();
-    });
-    grip.addEventListener("pointermove", function (e) {
-      if (dragging) setWidth(e.clientX, false);
-    });
-    grip.addEventListener("pointerup", function (e) {
-      if (!dragging) return;
-      dragging = false;
-      root.classList.remove("sb-drag");
-      grip.releasePointerCapture(e.pointerId);
-      setWidth(lastWidth, true);
-    });
-    grip.addEventListener("dblclick", function () { setWidth(DEF, true); });
-    grip.addEventListener("keydown", function (e) {
-      var step = e.shiftKey ? 32 : 8;
-      if (e.key === "ArrowLeft") { setWidth(lastWidth - step, true); e.preventDefault(); }
-      else if (e.key === "ArrowRight") { setWidth(lastWidth + step, true); e.preventDefault(); }
-      else if (e.key === "Home") { setWidth(DEF, true); e.preventDefault(); }
-    });
-  }
-
-  var filter = document.querySelector(".sb-filter input");
-  if (filter) filter.addEventListener("input", function () {
-    var q = filter.value.trim().toLowerCase();
-    document.querySelectorAll(".sb-list > li").forEach(function (li) {
-      li.classList.toggle("hide", q !== "" && li.textContent.toLowerCase().indexOf(q) === -1);
-    });
-  });
-
-  var slot = document.querySelector(".sb-out-slot");
-  var hs = Array.prototype.slice.call(document.querySelectorAll("main h2"));
-  var links = [];
-
-  if (slot && hs.length) {
-    var list = document.createElement("ul");
-    list.className = "sb-out";
-    hs.forEach(function (h, i) {
-      if (!h.id) h.id = "s" + i;
-      var li = document.createElement("li");
-      var a = document.createElement("a");
-      a.href = "#" + h.id;
-      a.textContent = h.textContent.trim();
-      li.appendChild(a);
-      list.appendChild(li);
-    });
-    slot.parentNode.replaceChild(list, slot);
-    links = Array.prototype.slice.call(list.querySelectorAll("a"));
-  }
-
-  /* The bar reports position inside the lesson, which nothing reported before
-     the segmented track retired. The breadcrumb's last segment carries the
-     lesson title once the real one has scrolled off. */
-  var bar = document.querySelector(".bar");
-  var here = document.querySelector(".crumb-here");
-  var h1 = document.querySelector("main h1");
-  var counter = here ? here.textContent.trim() : "";
-  var title = h1 ? h1.textContent.trim() : "";
-
-  function focusLine() {
-    var max = document.documentElement.scrollHeight - innerHeight;
-    ${FOCUS_LINE_BODY}
-  }
-
-  function sync() {
-    if (bar) {
-      var max = document.documentElement.scrollHeight - innerHeight;
-      var pct = max > 0 ? Math.min(100, Math.max(0, (scrollY / max) * 100)) : 0;
-      bar.style.setProperty("--read", pct.toFixed(1) + "%");
-    }
-
-    if (here && h1 && title && counter) {
-      var want = h1.getBoundingClientRect().bottom < 56 ? title : counter;
-      if (here.textContent !== want) here.textContent = want;
-    }
-
-    if (links.length) {
-      /* Nothing is marked until a heading has actually passed the line, so the
-         first section is not reported as current while the title is on screen. */
-      var best = -1;
-      var line = focusLine();
-      for (var i = 0; i < hs.length; i++) {
-        if (hs[i].getBoundingClientRect().top <= line) best = i;
-      }
-      links.forEach(function (l, j) { l.classList.toggle("on", j === best); });
-    }
-  }
-
-  addEventListener("scroll", sync, { passive: true });
-  addEventListener("resize", sync);
-  sync();
-})();
-</script>`
-
 function escapeHtml(text: string): string {
   return text
     .replace(/&/g, '&amp;')
@@ -685,13 +322,21 @@ function renderHeader(
 </header>`
 }
 
+function headScript(page: 'index' | 'lesson'): string {
+  return compileScript(head, [page, TEACH_SIDEBAR_BREAKPOINT])
+}
+
 function renderScripts(
   includeQuiz: boolean,
   includeGlossaryFilter: boolean,
 ): string {
-  const scripts = [THEME_SCRIPT, CLOSE_OUTSIDE_CLICK_SCRIPT, SIDEBAR_SCRIPT]
-  if (includeGlossaryFilter) scripts.push(GLOSSARY_FILTER_SCRIPT)
-  if (includeQuiz) scripts.push(QUIZ_SCRIPT)
+  const scripts = [
+    compileScript(theme),
+    compileScript(dismiss),
+    compileScript(sidebar, [TEACH_SIDEBAR_BREAKPOINT], [focusLine]),
+  ]
+  if (includeGlossaryFilter) scripts.push(compileScript(glossaryFilter))
+  if (includeQuiz) scripts.push(compileScript(quiz))
   return scripts.join('\n')
 }
 

package/src/teach/workspace.ts

@@ -885,12 +885,60 @@ async function openFile(
   return path
 }
 
+/** The entry lines of the file, or of one heading's section. */
+function listedEntries(text: string, heading?: string): string[] {
+  const body = unfenced(text)
+  const section = heading
+    ? sectionRange(body, heading, text.split('\n').length)
+    : undefined
+  if (heading && !section) return []
+
+  return body
+    .filter(
+      (line) =>
+        isEntry(line.text) &&
+        (!section ||
+          (line.number - 1 >= section.start && line.number - 1 < section.end)),
+    )
+    .map((line) => line.text)
+}
+
+function lists(entries: readonly string[], source: Source): boolean {
+  return entries.some((line) => line.includes(`(${source.url})`))
+}
+
+/**
+ * Drops the lead entries naming the given URLs, wrapped continuation lines
+ * included, and restores the placeholder when the section empties.
+ */
+function withoutLeads(text: string, urls: ReadonlySet<string>): string {
+  const lines = text.split('\n')
+  const section = sectionRange(unfenced(text), LEADS_HEADING, lines.length)
+  if (!section) return text
+
+  const bullets = bulletRange(unfenced(text), section)
+  if (!bullets) return text
+
+  const kept = bulletBlocks(lines.slice(bullets.start, bullets.end)).filter(
+    (block) => ![...urls].some((url) => block[0].includes(`(${url})`)),
+  )
+
+  return [
+    ...lines.slice(0, bullets.start),
+    ...(kept.length > 0 ? kept.flat() : [PLACEHOLDER]),
+    ...lines.slice(bullets.end),
+  ].join('\n')
+}
+
 /**
  * Appends sources to `RESOURCES.md`, keeping what was read apart from what was
  * only found.
  *
  * A URL already listed under either heading is refused rather than repeated,
  * since a second entry for one source splits what rests on it across two lines.
+ * The one exception is a read source found under `## Leads`, which moves to
+ * `## Read` under its new title, since opening a lead is how it becomes read.
+ * Any refusal leaves the file untouched, so a batch lands whole or not at all.
  */
 export async function recordSources(
   root: string,
@@ -905,13 +953,16 @@ export async function recordSources(
   if (typeof path !== 'string') return path
 
   let text = await readFile(path, 'utf8')
-  const listed = unfenced(text)
-    .map((line) => line.text)
-    .filter(isEntry)
+  const listed = listedEntries(text)
+  const leadEntries = listedEntries(text, LEADS_HEADING)
 
-  const repeated = [...read, ...leads].filter((source) =>
-    listed.some((line) => line.includes(`(${source.url})`)),
-  )
+  const isPromotion = (source: Source) => lists(leadEntries, source)
+  const promoted = read.filter(isPromotion)
+
+  const repeated = [
+    ...read.filter((source) => !isPromotion(source)),
+    ...leads,
+  ].filter((source) => lists(listed, source))
 
   if (repeated.length > 0) {
     return refuse(
@@ -921,6 +972,10 @@ export async function recordSources(
     )
   }
 
+  if (promoted.length > 0) {
+    text = withoutLeads(text, new Set(promoted.map((source) => source.url)))
+  }
+
   for (const [heading, sources] of [
     [READ_HEADING, read],
     [LEADS_HEADING, leads],

package/standards/figures.md

@@ -38,6 +38,7 @@ A figure failing these is non-conforming even when it satisfies every shape rule
 
 - Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
 - Reserve freehand inline SVG, plain shapes and lines authored directly in the markup, for a subject that is not graph-shaped. A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent one drawn by hand, so the hatch stays open rather than forcing every figure through the renderer.
+- Draw a figure in a teach lesson freehand whatever its shape. A lesson letters its figures in a hand font the renderer cannot load, so Mermaid measures every label in a narrower fallback face, and the page then clips the wider text it actually shows.
 - State this as a render-first policy rather than a ban on a tool-exported drawing. Routing a graph-shaped figure through Mermaid is itself running it through an external tool, so a rule banning any diagram "exported from a diagramming tool" would forbid the path this policy requires.
 
 ## Wrapping and captioning

package/tooling/claude/reference.md

@@ -91,6 +91,6 @@ The first entry covers the whole record root, so a record folder added later nee
 
 ## settings.json
 
-- Project seed at `tooling/claude/seeds/.claude/settings.json` ships two PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh` and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
+- Project seed at `tooling/claude/seeds/.claude/settings.json` ships three PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh`, `.claude/hooks/search-reminder.sh`, and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
 - User-level template at `tooling/claude/user/settings.template.json` carries `attribution.commit` and `attribution.pr` (empty strings to suppress co-author tags), `permissions.allow` with `Bash(bun run *)`, and `permissions.deny` with `Read(**/.env)` and `Read(**/.env.*)` to block accidental secret exposure across any project. Installed once per machine via `canon claude setup`.
 - The deprecated `includeCoAuthoredBy` key is not used.

package/tooling/claude/seeds/.claude/hooks/path-form.sh

@@ -8,10 +8,8 @@
 # and no error appears. This computes the fact a session was asking itself
 # to infer on every response and hands the answer back instead.
 #
-# The entrypoint branch (bare vs. `file://` link) stays prose in
-# governance/rules/claude/566-output.md. CLAUDE_CODE_ENTRYPOINT is not among
-# the environment variables Claude Code documents as passed to a hook
-# subprocess, unlike CLAUDE_PROJECT_DIR, so a hook cannot read it reliably.
+# The link form a response uses comes from the harness's own instruction for
+# its surface, not from this hook or the output rule.
 #
 # The worktree branch comes from the path rather than from `git rev-parse`,
 # the way `tasks-index.sh` and `memory-index.sh` already derive their main

package/tooling/claude/seeds/.claude/hooks/search-reminder.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+[ "$tool" = "WebSearch" ] || exit 0
+
+# Without a session id there is no stable key to dedupe on, and a shared marker
+# would silence every later session, so stay quiet rather than guess one.
+session=$(printf '%s' "$input" | jq -r '.session_id // empty')
+[ -n "$session" ] || exit 0
+
+key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
+# The marker is scratch, so it follows the scratch folder to whichever record
+# root the project carries rather than creating a second one beside it.
+project="${CLAUDE_PROJECT_DIR:-.}"
+if [ -d "$project/.canon" ]; then
+  marker_dir="$project/.canon/tmp/hooks/search-reminder"
+else
+  marker_dir="$project/.claude/.tmp/hooks/search-reminder"
+fi
+marker="$marker_dir/$key"
+[ -f "$marker" ] && exit 0
+mkdir -p "$marker_dir"
+: >"$marker"
+
+msg='Load the canon:search-craft skill before this web search. Report it rather than proceeding silently when the skill does not resolve.'
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/settings.json

@@ -10,6 +10,15 @@
           }
         ]
       },
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/search-reminder.sh"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [