@erclx/canon 4.65.0 → 4.67.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.67.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/commands.md

@@ -51,6 +51,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon records push`             | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                                                                                                                                                                             |
 | `canon records pull`             | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                                                                                                                                                                                |
 | `canon migrate rename`           | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                                                                                                                                                                   |
+| `canon migrate skill-names`      | Move the prefixed skill folders onto their two-word names and rewrite every citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                        |
 | `canon migrate records`          | Move the gitignored session records to `.canon/` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                         |
 | `canon migrate record-tree`      | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`)                                                                                                                                                               |
 | `canon migrate rule-layout`      | Move a target's installed rules from the flat `.claude/rules/<subdir>/` layout to `.claude/rules/canon/<subdir>/`, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                           |
@@ -138,7 +139,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `secrets`   | `scan`                                                                                                                                |
 | `deps`      | `audit`                                                                                                                               |
 | `labels`    | `audit`                                                                                                                               |
-| `migrate`   | `rename`, `records`                                                                                                                   |
+| `migrate`   | `rename`, `skill-names`, `records`                                                                                                    |
 | `autoship`  | `classify`                                                                                                                            |
 | `pr`        | `key-changes`, `head`, `checks`                                                                                                       |
 | `audits`    | `run`, `list`                                                                                                                         |
@@ -153,6 +154,8 @@ Common patterns:
 
 `migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
 
+`migrate skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then.
+
 `migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
 
 A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the nearest non-blank line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.

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/target-projects.md

@@ -173,6 +173,25 @@ canon migrate rule-layout --write --json
 
 The first line reports the plan and the second applies it, relocating each rule and carrying an edited one's recorded hash forward so it still reports as edited on the next sync rather than reading clean. Run it once, ahead of `canon gov sync` or `canon gov install`, on any project scaffolded before this move landed.
 
+### Rename the skill citations, once
+
+Twenty-five plugin skills dropped their `claude-` prefix for two-word names, so `canon:claude-docs` answers as `canon:docs-fold` and `canon:claude-tasks` as `canon:task-board`. A project that installed governance or tooling before that release holds files naming the old ones, and the plugin answers to none of them.
+
+Two of those files run rather than sit there. `.husky/post-merge` prints a command for a person to type, and `.claude/hooks/pr-create-log.sh` hands a session a message naming a skill, so a stale copy tells someone to invoke something that no longer exists. A rule under `.claude/rules/canon/core/` names skills too, though a rule is read rather than run.
+
+Resync what the toolkit owns, then sweep what the project wrote:
+
+```bash
+canon gov sync
+canon tooling sync <stack> . --write
+canon migrate skill-names --json
+canon migrate skill-names --write --json
+```
+
+Run the second line once per stack the project holds, since the two hooks above arrive from different ones. The third reports the plan and the fourth applies it.
+
+The order carries the reason. A sync replaces each toolkit-owned copy with one already carrying the new names, and the sweep afterwards reaches the prose the project wrote itself. Sweeping first rewrites those installed files in place, which moves them off the hash the install recorded, so the next sync reads them as edited by the project and leaves them alone.
+
 ### Check first
 
 `canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.

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.67.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) {