@erclx/canon 4.65.0 → 4.66.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.65.0",
+  "version": "4.66.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-frames-read/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: canon-frames-read
+description: Why a recording gets read back through numbered frames rather than left for a person to open, and why the report stops at description and never reaches a verdict
+---
+
+# Canon frames read requirement
+
+## Gap
+
+`ffmpeg` already ships as a dependency of the demo path, converting the raw recording to mp4 and gif, but nothing reads a recording back today. A demo run's own output is verified only when a person opens the video by hand, so a broken recording ships until someone happens to look.
+
+## Must
+
+- Call `canon demo frames <video> --json` rather than reading the video any other way
+- Read every path the record's `frames` array names, in order, with the Read tool
+- Report one plain description per frame, covering the visible UI state, on-screen text, cursor position, and what changed since the frame before it
+- Branch on the record's `reason` for a refusal (`video-missing`, `converter-missing`, `extraction-failed`) and report it rather than guessing what the recording shows
+
+## Must not
+
+- Write a pass-fail judgment, a "looks correct" line, or a "looks broken" line anywhere in the report. A frame read is evidence a person weighs, not a verdict this skill hands them.
+- Drive the application. This skill only reads files the verb already wrote.
+- Edit, trim, or otherwise modify the recording.
+- Assume this skill's own invocation frequency needs no check. Nothing names it as a step after `canon demo run` beyond an operator typing it or a body pointing here by hand, so a review pass some months in should read that back rather than take it on faith.
+
+## Guards
+
+- No recording path given: stop rather than guessing which video to read
+
+## Out of scope
+
+- Recording the video itself, which `canon demo run` owns
+- Judging whether the recording is correct, which nothing in the toolkit does yet
+- Sampling fewer frames than the verb's `--fps` default produces, since nothing has measured a long or high-fps recording as a real problem yet

package/claude/skills/canon-frames-read/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: canon-frames-read
+description: Pulls numbered still frames from a recorded video through `canon demo frames`, reads each one with the Read tool, and reports one plain description per frame. Never judges the recording, since a frame read is evidence rather than a verdict. Use when asked to "check the recording", "read the demo frames", "see what the video shows", or right after `canon demo run` writes a video and nobody has opened it yet. Do NOT use to record the video, which is `canon-record`, or to state whether the recording looks correct or broken, which is out of scope for every surface in the toolkit today.
+---
+
+# Canon frames read
+
+## Guards
+
+- If no recording path is given, stop: `❌ No recording path. Pass the video canon demo run wrote.`
+- Never write a pass-fail judgment, a "looks correct" line, or a "looks broken" line, anywhere in the report. A frame read is evidence a person weighs, not a verdict this skill hands them.
+- Never drive the application. Everything this skill touches is the frame files the verb already wrote, and it opens no browser and clicks nothing.
+- Never edit, trim, or otherwise modify the recording. The frames verb writes new files beside it, and this skill only reads what that writes.
+
+## Step 1: extract frames
+
+Run:
+
+```bash
+canon demo frames <video> --json
+```
+
+Branch on the record's `reason` rather than the exit code:
+
+- `video-missing`: report that the path does not resolve and stop.
+- `converter-missing`: report that ffmpeg is not installed and stop. `canon demo frames --help` names the install line.
+- `extraction-failed`: report the record's `message` and stop.
+- No `reason` key, meaning frames were written: continue to Step 2 with the record's `frames` array.
+
+## Step 2: read every frame
+
+Read each path in `frames`, in array order, with the Read tool. Do not skip any and do not sample a subset, since a gap in the sequence is a gap in what the report covers.
+
+## Step 3: report
+
+One numbered list entry per frame, each a plain description of what is on screen: the visible UI state, on-screen text, cursor position, and anything that changed from the entry before it. Skip a frame that is identical to its predecessor rather than repeating the same sentence.
+
+```markdown
+1. <plain description of frame 1>
+2. <plain description of frame 2>
+   ...
+```
+
+Close with the frame count and the source video path. Say nothing about whether the recording succeeded or looks right. That call belongs to whoever reads the report.
+
+Say so plainly if `canon demo frames` is not available, rather than reading the video some other way. The verb ships with the CLI and this skill ships with the plugin, so a project carrying one and not the other is a real state.

package/claude/skills/claude-worktree/SKILL.md

@@ -118,14 +118,28 @@ A linked worktree is a second working directory over one repository, and every e
 
 Report the state on one line. Do not install. Entering a worktree to read is as common as entering one to run, and an install is slow, needs a network, and picks an ecosystem on the session's behalf.
 
-Read the worktree root and evaluate node and python independently, each emitting its own line regardless of the other's state:
+Read the worktree root and evaluate node and python independently against a literal presence test, each emitting its own line regardless of the other's state:
 
-- Node. `package.json` present, `node_modules/` missing: `Dependencies are not installed. Run <install> before any build, test, or server command.` Take `<install>` from the lockfile beside the manifest, and use `bun install` when no lockfile names one. `package.json` present with `node_modules/` alongside it: `Node dependencies are installed.`
-- Python. A `pyproject.toml` or `requirements.txt` present, `.venv/` missing: `No virtual environment. Create and populate one before running anything.` Either manifest present with `.venv/` alongside it: `Python dependencies are installed.`
+- Node. `[ -f package.json ] && [ ! -d node_modules ]`: `Dependencies are not installed. Run <install> before any build, test, or server command.` `[ -f package.json ] && [ -d node_modules ]`: `Node dependencies are installed.`
+- Python. `{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } && [ ! -d .venv ]`: `No virtual environment. Create and populate one before running anything.` `{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } && [ -d .venv ]`: `Python dependencies are installed.`
+
+`[ -d node_modules ]` reads a symlinked `node_modules` as present, which is the correct read rather than a regression.
 
 Name the ecosystem in both installed lines rather than leaving `Dependencies are installed.` unqualified. Both checks can fire on one project, so an unqualified line reported the same sentence twice for a dual-root project with both folders present, and a reader could not tell which half each line answered.
 
-Emit the closing line only when neither manifest is present, tested directly rather than reached by falling through the two checks above unmatched: `No package manifest, so there is nothing to install.` A dual-root project matches both checks above, and a fallthrough test would route it here by accident.
+Take `<install>` from the lockfile beside the manifest, checked in this order, first match wins:
+
+| Lockfile                  | Install command |
+| ------------------------- | --------------- |
+| `bun.lock` or `bun.lockb` | `bun install`   |
+| `pnpm-lock.yaml`          | `pnpm install`  |
+| `yarn.lock`               | `yarn install`  |
+| `package-lock.json`       | `npm install`   |
+| none of the above         | `bun install`   |
+
+The order matters only when more than one lockfile sits beside the manifest, such as a project mid-migration between package managers. It is fixed rather than derived from anything about the project, so a reader hitting that rare case checks which manager the project actually uses rather than trusting the row the table picked first.
+
+Emit the closing line only on its own direct test, run ahead of the two checks above rather than reached by falling through them unmatched: `[ ! -f package.json ] && [ ! -f pyproject.toml ] && [ ! -f requirements.txt ]`: `No package manifest, so there is nothing to install.` A dual-root project matches both checks above, and a fallthrough test would route it here by accident.
 
 The closing line is what keeps the step honest on a stack this skill cannot read. Entry is not stack-aware, and silence is indistinguishable from a check that passed.
 

package/docs/agents/demo.md

@@ -1,6 +1,6 @@
 ---
 title: Demo
-description: Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, the pointer the recording paints, and what each refusal reports
+description: Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
 ---
 
 # Demo
@@ -13,6 +13,7 @@ Two verbs, and they are separate because the artifact between them is edited.
 canon demo compile .canon/tmp/screencast/inline-edit.md
 canon demo run demos/inline-edit.json
 canon demo run demos/inline-edit.json --cursor ~/cursors/theme --out assets
+canon demo frames demos/inline-edit.webm --fps 2
 ```
 
 ## The draft and the plan are different files
@@ -53,6 +54,18 @@ When `ffmpeg` is on PATH, the run also writes an mp4 beside the webm, since webm
 
 A step waits on its `waitFor` selector becoming visible and then holds for its own `holdMs`, which is what puts a finished state on screen long enough to read. `navigate` uses the plan's URL unless the step names its own.
 
+## What frames does
+
+`canon demo frames` pulls numbered PNG stills back out of a recorded video through the same `ffmpeg` binary the mp4 and gif conversion already shells to. Nothing reads a recording back today, so a broken one ships until a person opens it, and this verb is what a skill calls to read one instead. It writes one frame a second by default, sampling at a rate matched to how long a tuned recording runs rather than at a rate tuned for any one clip. Frames land beside the video by default, named `<video-basename>-frame-<NNN>.png`, so they fall under the same `demos/*.png` gitignore entry the still already uses.
+
+| Option            | Behavior                                                 |
+| ----------------- | -------------------------------------------------------- |
+| `-o, --out <dir>` | Directory to write frames into, default beside the video |
+| `--fps <n>`       | Frames extracted per second of video, default `1`        |
+| `--json`          | Add a record on stdout carrying every frame path written |
+
+`canon-frames-read` is the routed way to call this verb and read the frames back: it runs the verb, reads each returned frame with the Read tool, and reports one plain description per frame. It never renders a verdict, since a frame read is evidence a person weighs rather than a pass or fail this toolkit states on their behalf.
+
 ## The pointer is painted inside the page
 
 The browser engine offers an annotation of its own that draws a dot on the interacted element and a title naming the API call it made, and this recorder does not turn it on. It paints no cursor, so a run relying on it looks like the pointer teleports between targets, and the two overlays below supersede it: a real cursor where the dot is a marker, and the beat's narration where the title reads `Mouse move`. Running both put four overlays on the frame, and the two the engine drew were the two a viewer reads as noise.
@@ -77,6 +90,9 @@ Every refusal exits 1 and names its reason in the `--json` record, so a skill br
 | `plan-unreadable`     | The plan is not JSON, or a step names a kind nothing drives                         |
 | `browser-missing`     | The browser binary is not installed, with `install` carrying the command            |
 | `engine-missing`      | The browser package itself did not resolve                                          |
+| `video-missing`       | No file at the path given to `frames`                                               |
+| `converter-missing`   | `ffmpeg` is not on PATH, so `frames` extracted nothing                              |
+| `extraction-failed`   | `ffmpeg` exited non-zero, with `message` carrying its stderr                        |
 
 ## The browser reaches every target
 

package/docs/agents/index.md

@@ -16,7 +16,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
-- [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, the pointer the recording paints, and what each refusal reports
+- [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing

package/docs/workflow/ai-workflow.md

@@ -204,6 +204,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:setup-smoke`           | After `setup-verify` passes, to check the dev and preview servers, end-to-end tests, and the screenshot harness |
 | `canon:claude-design-extract` | Before the first UI feature, to draft `.claude/DESIGN.md`                                                       |
 | `canon:claude-diagram`        | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                            |
+| `canon:repo-metadata`         | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README          |
 
 ### Decide what to build
 
@@ -265,11 +266,13 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Run several tracks at once
 
-| Skill                      | When to use                                                                    |
-| -------------------------- | ------------------------------------------------------------------------------ |
-| `canon:claude-orchestrate` | To assert the control session that owns the queue and reviews each worker's PR |
-| `canon:session-resume`     | At the start of a session, to pick up what a previous one left                 |
-| `canon:session-map`        | At the close of a session, to write the handoff a compaction would destroy     |
+| Skill                      | When to use                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `canon:claude-orchestrate` | To assert the control session that owns the queue and reviews each worker's PR  |
+| `canon:claude-planner`     | To assert the planner role for a cold session writing one plan under one task   |
+| `canon:claude-worker`      | To assert the worker role for a cold session building one branch under one plan |
+| `canon:session-resume`     | At the start of a session, to pick up what a previous one left                  |
+| `canon:session-map`        | At the close of a session, to write the handoff a compaction would destroy      |
 
 ### Keep the project current with the toolkit
 
@@ -311,6 +314,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
 | `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
 | `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
+| `canon:canon-frames-read`   | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
 | `canon:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
 | `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
 | `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.65.0",
+  "version": "4.66.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/claude-workflow.ts

@@ -38,6 +38,11 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
       'Sketch out a plan for adding this new capability before we touch any code.',
     expect: 'claude-feature',
   },
+  {
+    prompt:
+      'The video just finished recording. Read it back and tell me what each part shows.',
+    expect: 'canon-frames-read',
+  },
   {
     prompt:
       'We need to measure this properly before committing to an approach.',

package/src/commands/claude.ts

@@ -50,7 +50,7 @@ import {
 } from '@/claude/settings'
 import { copyPreservingMode } from '@/copy'
 import { execScript } from '@/exec'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { recordDir } from '@/record-root'
 import { isDirectory, resolveTarget } from '@/target'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
@@ -620,15 +620,21 @@ async function sameContent(src: string, dest: string): Promise<boolean> {
  * human listing stays on the timeline. Only the human mode opens a frame.
  */
 async function runSeedsList(opts: SeedsListOptions): Promise<number> {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the two that return first and open none.
+  // One position cannot serve all three.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const listings = listSeeds(PROJECT_ROOT)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     const withContent = await readSeedContents(listings)
     process.stdout.write(`${JSON.stringify(withContent)}\n`)
     return 0
   }
 
   if (opts.names) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(
       listings.map((listing) => listing.target).join('\n') + '\n',
     )
@@ -637,6 +643,7 @@ async function runSeedsList(opts: SeedsListOptions): Promise<number> {
 
   const { GREY, NC } = palette(process.stderr)
   intro('canon claude')
+  if (mismatch !== undefined) logWarn(mismatch)
   logStep('Seed docs')
   for (const listing of listings) {
     logInfo(`${listing.target} ${GREY}← ${listing.source}${NC}`)
@@ -646,14 +653,20 @@ async function runSeedsList(opts: SeedsListOptions): Promise<number> {
 }
 
 function runSkillsList(opts: SkillsListOptions): number {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the two that return first and open none.
+  // One position cannot serve all three.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const listings = listSkills(PROJECT_ROOT)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(`${JSON.stringify({ skills: listings })}\n`)
     return 0
   }
 
   if (opts.names) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(
       listings.map((listing) => listing.name).join('\n') + '\n',
     )
@@ -661,6 +674,7 @@ function runSkillsList(opts: SkillsListOptions): number {
   }
 
   intro('canon claude')
+  if (mismatch !== undefined) logWarn(mismatch)
   logStep('Plugin skills')
   for (const listing of listings) {
     logInfo(listing.name)

package/src/commands/demo.ts

@@ -4,7 +4,12 @@ import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import { parseDraft } from '@/demo/beats'
 import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
-import { convertToGif, convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
+import {
+  convertToGif,
+  convertToMp4,
+  extractFrames,
+  INSTALL_CONVERTER,
+} from '@/demo/container'
 import { DEFAULT_CURSORS } from '@/demo/cursors'
 import { loadCursorTheme } from '@/demo/theme'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
@@ -34,6 +39,12 @@ interface RunOptions {
   readonly json?: boolean
 }
 
+interface FramesOptions {
+  readonly out?: string
+  readonly fps: string
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const demo = program
     .command('demo')
@@ -111,6 +122,38 @@ export function register(program: Command): void {
     .action(async (plan: string, opts: RunOptions) => {
       process.exitCode = await runDrive(plan, opts)
     })
+
+  demo
+    .command('frames')
+    .description('Pull numbered still frames from a recorded video')
+    .argument('<video>', 'Video written by canon demo run')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '-o, --out <dir>',
+      'Directory to write frames into, default beside the video',
+    )
+    .option('--fps <n>', 'Frames extracted per second of video', '1')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Needs ffmpeg on PATH, the same binary demo run already shells to for',
+        `mp4 and gif conversion. Install it with: ${INSTALL_CONVERTER}`,
+        '',
+        'Exit codes:',
+        '  0  frames were written',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon demo frames demos/inline-edit.webm',
+        '  canon demo frames demos/inline-edit.webm --fps 2 --out frames',
+        '',
+      ].join('\n'),
+    )
+    .action(async (video: string, opts: FramesOptions) => {
+      process.exitCode = await runFrames(video, opts)
+    })
 }
 
 function runCompile(draftPath: string, opts: CompileOptions): number {
@@ -344,6 +387,59 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
   return 0
 }
 
+async function runFrames(
+  videoPath: string,
+  opts: FramesOptions,
+): Promise<number> {
+  intro('canon demo frames')
+
+  const source = resolve(process.cwd(), videoPath)
+  if (!existsSync(source)) {
+    logStep('Video')
+    logError(`${videoPath} not found`)
+    outro()
+    emit(opts.json, { video: source, reason: 'video-missing' })
+    return 1
+  }
+
+  logStep('Video')
+  logInfo(display(source))
+
+  const outDir = opts.out ? resolve(process.cwd(), opts.out) : undefined
+  const fps = Number(opts.fps)
+
+  logStep('Frames')
+  const extracted = await extractFrames(source, outDir, { fps })
+  if (extracted.status === 'skipped') {
+    logError('ffmpeg is not installed, so no frames were written.')
+    logWarn(`Install it with: ${INSTALL_CONVERTER}`)
+    outro()
+    emit(opts.json, { video: source, reason: extracted.reason })
+    return 1
+  }
+  if (extracted.status === 'failed') {
+    logError(`frame extraction failed: ${extracted.reason}`)
+    outro()
+    emit(opts.json, {
+      video: source,
+      reason: 'extraction-failed',
+      message: extracted.reason,
+    })
+    return 1
+  }
+
+  for (const framePath of extracted.framePaths) logInfo(display(framePath))
+  logInfo(`${plural(extracted.framePaths.length, 'frame')} at ${fps} fps`)
+  outro()
+
+  emit(opts.json, {
+    video: source,
+    frames: extracted.framePaths,
+    fps,
+  })
+  return 0
+}
+
 type CursorChoice =
   | { status: 'ready'; value: typeof DEFAULT_CURSORS; label: string }
   | { status: 'failed'; reason: string }

package/src/commands/design.ts

@@ -9,11 +9,11 @@ import {
 import { buildDesignCss } from '@/design/css'
 import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
-import { intro, logAdd, logError, logInfo, outro, palette } from '@/ui'
+import { intro, logAdd, logError, logInfo, logWarn, outro, palette } from '@/ui'
 
 export function register(program: Command): void {
   const design = program
@@ -39,13 +39,21 @@ export function register(program: Command): void {
     .action(() => {
       const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
 
+      // The guard below catches a `PROJECT_ROOT` with no record at all, which
+      // is an installed package. It cannot catch a second real checkout that
+      // has one, so both paths carry the warning. It is a frame-interior line,
+      // so each emits it after its own opener rather than ahead of the branch.
+      const mismatch = checkoutMismatchWarning(process.cwd())
+
       // Both outputs resolve from `PROJECT_ROOT`, which is the installed
       // package directory when the CLI runs out of a target's `node_modules`.
       // The record is the one output that is already committed here and ships
       // with no package, so its absence is what separates the two.
       if (!existsSync(join(PROJECT_ROOT, DESIGN_DOCUMENT))) {
+        process.stderr.write(`${GREY}┌${NC}\n`)
+        if (mismatch !== undefined) logWarn(mismatch)
         process.stderr.write(
-          `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} No ${DESIGN_DOCUMENT} at ${PROJECT_ROOT}. Regen runs in the toolkit checkout, not against a target.\n${GREY}└${NC}\n`,
+          `${GREY}│${NC} ${RED}✗${NC} No ${DESIGN_DOCUMENT} at ${PROJECT_ROOT}. Regen runs in the toolkit checkout, not against a target.\n${GREY}└${NC}\n`,
         )
         process.exitCode = 1
         return
@@ -54,6 +62,7 @@ export function register(program: Command): void {
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Regenerate design source${NC}\n`,
       )
+      if (mismatch !== undefined) logWarn(mismatch)
       const result = regenDesign(PROJECT_ROOT)
       for (const path of [result.documentPath, result.cssPath]) {
         process.stderr.write(

package/src/commands/docs.ts

@@ -2,7 +2,7 @@ import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
 import { listTopics, readTopic, resolveTopic } from '@/docs/read'
 import { execScript } from '@/exec'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
 
 export function register(program: Command): void {
@@ -42,6 +42,9 @@ export function register(program: Command): void {
 function get(topic: string): number {
   intro('canon docs')
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const resolved = resolveTopic(PROJECT_ROOT, topic)
 
   if (!resolved) {

package/src/commands/gov.ts

@@ -8,7 +8,7 @@ import {
   type CountsReport,
   scanCounts,
 } from '@/counts/scan'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel, SCRATCH } from '@/record-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
@@ -203,8 +203,11 @@ export function register(program: Command): void {
         '',
       ].join('\n'),
     )
-    .action(async (opts: RegenOptions) => {
-      process.exitCode = await runRegen(opts)
+    .action(async (opts: RegenOptions, cmd: Command) => {
+      process.exitCode = await runRegen(
+        opts,
+        cmd.getOptionValueSource('root') === 'cli',
+      )
     })
 
   gov
@@ -1052,10 +1055,15 @@ function selectedSections(opts: ListOptions): {
  * untouched by it.
  */
 function runList(opts: ListOptions): number {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the `--json` path, which returns first and
+  // opens none. One position cannot serve both.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const catalog = buildGovCatalog(PROJECT_ROOT)
   const sections = selectedSections(opts)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(
       `${JSON.stringify({
         ...(sections.stacks ? { stacks: catalog.stacks } : {}),
@@ -1067,6 +1075,7 @@ function runList(opts: ListOptions): number {
   }
 
   intro('canon gov list')
+  if (mismatch !== undefined) logWarn(mismatch)
 
   if (sections.stacks) {
     logStep('Stacks')
@@ -1092,7 +1101,18 @@ function runList(opts: ListOptions): number {
  * the only work that stage does now. The installed set is readable on disk, so
  * printing it would only add noise to every `bun run check`.
  */
-async function runRegen(opts: RegenOptions): Promise<number> {
+async function runRegen(
+  opts: RegenOptions,
+  rootPassed: boolean,
+): Promise<number> {
+  // An operator naming `--root` names their own target on purpose, so only the
+  // default can silently regenerate against a checkout nobody is standing in.
+  // The value alone cannot separate the two, since the flag carries a default.
+  if (!rootPassed) {
+    const mismatch = checkoutMismatchWarning(process.cwd())
+    if (mismatch !== undefined) logWarn(mismatch)
+  }
+
   const result = await regenConsumedRules(resolve(opts.root ?? PROJECT_ROOT))
 
   if (!result.ok) {

package/src/commands/migrate.ts

@@ -31,7 +31,7 @@ import {
   type ScratchEvidencePlan,
   walkScratchEvidenceCorpus,
 } from '@/migrate/scratch-evidence'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { readStamp, stampedHashes } from '@/sync/stamp'
 import { logError, logInfo, logStep, logWarn, pipeOutput, plural } from '@/ui'
 
@@ -584,6 +584,9 @@ interface RuleLayoutOptions {
 async function runRuleLayout(opts: RuleLayoutOptions): Promise<number> {
   const root = opts.root ?? process.cwd()
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const files = await walkFlatRules(root)
   const hashes = stampedHashes(readStamp(root), 'governance')
   const catalog = new Set(indexSourceRules(PROJECT_ROOT).keys())

package/src/commands/sandbox.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { execScript } from '@/exec'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   assertedPercent,
   collectCensus,
@@ -286,6 +286,9 @@ function runCoverage(options: CoverageOptions): void {
 
   intro('canon sandbox coverage')
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const report = collectCoverage(PROJECT_ROOT)
 
   // A broken `exempt.toml` reads as a caller error, not as a crash. The parser
@@ -341,6 +344,9 @@ function runCheck(
 ): void {
   intro('canon sandbox check')
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const parsed = parseTarget(target)
   if (parsed === undefined) {
     logError('Invalid target. Use <category>:<command>, e.g. claude:docs.')

package/src/commands/snippets.ts

@@ -1,9 +1,9 @@
 import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { BASE_CATEGORY } from '@/snippets/categories'
 import { buildSnippetsCatalog } from '@/snippets/list'
-import { intro, logInfo, logStep, outro } from '@/ui'
+import { intro, logInfo, logStep, logWarn, outro } from '@/ui'
 
 const PASS_THROUGH_VERBS = ['create'] as const
 
@@ -42,14 +42,20 @@ export function register(program: Command): void {
  * emitted section headers and the pass-through above it owned the `┌`.
  */
 function runList(opts: ListOptions): number {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the `--json` path, which returns first and
+  // opens none. One position cannot serve both.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const catalog = buildSnippetsCatalog(PROJECT_ROOT)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(`${JSON.stringify(catalog)}\n`)
     return 0
   }
 
   intro('canon snippets list')
+  if (mismatch !== undefined) logWarn(mismatch)
 
   const showCategories = opts.entries !== true
   const showEntries = opts.categories !== true

package/src/commands/tooling.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { execScript } from '@/exec'
-import { findCheckoutMismatch, PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   injectConfigs,
   injectGitignore,
@@ -180,14 +180,20 @@ export function register(program: Command): void {
  * pass-through loop below skips the `intro` the shared helper carries.
  */
 function runList(opts: ListOptions): number {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the `--json` path, which returns first and
+  // opens none. One position cannot serve both.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const stacks = buildStackSummaries(PROJECT_ROOT)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(`${JSON.stringify({ stacks })}\n`)
     return 0
   }
 
   intro('canon tooling list')
+  if (mismatch !== undefined) logWarn(mismatch)
   logStep('Stacks')
   for (const summary of stacks) logInfo(describeStack(summary))
   outro()
@@ -229,6 +235,9 @@ function printReference(stack: string): number {
  * stack the way it drove `merge_gitignore` before.
  */
 function prepare(stack: string, target: string, skip?: string): Prepared {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   if (!stackExists(PROJECT_ROOT, stack)) {
     return { ok: false, error: `Stack not found: ${stack}` }
   }
@@ -268,13 +277,6 @@ async function runSync(
 ): Promise<number> {
   intro('canon tooling sync')
 
-  const mismatch = findCheckoutMismatch(process.cwd())
-  if (mismatch !== undefined) {
-    logWarn(
-      `Resolved via ${PROJECT_ROOT}, not the checkout at ${mismatch}. Run \`bun ${mismatch}/src/cli.ts tooling sync ...\` to sync against that checkout instead.`,
-    )
-  }
-
   if (opts.check === true && opts.write === true) {
     logWarn('Pass --check or --write, not both.')
     outro()

package/src/demo/container.ts

@@ -1,3 +1,4 @@
+import { existsSync, mkdirSync, rmSync } from 'node:fs'
 import { join, parse } from 'node:path'
 import { execa } from 'execa'
 
@@ -20,6 +21,15 @@ export type GifResult =
   | { status: 'skipped'; reason: 'converter-missing' }
   | { status: 'failed'; reason: string }
 
+export type FramesResult =
+  | { status: 'extracted'; framePaths: string[] }
+  | { status: 'skipped'; reason: 'converter-missing' }
+  | { status: 'failed'; reason: string }
+
+export interface ExtractFramesOptions {
+  readonly fps?: number
+}
+
 /**
  * Writes mp4 beside the webm rather than instead of it, since both stated use
  * cases are a `<video>` tag on a page the operator controls, where webm
@@ -122,3 +132,88 @@ export async function convertToGif(
   }
   return { status: 'converted', gifPath }
 }
+
+/**
+ * Written beside the video by default, so frames fall under the same
+ * `demos/*.png` gitignore entry the still already uses with no new rule
+ * needed. One frame a second by default, matched to the seconds-to-tens-of-
+ * seconds length a tuned recording runs, without a smarter sampling strategy
+ * nobody has asked for.
+ *
+ * The missing-binary and failure handling matches `convertToMp4` exactly: the
+ * recording already succeeded by the time this runs, so an optional step
+ * never fails the run.
+ *
+ * A prior extraction's frames are cleared before ffmpeg runs, not left for
+ * `-y` to overwrite. ffmpeg's `-y` only overwrites the indices this run
+ * produces, so a shorter re-extraction against the same video's stable
+ * output path (the plan's declared `output.video`, unchanged across
+ * re-records) would otherwise leave the previous run's tail in place,
+ * sorted into the returned list as if it were still current.
+ */
+export async function extractFrames(
+  videoPath: string,
+  outDir?: string,
+  opts: ExtractFramesOptions = {},
+  bin: string = CONVERTER_BIN,
+): Promise<FramesResult> {
+  const { dir, name } = parse(videoPath)
+  const targetDir = outDir ?? dir
+  const fps = opts.fps ?? 1
+  if (outDir) mkdirSync(outDir, { recursive: true })
+
+  if (existsSync(targetDir)) {
+    for (const stale of new Bun.Glob(`${name}-frame-*.png`).scanSync({
+      cwd: targetDir,
+      onlyFiles: true,
+    })) {
+      rmSync(join(targetDir, stale))
+    }
+  }
+
+  const pattern = join(targetDir, `${name}-frame-%03d.png`)
+  const result = await execa(
+    bin,
+    ['-y', '-i', videoPath, '-vf', `fps=${fps}`, pattern],
+    { reject: false },
+  )
+
+  if (result.failed && result.code === 'ENOENT') {
+    return { status: 'skipped', reason: 'converter-missing' }
+  }
+  if (result.exitCode !== 0) {
+    return {
+      status: 'failed',
+      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
+    }
+  }
+
+  return { status: 'extracted', framePaths: collectFrames(targetDir, name) }
+}
+
+/**
+ * The glob-and-sort step `extractFrames` reads its result from, pulled out so
+ * a test can drive it against a directory it wrote by hand rather than
+ * through a real extraction, which is the only way to reach the four-digit
+ * boundary below without an ffmpeg run long enough to produce one.
+ *
+ * ffmpeg's `%03d` pads to three characters and then widens rather than
+ * truncating, so a run producing 1000 or more frames writes `-1000.png`
+ * beside `-999.png`, and a lexicographic sort reads the wider name first.
+ * `frameIndex` sorts on the parsed number instead.
+ */
+export function collectFrames(targetDir: string, name: string): string[] {
+  return [
+    ...new Bun.Glob(`${name}-frame-*.png`).scanSync({
+      cwd: targetDir,
+      onlyFiles: true,
+    }),
+  ]
+    .sort((a, b) => frameIndex(a) - frameIndex(b))
+    .map((frame) => join(targetDir, frame))
+}
+
+function frameIndex(filename: string): number {
+  const match = filename.match(/-frame-(\d+)\.png$/)
+  return match ? Number(match[1]) : 0
+}

package/src/exec.ts

@@ -1,11 +1,15 @@
 import { join } from 'node:path'
 import { execa } from 'execa'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
+import { logWarn } from '@/ui'
 
 export async function execScript(
   script: string,
   args: string[],
 ): Promise<void> {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const scriptPath = join(PROJECT_ROOT, 'scripts', script)
   const result = await execa(scriptPath, args, {
     stdio: 'inherit',

package/src/project-root.ts

@@ -51,3 +51,20 @@ export function findCheckoutMismatch(startDir: string): string | undefined {
     dir = parent
   }
 }
+
+/**
+ * The warning line every verb that answers from `PROJECT_ROOT` emits when the
+ * caller's cwd sits inside a second checkout, or `undefined` when it does not.
+ *
+ * It returns the string rather than logging it so this module keeps no `@/ui`
+ * dependency and the wording is unit-testable on its own. The wording names
+ * both roots and no subcommand: the four chokepoints that carry it stand under
+ * eight-plus verbs each, so a per-verb suffix would cost a parameter at every
+ * call site to buy back one verb's exact string.
+ */
+export function checkoutMismatchWarning(cwd: string): string | undefined {
+  const mismatch = findCheckoutMismatch(cwd)
+  if (mismatch === undefined) return undefined
+
+  return `Resolved via ${PROJECT_ROOT}, not the checkout at ${mismatch}. Run \`bun ${mismatch}/src/cli.ts ...\` to answer from that checkout instead.`
+}

package/src/sync/engine.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { copyPreservingMode } from '@/copy'
+import { checkoutMismatchWarning } from '@/project-root'
 import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 import {
   type DomainHashes,
@@ -339,6 +340,9 @@ export async function runDomainSync(
 ): Promise<number> {
   intro(adapter.banner)
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const resolved = resolve(target)
 
   if (!isDirectory(resolved)) {

package/src/target.ts

@@ -1,6 +1,7 @@
 import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { logError, outro } from '@/ui'
+import { checkoutMismatchWarning } from '@/project-root'
+import { logError, logWarn, outro } from '@/ui'
 
 export function isDirectory(path: string): boolean {
   try {
@@ -23,6 +24,9 @@ export function resolveTarget(
   target: string,
   protectedRoot: string,
 ): string | number {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const resolved = resolve(target)
 
   if (!isDirectory(resolved)) {