@erclx/canon 5.16.0 → 5.18.0

package/src/demo/drive.ts

@@ -8,6 +8,8 @@ import { deriveSteps } from '@/demo/compile'
 import type { DemoPlan, DemoStep } from '@/demo/compile'
 import type { CursorSet } from '@/demo/pointer'
 import { pointerSource } from '@/demo/pointer'
+import type { StepTiming, TargetBox } from '@/demo/timeline'
+import { timelineEntry, timelinePath, writeTimeline } from '@/demo/timeline'
 
 declare global {
   interface Window {
@@ -84,6 +86,7 @@ export type DriveResult =
       status: 'recorded'
       videoPath?: string
       stillPath?: string
+      timelinePath?: string
       steps: number
       durationMs: number
     }
@@ -150,6 +153,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
 
   let stillPath: string | undefined
   let videoPath: string | undefined
+  let timeline: string | undefined
 
   try {
     await context.addInitScript({
@@ -157,7 +161,12 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     })
     await context.addInitScript({ content: captionInitScript() })
     const page = await context.newPage()
+    // The recording begins with the page, so this is the instant a frame of
+    // the take is zero. Taking it at the first step instead would drift every
+    // entry by the opening page load.
+    const recordingStart = performance.now()
     const video = page.video()
+    const timings: StepTiming[] = []
     const pace: PointerPace = {}
 
     // The opening navigate is skipped when the plan already starts with one,
@@ -170,8 +179,16 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       }
     }
 
-    for (const step of plan.steps) {
-      await runStep(page, plan, step, pace)
+    for (const [index, step] of plan.steps.entries()) {
+      const startedAt = performance.now()
+      const box = await runStep(page, plan, step, pace)
+      timings.push({
+        index,
+        kind: step.kind,
+        startedAt,
+        endedAt: performance.now(),
+        ...(box ? { box } : {}),
+      })
       // The first marked step wins. One file holds one frame, so a plan a
       // person edited to mark several would otherwise write each over the last
       // and keep whichever ran last, with nothing saying so.
@@ -191,6 +208,11 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       // The engine keeps the auto-named recording beside the saved copy, so a
       // run that skipped this would leave two files for every demo.
       await video.delete()
+      timeline = timelinePath(videoPath)
+      writeTimeline(
+        timeline,
+        timings.map((timing) => timelineEntry(timing, recordingStart)),
+      )
     }
   } catch (error) {
     return failed('drive-failed', error)
@@ -203,6 +225,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     status: 'recorded',
     ...(videoPath ? { videoPath } : {}),
     ...(stillPath ? { stillPath } : {}),
+    ...(timeline ? { timelinePath: timeline } : {}),
     steps: plan.steps.length,
     durationMs: Date.now() - started,
   }
@@ -237,13 +260,17 @@ export interface PointerPace {
  * Exported so `drive.e2e.test.ts` can drive one real step against a real
  * caption and read it back, which is the integration a full `drive()` call
  * cannot assert without decoding the video it writes.
+ *
+ * Returns the box the pointer moved to, for the timeline, and nothing for
+ * a step that points at no target.
  */
 export async function runStep(
   page: Page,
   plan: DemoPlan,
   step: DemoStep,
   pace: PointerPace,
-): Promise<void> {
+): Promise<TargetBox | undefined> {
+  let box: TargetBox | undefined
   switch (step.kind) {
     case 'navigate':
       await page.goto(step.target || plan.url)
@@ -252,18 +279,18 @@ export async function runStep(
       }
       break
     case 'click':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       break
     case 'fill':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       await page.keyboard.type(step.text, { delay: plan.pointer.typeDelayMs })
       break
     case 'hover':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       break
     case 'scroll':
       // Centred rather than `scrollIntoViewIfNeeded`, which scrolls the least
@@ -307,6 +334,7 @@ export async function runStep(
   await setCaption(page, step.caption)
   if (step.waitFor) await page.locator(step.waitFor).first().waitFor()
   await page.waitForTimeout(step.holdMs)
+  return box
 }
 
 /**
@@ -333,7 +361,7 @@ async function moveTo(
   plan: DemoPlan,
   step: DemoStep,
   pace: PointerPace,
-): Promise<void> {
+): Promise<TargetBox> {
   pace.roundTripMs ??= await calibrateRoundTrip(page)
   const locator = page.locator(step.target).first()
   await locator.waitFor()
@@ -342,6 +370,7 @@ async function moveTo(
   await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, {
     steps: deriveSteps(plan.pointer.travelMs, pace.roundTripMs),
   })
+  return box
 }
 
 /**

package/src/demo/timeline.ts

@@ -0,0 +1,64 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+import type { DemoStep } from '@/demo/compile'
+
+/**
+ * A step's target in viewport pixels, which are the video frame's own
+ * coordinates because the recording is sized to the viewport.
+ */
+export interface TargetBox {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** One step as the run clocked it, in wall-clock milliseconds. */
+export interface StepTiming {
+  readonly index: number
+  readonly kind: DemoStep['kind']
+  readonly startedAt: number
+  readonly endedAt: number
+  readonly box?: TargetBox
+}
+
+/**
+ * Times count from the recording's start rather than the first step, since
+ * that is the clock a composition places the take on. A step ends once its
+ * hold has played, so the span covers what the viewer sees of it.
+ */
+export interface TimelineEntry {
+  readonly index: number
+  readonly kind: DemoStep['kind']
+  readonly startMs: number
+  readonly endMs: number
+  readonly box?: TargetBox
+}
+
+export function timelineEntry(
+  timing: StepTiming,
+  recordingStart: number,
+): TimelineEntry {
+  return {
+    index: timing.index,
+    kind: timing.kind,
+    startMs: Math.round(timing.startedAt - recordingStart),
+    endMs: Math.round(timing.endedAt - recordingStart),
+    ...(timing.box ? { box: timing.box } : {}),
+  }
+}
+
+export function timelinePath(videoPath: string): string {
+  return join(
+    dirname(videoPath),
+    `${basename(videoPath, extname(videoPath))}.timeline.json`,
+  )
+}
+
+export function writeTimeline(
+  path: string,
+  entries: readonly TimelineEntry[],
+): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify({ entries }, null, 2)}\n`)
+}

package/src/gate/measures.ts

@@ -10,9 +10,12 @@ import {
 import {
   isOverCount,
   isOverLength,
+  isOverRisks,
   measureArchitecture,
   missingRevisit,
+  overWords,
 } from '@/context/architecture'
+import { isOverWordCap, measureRequirements } from '@/context/requirements'
 import {
   auditSkills,
   PRACTICE_LEDGER,
@@ -246,42 +249,80 @@ function citedPaths(record: { paths?: unknown } | undefined): string[] {
 }
 
 /**
- * The architecture record against the three rules it states for itself: the
- * line ceiling its allowances derive, the entry cap, and the revisit sentence
- * closing each decision.
+ * The canonical records against the caps each states for itself. The
+ * architecture record carries five: the line ceiling its allowances derive,
+ * the entry cap, the revisit sentence closing each decision, the words a
+ * decision may hold, and the bullets its Risks section may hold. The
+ * requirements record carries one, its own word count.
  *
  * Read in-process rather than through `context audit`, whose one gating stage
- * here runs `--citations-only` and never opens the record, which is why the
- * line ceiling went unenforced by `bun run check` until this stage. A project
- * carrying no record, or a record stating none of the three, passes, since
- * each rule belongs to the record rather than to the toolkit.
+ * here runs `--citations-only` and never opens either record, which is why
+ * the line ceiling went unenforced by `bun run check` until this stage. A
+ * project carrying neither record, or records stating none of the caps,
+ * passes, since each rule belongs to the record rather than to the toolkit.
  */
-export const architectureRecord: Measure = async (ctx) => {
-  const report = await measureArchitecture(ctx.root)
+export const canonicalRecords: Measure = async (ctx) => {
+  const [report, requirements] = await Promise.all([
+    measureArchitecture(ctx.root),
+    measureRequirements(ctx.root),
+  ])
+
+  const failures: string[] = []
+  const emissions: Emission[] = []
+
   if (report === undefined) {
-    return { emissions: [info('No architecture record to measure')] }
+    emissions.push(info('No architecture record to measure'))
+  } else {
+    const decisions = report.decisions.length
+    const lackingRevisit = missingRevisit(report)
+    const longDecisions = overWords(report)
+    failures.push(
+      ...[
+        isOverCount(report) &&
+          `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
+        isOverLength(report) &&
+          `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
+        lackingRevisit.length > 0 &&
+          `No revisit sentence in ${lackingRevisit.map((heading) => `"${heading}"`).join(', ')}. Close each with one opening "Revisit when" in ${report.rel}.`,
+        longDecisions.length > 0 &&
+          `${longDecisions.map((entry) => `"${entry.heading}" (${entry.words})`).join(', ')} past ${report.wordCap} words a decision in ${report.rel}. Cut the reasoning to the trade, never split one decision across two headings.`,
+        isOverRisks(report) &&
+          `${report.risksBullets} risk bullets against a cap of ${report.riskCap} in ${report.rel}. Drop what is no longer open.`,
+      ].filter((failure): failure is string => typeof failure === 'string'),
+    )
+
+    const cap =
+      report.entryCap === undefined
+        ? 'no entry cap stated'
+        : `a cap of ${report.entryCap}`
+    emissions.push(info(`${decisions} decisions against ${cap}`))
+    if (report.riskCap !== undefined && report.risksBullets === undefined) {
+      emissions.push(
+        info(
+          `No Risks section to count against a cap of ${report.riskCap} in ${report.rel}`,
+        ),
+      )
+    }
   }
 
-  const decisions = report.decisions.length
-  const lackingRevisit = missingRevisit(report)
-  const failures = [
-    isOverCount(report) &&
-      `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
-    isOverLength(report) &&
-      `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
-    lackingRevisit.length > 0 &&
-      `No revisit sentence in ${lackingRevisit.map((heading) => `"${heading}"`).join(', ')}. Close each with one opening "Revisit when" in ${report.rel}.`,
-  ].filter((failure): failure is string => typeof failure === 'string')
+  if (requirements === undefined) {
+    emissions.push(info('No requirements record to measure'))
+  } else if (isOverWordCap(requirements)) {
+    failures.push(
+      `${requirements.words} words against a cap of ${requirements.wordCap} in ${requirements.rel}.`,
+    )
+  } else {
+    const cap =
+      requirements.wordCap === undefined
+        ? 'no word cap stated'
+        : `a cap of ${requirements.wordCap}`
+    emissions.push(
+      info(`${requirements.words} requirements words against ${cap}`),
+    )
+  }
 
   if (failures.length > 0) return { emissions: [], failure: failures.join(' ') }
-
-  const cap =
-    report.entryCap === undefined
-      ? 'no entry cap stated'
-      : `a cap of ${report.entryCap}`
-  return {
-    emissions: [info(`${decisions} decisions against ${cap}`)],
-  }
+  return { emissions }
 }
 
 /**

package/src/gate/stages.ts

@@ -6,7 +6,7 @@ import {
   skillPaths,
 } from '@/gate/boundaries'
 import {
-  architectureRecord,
+  canonicalRecords,
   auditSet,
   captureStamps,
   clientCommandCitations,
@@ -346,11 +346,11 @@ export const STAGES: readonly Stage[] = [
     success: 'Context citations resolve',
   },
   {
-    // The record's three rules are facts it states about itself, unlike the
+    // Each record's caps are facts it states about itself, unlike the
     // judgment thresholds the stage above leaves out, so they gate here.
-    id: 'architecture-record',
-    label: 'Architecture record',
-    checks: [{ kind: 'measure', measure: architectureRecord }],
+    id: 'canonical-records',
+    label: 'Canonical records',
+    checks: [{ kind: 'measure', measure: canonicalRecords }],
   },
   {
     // Unscoped, since any branch can grow any document. A document past the

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/architecture.md

@@ -73,18 +73,24 @@ A decision says why it won and rarely says when that reason stops holding, so an
 - Draft it from the harm the decision prevents, never from the mechanism it uses. A mechanism can keep working long after the reason for choosing it is gone, so re-checking it confirms the wrong fact.
 - Place the sentence after the reasoning and before any verification anchor, so the anchor stays the entry's last sentence.
 - Give a heading holding several principles one sentence, for the premise they share, rather than one per principle.
-- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the cap, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
+- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the caps, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
 - A checker reads presence alone. A vacuous sentence passes it, so the sentence is only as useful as the finding it names.
 
-## Entry cap
+## Caps
 
-Every session pays for this file before any work starts, so a heavy read is a real cost. A file that reads heavy is carrying too many decisions, not decisions written too long, so the bound is a count of decisions rather than of words.
+Every session pays for this file before any work starts, so a heavy read is a real cost. Weight comes from two places, too many decisions and decisions written too long, so the record caps both, and caps the open risks beside them.
 
-- State the cap in the record itself as a clause of the form `This record holds at most <n> decisions.` The cap is the record's own, so a checker reads it from the file, and a record stating none is measured and never gated.
-- Set the cap near one decision per slot plus a small margin.
-- At the cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never compress a decision's prose to fit, and never pack two decisions under one heading, which the count cannot see.
+- State each cap in the record itself. A checker reads only these spellings, so a clause worded another way is reported and never gated:
+  - `This record holds at most <n> decisions.`
+  - `at most <n> words a decision`, counting a decision's prose below its heading, fenced lines left out
+  - `at most <n> risk bullets`, counting every list item under `## Risks / open questions`, nested ones included
+- The three can share one sentence, such as `This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets.` Each cap is the record's own, so a record stating none is measured and never gated, and the template states the entry cap alone so the other two are adopted on purpose.
+- Set the decision cap near one decision per slot plus a small margin, the word cap near what one trade takes to state, about 150, and the risk cap at what a reader holds in mind at once, about 6.
+- At the decision cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never pack two decisions under one heading, which the count cannot see.
+- At the word cap, cut a decision to the choice, the alternative that lost, the reason, and the revisit sentence. What it sheds is a mechanism or a measurement, which goes to the domain context entry it constrains, never under a second heading.
+- At the risk cap, drop what is no longer open before adding a risk.
 - Retire a decision by moving it to the domain context entry it constrains, not by deleting its reasoning.
-- A word count, for the file and for each decision, is read alongside the judgment when one is available, and it never gates.
+- The whole file's word count stays a report, read alongside the judgment, and never gates.
 - Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.
 
 ## Template

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/standards/requirements.md

@@ -36,6 +36,10 @@ Does not govern:
 
 Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, and `## Constraints`. Add `## Distribution` when the rule below applies. Add `## Worldview` when the project holds beliefs that shape every decision, and keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list. Add `## Premise` when the project exists to answer a question, stated as the question and what would count as an answer, never as the answer measured so far. Drop a section rather than pad it with filler.
 
+## Length
+
+This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter. The cap is the record's own, so a record stating none is measured and never gated. Set it near 600, and at the cap cut a goal or a constraint that no longer changes a decision before adding one.
+
 ## Lifecycle
 
 Once every entry in the MVP list, or in a later scope section, has shipped, delete the section. Git keeps the old text, and the document states the project as it stands. Do not annotate an entry as shipped and leave it in place. While any entry is unshipped, do not renumber the list or append to it.

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": [

package/tooling/cloudflare/configs/.github/workflows/deploy.yml

@@ -75,7 +75,7 @@ jobs:
 
       - name: Skip notice
         if: steps.secrets-check.outputs.skip == 'true'
-        run: echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping deploy. Run the deploy-cloudflare skill to finish setup."
+        run: echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping deploy. Run the deploy-app skill to finish setup."
 
       # This job builds nothing and still needs a toolchain. The checkout
       # below brings bun.lock, wrangler-action reads it, picks bun on the
@@ -110,7 +110,7 @@ jobs:
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           wranglerVersion: '3.90.0'
           # Fill in this project's Pages project name, set when the
-          # deploy-cloudflare skill runs wrangler pages project create.
+          # deploy-app skill runs wrangler pages project create.
           command: pages deploy dist --project-name=REPLACE_WITH_PROJECT_NAME --branch=${{ github.ref_name }}
 
       # `canon pr preview` reads this line out of the run log, so the marker is

package/tooling/cloudflare/reference.md

@@ -20,7 +20,7 @@ Three values in the seeded file have no generic default and are set once, right
 
 - The `paths:` filter under the `push` trigger. The shipped default is a single `src/**` glob. Widen it to cover every path the build reads when the build draws on catalogs or generated content living outside `src/`.
 - The `concurrency.group` name. The shipped default is `deploy-${{ github.ref_name }}`, which is enough for a single-deploy project. Give the `deploy` prefix a project-specific name only if the project runs more than one deploy workflow, and keep the ref suffix.
-- The Pages project name, written twice as `REPLACE_WITH_PROJECT_NAME`: once in the `--project-name` flag on the `wrangler pages deploy` command and once as `PROJECT_NAME` in the cleanup job. Set both to the name the `deploy-cloudflare` skill creates the Pages project under.
+- The Pages project name, written twice as `REPLACE_WITH_PROJECT_NAME`: once in the `--project-name` flag on the `wrangler pages deploy` command and once as `PROJECT_NAME` in the cleanup job. Set both to the name the `deploy-app` skill creates the Pages project under.
 
 ## Re-sync
 

package/claude/skills/deploy-cloudflare/REQUIREMENT.md

@@ -1,37 +0,0 @@
----
-name: deploy-cloudflare
-description: What the Cloudflare Pages setup gap is, which of the four manual steps this skill closes, and why the credential and the custom domain stay the operator's
----
-
-# Deploy Cloudflare requirement
-
-## Gap
-
-Without this skill, a Cloudflare Pages setup is a sequence performed from memory. Three of its four repeated acts touch a service rather than the tree, so no workflow file can absorb them, and one of the acts has already cost a broken deploy: the account ID displayed in the Cloudflare dashboard is truncated, and a value copied from there is wrong in a way that only shows up at deploy time.
-
-## Must
-
-- Create the Pages project through `wrangler pages project create`
-- Fetch the account ID from `wrangler`'s own authenticated session rather than have it typed or pasted
-- Stop for the operator to issue the API token and run `gh secret set CLOUDFLARE_API_TOKEN` themselves
-- Verify both secrets are present with `gh secret list` before continuing
-- Stop for the operator to attach the custom domain in the dashboard
-- Call `wrangler` and `gh` directly for every step those tools already cover
-
-## Must not
-
-- Accept a Cloudflare API token as input in any form. The toolkit verifies a secret exists, never what it contains.
-- Reimplement `wrangler pages project create` or `gh secret set` as a hand-built API call
-- Open a pull request or merge
-
-## Guards
-
-- `wrangler` not authenticated: stop and name the login command
-- `gh` not authenticated: stop and name the login command
-- A secret missing after the token stop: stop and name which one
-
-## Out of scope
-
-- Attaching a custom domain through the Cloudflare REST API instead of the dashboard. Measured absent from `wrangler pages` at plan time and the REST API was not read, so the dashboard stop stays for this pass.
-- Running the deploy itself once secrets and the domain are set. That is the seeded `tooling/cloudflare/configs/.github/workflows/deploy.yml` workflow, triggered by a push to main.
-- Reconfiguring an existing Pages project's build settings.