@erclx/canon 5.38.0 → 5.40.0

package/docs/workflow/zshrc-aliases.md

@@ -6,15 +6,13 @@ category: Workflow
 
 # Zshrc aliases for Claude Code
 
-Claude Code auto-discovers the toolkit plugin from `claude/.claude-plugin/plugin.json` when run inside the toolkit repository. Outside the toolkit, that discovery does not fire, so a separate set of aliases bakes in `--plugin-dir` explicitly. Two parallel sets cover both cases.
+Claude Code auto-discovers the toolkit plugin inside the toolkit repository. Outside it, the `clp` aliases pass `--plugin-dir` explicitly.
 
 ## The aliases
 
-`bun run bootstrap` installs this block. It owns the canonical copy in `scripts/core/bootstrap.sh`, appends it to `~/.zshrc` wrapped in the two marker comments below, and sets `TOOLKIT` to the cloned path. The markers are how a re-run recognizes its own block and skips.
+`bun run bootstrap` appends this block to `~/.zshrc` between the two marker comments and sets `TOOLKIT` to the cloned path. A re-run skips a block it finds and never updates it. To pick up a newer alias, delete the marked block and re-run, or paste the new lines in.
 
-Skipping means a re-run never updates a block already installed, so a shell that ran the bootstrap before the canonical block grew keeps whatever it got that day. To pick up an alias added since, delete the marked block and re-run the bootstrap, or paste the new lines into the block by hand.
-
-A block installed by hand before the managed one has no markers. Bootstrap detects that case through the `alias clp=` line instead, warns, and leaves the block untouched rather than appending a second copy. To switch over, delete the hand-rolled block and re-run the bootstrap.
+A hand-written block without markers is detected through its `alias clp=` line, and bootstrap warns and leaves it. Delete it and re-run to switch.
 
 ```zsh
 # >>> canon aliases >>>
@@ -34,46 +32,29 @@ alias clpac='clpa --cwd .'
 # <<< canon aliases <<<
 ```
 
-The block sits after any `PATH` mutations and the `claude` CLI install. Zsh expands aliases recursively on the first word, so `clr`, `clc`, `clw`, and `cls` inherit their base through `cl`, and `clpc`, `clps`, and `clpa` inherit `--plugin-dir` through `clp`. `clpac` inherits it one level further, through `clpa`. `$TOOLKIT` expands at invocation time, so updating the variable and re-sourcing reroutes all `clp` calls without touching the alias definitions.
-
-To opt out, delete the block between the two markers. Bootstrap re-adds it on the next run, so skip that step by running `bun install` and `bun link` yourself instead.
-
-The block itself works unchanged in bash, and what differs is the file it goes in and who writes it. Paste it into `~/.bashrc` by hand, since `bun run bootstrap` appends to `~/.zshrc` alone and a run from a bash shell installs nothing that shell reads. Bash re-checks the first word of an alias expansion the way zsh does, so the `cl` and `clp` chains below still inherit their base, and the `bun install` and `bun link` step above is the opt-out either shell takes.
+To opt out, delete the block and run `bun install` and `bun link` yourself. Bash takes the block unchanged in `~/.bashrc`, pasted by hand. Bootstrap writes `~/.zshrc` alone.
 
 ## What each one does
 
-`cl`, `clw`, and `cls` carry no explicit plugin dir and start a fresh session. Use them inside the toolkit repository, where Claude Code auto-discovers the plugin from `claude/.claude-plugin/plugin.json`. Loading `--plugin-dir` on top of auto-discovery registers every skill twice and produces duplicate entries in the slash command list.
-
-`clr` and `clc` resume a session rather than launching one, so auto-discovery never fires for them. A resume restores whatever plugin registration the session started with and recomputes nothing, which a bare `claude --resume` demonstrated by holding a stale registration through a full process restart until `--plugin-dir` was passed on the resume itself.
-
 - `cl`: plain session in the current directory
-- `clr`: opens the `/resume` picker scoped to the current directory. Trailing arguments filter by name. `clr auth` limits results to sessions containing "auth". Resuming does not reload the plugin, so reach for `clpc` when the session needs it.
-- `clc`: jumps straight into the most recent session for the current directory. No picker. Faster than `clr` when the terminal closed and you want back into the same session. Resuming does not reload the plugin here either.
-- `clw`: creates a worktree under `.claude/worktrees/<name>/` on a fresh branch and starts a Claude Code session in it. Pass the worktree name as the trailing arg: `clw feat-auth`.
-- `cls`: pins the session to Sonnet instead of the default Opus. Use for routine work where Opus cost is not justified.
+- `clr`: opens the `/resume` picker for the current directory. `clr auth` filters to sessions containing "auth".
+- `clc`: resumes the most recent session for the current directory, no picker
+- `clw`: creates a worktree under `.claude/worktrees/<name>/` on a fresh branch and starts a session there, as in `clw feat-auth`
+- `cls`: pins the session to Sonnet
 
-The `clp` family bakes in `--plugin-dir`. Use it outside the toolkit repository, where auto-discovery does not fire, and for any resume that needs the plugin.
+The `clp` family loads the plugin explicitly.
 
-- `clp`: session with the toolkit plugin loaded explicitly
-- `clpc`: jumps straight into the most recent session for the current directory with the plugin loaded. The `clp` mirror of `clc`, and the one resume that carries the plugin.
+- `clp`: session with the toolkit plugin loaded
+- `clpc`: resumes the most recent session with the plugin loaded
 - `clps`: `clp` pinned to Sonnet
-- `clpa`: opens the agent view with the plugin loaded, covering background sessions from every directory
-- `clpac`: the same view filtered to background sessions started under the current directory
+- `clpa`: opens the agent view with the plugin loaded, across every directory
+- `clpac`: the same view filtered to the current directory
 
 ## When to use which
 
-Use `cl` by default when working in the toolkit repository. Auto-discovery loads the plugin and the two-key alias keeps it short.
-
-Use `clp` in any other repository where you want the toolkit skills available. Without the flag, those repos do not load the plugin.
-
-Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session with `/model` to avoid restarting.
-
-Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the worktree mechanism, and [Parallel features](parallel-features.md) for fan-out rules.
-
-Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Reach for `clpc` over `clc` wherever the resumed session needs the plugin, inside the toolkit repository as well as outside it, since neither resume re-runs discovery.
-
-Use `clpa` to see what is running across every directory, and `clpac` when only the current project matters.
-
-## Why not a function
+Use `cl` inside the toolkit repository and `clp` in any other repository that needs the toolkit skills. A resume does not reload the plugin, so use `clpc` over `clc` wherever the resumed session needs it.
 
-A function with subcommand dispatch (`cl r`, `cl c`, `cl w foo`) was considered and rejected. It loses shell completion and adds a layer of indirection. Separate aliases are self-contained and the shared `cl`/`clp` prefixes make them easy to recall.
+- Use `cls` or `clps` for routine sessions, and `/model` to switch mid-session
+- Use `clw <name>` for features that take more than one session. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) and [Parallel features](parallel-features.md).
+- Use `clc` to resume without a picker and `clr` to pick by name
+- Use `clpa` for every directory and `clpac` for the current project

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.38.0",
+  "version": "5.40.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/canvas/client/inspector/fields.css

@@ -2,6 +2,10 @@
  * The inspector's own rules. Every value reads a chrome token, the same set
  * shell.css reads. Each field's glyph sits inside its box, so two fields share
  * a row without a label column eating the width.
+ *
+ * These rules share one class namespace with shell.css, where the Theme tab
+ * owns `.token`, so a new class here takes its own prefix, as `.token-option`
+ * does.
  */
 
 .inspector-section {

package/src/canvas/index.html

@@ -4,6 +4,12 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Canvas</title>
+    <!--
+      Bun's bundler resolves every href and src here at start. A root-relative
+      route the server answers, such as /api/icon.svg, fails with "Could not
+      resolve" and leaves / serving an empty 200, so main.tsx points the icon
+      at it on load.
+    -->
     <link rel="icon" href="data:," />
     <link rel="stylesheet" href="./client/shell.css" />
   </head>

package/src/claude/skills-reach.ts

@@ -13,8 +13,8 @@ import { SURFACE_ROOTS } from '@/roots/surface'
  * `src/`, `scripts/`, and bare `docs/` are deliberately absent. A body naming
  * one of those is describing the reader's own tree, so listing them would
  * report a correct citation on every run and bury the defect this measures.
- * `docs/agents/` is the exception, being the CLI contract pages that exist
- * here alone.
+ * `docs/agents/` is the exception, being the reference pages for verbs run by
+ * hand, which exist here alone.
  *
  * The context folder carries both surface-root spellings, since this list
  * decides whether a shipped body names this repository's own tree and a body

package/src/cli/ui.ts

@@ -162,6 +162,8 @@ export async function select<Value>(opts: {
   message: string
   options: { value: Value; label: string; hint?: string }[]
   nonInteractiveDefault?: boolean
+  /** Replaces the "Pass an argument" clause of the TTY refusal. */
+  ttyHint?: string
 }): Promise<Value> {
   const { message, options } = opts
   const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
@@ -196,7 +198,7 @@ export async function select<Value>(opts: {
   return new Promise<Value>((resolve) => {
     if (!process.stdin.isTTY) {
       process.stderr.write(
-        `${GREY}│${NC} ${RED}✗${NC} ${message} requires a TTY. Pass an argument or set CANON_NON_INTERACTIVE=1.\n${GREY}└${NC}\n`,
+        `${GREY}│${NC} ${RED}✗${NC} ${message} requires a TTY. ${opts.ttyHint ?? 'Pass an argument'} or set CANON_NON_INTERACTIVE=1.\n${GREY}└${NC}\n`,
       )
       process.exit(1)
     }

package/src/commands/canvas.ts

@@ -77,6 +77,11 @@ const CLIENT_DEPS = ['preact', '@preact/signals'] as const
  * the bundler then answers `/` with an empty page rather than an error. The
  * caller passes the package root the binary runs from, never the served
  * project's, so a global install serving a target finds its own copies.
+ *
+ * `Bun.resolveSync` and `createRequire(...).resolve` fall back to Bun's global
+ * install cache when no ancestor of the starting directory holds a
+ * `node_modules`, so a presence check from such a directory passes where the
+ * bundler fails. The package root always sits under one.
  */
 export function missingClientDeps(from: string): Refused | undefined {
   const missing = CLIENT_DEPS.filter((name) => {
@@ -161,6 +166,24 @@ export function register(program: Command): void {
         'it, and layout.json beside them holds each frame box. Edit a frame by',
         'editing its file, and an open canvas reloads that frame.',
         '',
+        'Reasons, on stderr or in the JSON record:',
+        '  no-root                no .canon/canvas/ folder under the root',
+        '  no-page, no-frame      the target is not on disk',
+        '  invalid-name           a name or target breaks the page or frame form',
+        '  invalid-size           a width or height is not a whole number of pixels',
+        '  invalid-position       an x or y is not a whole number',
+        '  exists                 the page or frame is already there',
+        '  malformed-layout       layout.json does not read as a frame map',
+        '  busy                   another write holds the page',
+        '  invalid-address        an element address is not a path of positions',
+        '  address-mismatch       the file builds elements the address does not',
+        '  stale-address          the file changed since the address was served',
+        '  invalid-edit           an edit key or value is not one the writer takes',
+        '  not-text-only          text targets an element holding other elements',
+        '  missing-client-deps    preact or @preact/signals does not resolve, so run bun install',
+        '  no-server              no canvas server answers at the address',
+        '  capture-failed         a frame did not render, with the font or browser reason',
+        '',
         'Examples:',
         '  canon canvas serve',
         '  canon canvas page add drafts',

package/src/commands/capture.ts

@@ -58,6 +58,20 @@ export function register(program: Command): void {
       '--width <px>',
       'Viewport width in pixels, so a media query resolves at that width',
     )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The selector has no default, since the element to crop to belongs to the',
+        'page. Each element holding text inside it must resolve its first font',
+        'family, and a generic keyword such as monospace or system-ui fails,',
+        'since it resolves differently on each machine. The user agent sets',
+        'monospace on pre, code, kbd, and samp, so each needs its own',
+        'font-family. --width takes one whole number and sets the viewport, so',
+        'run it once per breakpoint with its own --out.',
+        '',
+      ].join('\n'),
+    )
     .action(
       async (
         source: string,

package/src/commands/claude.ts

@@ -319,8 +319,13 @@ export function register(program: Command): void {
         '  0  the file was read',
         '  1  refused, with the reason on stderr',
         '',
+        'Reasons:',
+        '  no-claude-md  the tree has no always-loaded file',
+        '  no-rules      no path-scoped rule under .claude/rules/, so every path would',
+        '                report as uncovered',
+        '',
         'Reports rather than gates. Whether a bullet belongs in a rule is the',
-        'judgment canon/context/context-model/overview.md states, and naming a path is evidence for it',
+        'judgment canon/context/context-model.md states, and naming a path is evidence for it',
         'rather than the answer.',
         '',
         'Examples:',
@@ -432,6 +437,8 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  a skill folder carries no REQUIREMENT.md',
         '',
+        'Refuses when neither claude/skills/ nor .claude/skills/ resolves.',
+        '',
         'Only a missing REQUIREMENT.md sets a failing exit code. Name, description,',
         'folder, and requirement-section findings are advisory.',
         '',
@@ -460,6 +467,10 @@ export function register(program: Command): void {
         '  0  history was read, whether or not a body moved',
         '  1  the question could not be answered, with the reason on stderr',
         '',
+        'Refuses on an absent shipped corpus, an absent repository, and a ref',
+        'matching no commit, each with its own reason. A target loading the',
+        'plugin from a marketplace cache has no history, so it refuses there.',
+        '',
         'A moved body means the file changed, not that a session holds a stale',
         'copy. Passing a ref older than the oldest load over-reports, which is',
         'the safe direction. Confirm a name by reading the body.',
@@ -502,6 +513,8 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  at least one citation is unqualified',
         '',
+        'Refuses a tree carrying neither claude/skills/ nor .claude/skills/.',
+        '',
         'Reports rather than gates. A toolkit-scoped instruction is sometimes',
         'meant for a session in this repository, so the verdict is a reading',
         'and the repair is to name the owner in the sentence.',

package/src/commands/context.ts

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
   type ContextAuditRefusal,
@@ -12,14 +12,22 @@ import {
   matchesSiblings,
   measureFolders,
   extraSections,
+  GOTCHA_CAP,
+  LAYOUT_BULLET_CAP,
+  LAYOUT_PARAGRAPH_CAP,
   missingSections,
+  OTHER_FOLDERS,
   PROVENANCE_FOLDER,
   ALLOWED_SECTIONS_BY_FOLDER,
   REQUIRED_SECTIONS,
   REQUIRED_SECTIONS_BY_FOLDER,
   requiredSections,
+  RETIRED_SECTIONS_BY_FOLDER,
+  shapeFindings,
   type ExtraSectionFinding,
   type SectionFinding,
+  type ShapeFinding,
+  type ShapeIssue,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
 import {
@@ -49,6 +57,8 @@ import {
   resolveFolders,
 } from '@/context/folders'
 import { isGating } from '@/context/gate'
+import { isShapeGated, SHAPE_GATED_FOLDERS } from '@/context/shape-gated'
+import { currentWorktreeRoot } from '@/git/worktree'
 import {
   isOverWordCap,
   measureRequirements,
@@ -103,7 +113,7 @@ export function register(program: Command): void {
     .option('--citations-only', 'Run the gating citation check alone')
     .option(
       '--gate',
-      'Also fail on a missing required section or index drift, the findings that are facts',
+      'Also fail on a missing required section, an H2 outside the set, a shape break in a gated folder, or index drift, the findings that are facts',
     )
     .addHelpText(
       'after',
@@ -118,10 +128,13 @@ export function register(program: Command): void {
         'stating a word cap gates past it, on any run except',
         '--citations-only, which never measures it. A record stating no',
         'cap is reported and never gated. --gate widens the gate to the',
-        'other two findings that are facts rather than judgments: a',
-        'missing required section and index drift. A context entry',
-        'requires Overview and Layout. Entry length, reference form,',
-        'table, and provenance are judgments under both.',
+        'findings that are facts rather than judgments: a missing',
+        'required section, an H2 outside the closed set, and index drift.',
+        'A context entry requires Overview and Layout and allows Gotchas.',
+        'A shape break, such as a Decisions section or a sixth gotcha, is',
+        'reported everywhere and gated only under a shape-gated folder.',
+        'Entry length, reference form, table, and provenance are',
+        'judgments under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `canon markdown audit` measures them.',
@@ -644,6 +657,15 @@ async function runAudit(
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
   const extras = gateOnly ? [] : extraSections(entries)
+  // The gated prefixes name paths from the repository root, while an entry's
+  // path runs from the audit root, which is a seed tree's own root when one is
+  // passed. Resolving here keeps a seed tree listed under its toolkit path.
+  const top = gateOnly ? root : await currentWorktreeRoot(root)
+  const shape = gateOnly
+    ? []
+    : shapeFindings(entries, (rel) =>
+        isShapeGated(relative(top, join(root, rel))),
+      )
   const length = gateOnly ? undefined : lengthFindings(entries)
   // Absent under `--citations-only` and null when the project carries no
   // record. A run that never looked and a project with nothing to look at are
@@ -658,6 +680,7 @@ async function runAudit(
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
     reportSections(sections, extras, folders)
+    reportShape(shape)
     reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
@@ -696,6 +719,7 @@ async function runAudit(
         length,
         missingSections: sections,
         extraSections: extras,
+        shapeFindings: shape,
         indexDrift: drift,
         // Null says the run opened the project and found no record, which a
         // target that never wrote one is entitled to. Absent says the run
@@ -711,6 +735,11 @@ async function runAudit(
           // caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
           allowedSectionsByFolder: ALLOWED_SECTIONS_BY_FOLDER,
+          retiredSectionsByFolder: RETIRED_SECTIONS_BY_FOLDER,
+          gotchaCap: GOTCHA_CAP,
+          layoutBulletCap: LAYOUT_BULLET_CAP,
+          layoutParagraphCap: LAYOUT_PARAGRAPH_CAP,
+          shapeGatedFolders: SHAPE_GATED_FOLDERS,
         },
       })}\n`,
     )
@@ -722,6 +751,7 @@ async function runAudit(
       requirements !== undefined && isOverWordCap(requirements),
     sections,
     extraSections: extras,
+    shape,
     drift,
     widened,
   })
@@ -958,7 +988,7 @@ function reportSections(
   logInfo(
     `The set is closed: ${Object.entries(ALLOWED_SECTIONS_BY_FOLDER)
       .map(([name, set]) => `canon/${name}/ allows ${set.join(', ')}`)
-      .join('. ')} as H2. Any other topic is an H3 under one of them.`,
+      .join('. ')} as H2. A folder is an H3 under Layout.`,
   )
 
   if (extras.length === 0) {
@@ -974,6 +1004,75 @@ function reportSections(
   )
 }
 
+/** Characters of a paragraph the report quotes, enough to find it by. */
+const QUOTE_WIDTH = 60
+
+function clip(text: string): string {
+  return text.length > QUOTE_WIDTH ? `${text.slice(0, QUOTE_WIDTH)}...` : text
+}
+
+/** How each shape break reads in the report. */
+function readIssue(issue: ShapeIssue): string {
+  switch (issue.kind) {
+    case 'retired-section':
+      return `retired section: ${issue.text}`
+    case 'gotcha-count':
+      return `${issue.count ?? 0} gotchas, past ${GOTCHA_CAP}`
+    case 'gotcha-heading':
+      return `heading inside Gotchas: ${issue.text}`
+    case 'gotcha-paragraph':
+      return `paragraph inside Gotchas: ${clip(issue.text)}`
+    case 'layout-heading':
+      return `Layout H3 titled neither a path nor ${OTHER_FOLDERS}: ${issue.text}`
+    case 'layout-bullets':
+      return `${issue.count ?? 0} bullets under ${issue.text}, past ${LAYOUT_BULLET_CAP}`
+    case 'layout-paragraphs':
+      return `${issue.count ?? 0} paragraphs under ${issue.text}, past ${LAYOUT_PARAGRAPH_CAP}`
+    case 'layout-depth':
+      return `heading below H3 under Layout: ${issue.text}`
+  }
+}
+
+/**
+ * Names each entry breaking the section shape, gated ones first, and states
+ * which prefixes gate on every run, since an empty gated list and a corpus that
+ * conforms would otherwise print the same report.
+ */
+function reportShape(shape: readonly ShapeFinding[]): void {
+  logStep('Shape')
+
+  logInfo(
+    SHAPE_GATED_FOLDERS.length === 0
+      ? 'No folder is shape-gated yet, so every shape break reports and none gates.'
+      : `Gated under --gate: ${SHAPE_GATED_FOLDERS.join(', ')}. A break elsewhere reports and never gates.`,
+  )
+
+  if (shape.length === 0) {
+    logInfo('Every entry holds the section shape.')
+    return
+  }
+
+  const gated = shape.filter((finding) => finding.gated)
+  if (gated.length > 0) {
+    logWarn(
+      `${gated.length} gated ${gated.length === 1 ? 'entry' : 'entries'} breaking the shape`,
+    )
+  }
+  logInfo(
+    `${shape.length} ${shape.length === 1 ? 'entry' : 'entries'} breaking the shape in all`,
+  )
+  pipeOutput(
+    [...gated, ...shape.filter((finding) => !finding.gated)]
+      .map(
+        (finding) =>
+          `${finding.rel}${finding.gated ? '  gated' : ''}\n${finding.issues
+            .map((issue) => `  :${issue.line}  ${readIssue(issue)}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 /** How each question reads in the report, in the standard's own order. */
 const QUESTION_LABEL: Record<LengthQuestion, string> = {
   domain: 'one domain',

package/src/commands/demo.ts

@@ -76,6 +76,12 @@ export function register(program: Command): void {
         'wait condition, and the timing a beat lacks, and the timing is a',
         'starting point you tune, which is why a recompile refuses to overwrite.',
         '',
+        'Reasons:',
+        '  draft-missing        no file at the draft path',
+        '  draft-unreadable     no beat sheet in the draft, or a sheet with no beats',
+        '  plan-exists          a plan is already there and --force was not passed',
+        '  plan-unresolved      a URL or a target is still empty, named field by field',
+        '',
         'Exit codes:',
         '  0  a plan was written',
         '  1  refused, with the reason on stderr',
@@ -114,9 +120,20 @@ export function register(program: Command): void {
         'Writes mp4 beside the webm when ffmpeg is on PATH, and skips it',
         `otherwise without failing the run. Install it with: ${INSTALL_CONVERTER}`,
         '',
+        'Beside the webm it writes <video>.timeline.json, an entries array with',
+        'one entry per step carrying index, kind, and startMs and endMs from the',
+        'first frame. A click, fill, or hover entry adds box, the target in',
+        'viewport pixels. The still is the hero beat, or the last beat.',
+        '',
         'A gif is opt-in behind --gif, since it is far larger than the webm',
         'and only a host that strips video needs one. GitHub is that host.',
         '',
+        'Reasons:',
+        '  no-output-requested  --no-video with --no-still, which would write nothing',
+        '  plan-unreadable      the plan is not JSON, or a step names a kind nothing drives',
+        '  browser-missing      the browser binary is not installed',
+        '  engine-missing       the browser package did not resolve',
+        '',
         'Exit codes:',
         '  0  the recording and the still were written',
         '  1  refused, with the reason on stderr',
@@ -149,6 +166,11 @@ export function register(program: Command): void {
         'Needs ffmpeg on PATH, the same binary demo run already shells to for',
         `mp4 and gif conversion. Install it with: ${INSTALL_CONVERTER}`,
         '',
+        'Reasons:',
+        '  video-missing        no file at the video path',
+        '  converter-missing    ffmpeg is not on PATH, so nothing was extracted',
+        '  extraction-failed    ffmpeg exited non-zero, with its stderr in the message',
+        '',
         'Exit codes:',
         '  0  frames were written',
         '  1  refused, with the reason on stderr',

package/src/commands/deps.ts

@@ -56,6 +56,12 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  at least one advisory was published',
         '',
+        'Reasons:',
+        '  no-manifest  no package.json in the project',
+        '  no-lockfile  dependencies were never resolved, so install before auditing',
+        '  no-record    the lookup returned no record that parses, as an unreachable',
+        '               index does',
+        '',
         'Examples:',
         '  canon deps audit',
         '  canon deps audit --json',

package/src/commands/driver.ts

@@ -4,7 +4,7 @@ import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import type { DriverRefusal } from '@/driver/drive'
 import { describeViewport } from '@/driver/probes/viewport'
-import { PROBE_NAMES, readDriverPlan } from '@/driver/steps'
+import { PROBE_NAMES, readDriverPlan, type ProbeName } from '@/driver/steps'
 import type { PlanRefusal } from '@/driver/steps'
 import {
   intro,
@@ -55,6 +55,15 @@ const DRIVE_REFUSALS: Record<DriverRefusal, string> = {
   'drive-failed': 'The drive failed against a reachable page.',
 }
 
+const PROBE_NOTES: Record<ProbeName, string> = {
+  focus: 'keyboard focus that changes nothing visible, read after a Tab press',
+  details:
+    'a details panel off the viewport or a row under the tap minimum, read open',
+  'diagram-geometry':
+    'an SVG label outside its frame, covered by a fill, or on another label',
+  'diagram-strokes': 'an SVG label a stroke crosses, in either paint order',
+}
+
 export function register(program: Command): void {
   program
     .command('drive')
@@ -103,7 +112,24 @@ export function register(program: Command): void {
         `  ${INSTALL_BROWSER}`,
         '',
         'Probes:',
-        ...PROBE_NAMES.map((name) => `  ${name}`),
+        ...PROBE_NAMES.map(
+          (name) => `  ${name.padEnd(18)}${PROBE_NOTES[name]}`,
+        ),
+        '',
+        'Reasons:',
+        '  no-run-file         nothing readable at the run path',
+        '  unreadable-plan     the run file is not valid JSON',
+        '  no-steps            the run names no step',
+        '  no-probes           the run names an empty probe list',
+        '  unknown-probe       the run names a probe this build does not ship',
+        '  bad-step            a step is missing what the driver needs to perform it',
+        '  no-viewport         the run declares no viewport',
+        '  no-width            the viewport has no width to wrap at',
+        '  no-heights          the viewport names no height, which is never defaulted',
+        '  engine-missing      the browser engine is not installed in this project',
+        '  browser-missing     the engine is installed and its browser binary is not',
+        '  server-unreachable  nothing answered at the URL, so no state was reached',
+        '  drive-failed        the drive failed against a reachable page',
         '',
         'Step kinds:',
         '  click <target>   press the first element the selector matches',