@erclx/canon 5.39.0 → 5.41.0

package/docs/workflow/visual-design-workflow.md

@@ -6,147 +6,54 @@ category: Workflow
 
 # Visual design workflow
 
-Three tiers cover the range from prose-only design docs to a fully graphical design source of truth. Pick one per project based on how UI-heavy the work is, whether stakeholders review visuals, and whether a designer is involved. Tiers stack, so moving up does not invalidate work done at a lower tier.
-
-The tier framework sits alongside [Claude Design](../../wiki/claude/design.md), the one catalog page in this range. Excalidraw and the surrounding MCP and skill ecosystem are named inline below rather than catalogued separately. This page decides when to reach for what.
-
-[Claude Design](../../wiki/claude/design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool for tier 1 and tier 2. Reserve it for codebase extraction and the richly annotated handoff bundle.
+Three tiers run from prose-only design docs to a graphical source of truth, and tiers stack. [Claude Design](../../wiki/claude/design.md) is the ceiling tool for tiers 1 and 2.
 
 ## Tier 0: prose only
 
-The default. `canon/DESIGN.md` holds visual intent, being one Overview paragraph, at most three one-line rules a section, and a table naming what each color and shape role is for. Its lead names the stylesheet the values live in, since a hand-typed copy of them drifts from the CSS.
-
-Claude Code reads it and writes the implementation. Works for CLI tools, internal dashboards, admin panels, and backend-focused projects.
-
-### Seed shape
-
-The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships an intent template with a starting set of roles, each naming its custom property, and `claude/skills/canvas-board/references/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the parser reads, so they stay verbatim in either, while the rows are the project's own. The seed's lead asks for the project's own stylesheet, such as `src/styles/tokens.css` or a Tailwind `@theme` block, and falls back to `.claude/design/project/` only when the project has none.
-
-`canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design.md`.
-
-A project wanting a neutral starting point to override runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying an achromatic token set as custom properties and two components built on them. Greys run from near-black to near-white and the accent is monochrome, so the only palette the project renders is one it writes itself. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record the project wrote is its own, and the installed stylesheet is the toolkit's.
-
-A record generated from a token source carries the values in tables instead, which is the shape this toolkit's own record takes. There a cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
-
-### Tools
-
-- None beyond Claude Code itself
-- Playwright CLI optional for verifying journeys across routes and browser-only behavior. See [`test-craft`](../../claude/skills/test-craft/SKILL.md) for which layer a journey belongs at.
+The default. `canon/DESIGN.md` holds visual intent as one Overview paragraph, at most three one-line rules a section, and a table naming each color and shape role, with a lead naming the stylesheet. Claude Code alone suffices, and [`test-craft`](../../claude/skills/test-craft/SKILL.md) says which layer a Playwright journey belongs at.
 
-### Skills
+- The seed is `tooling/claude/seeds/canon/DESIGN.md`, and its column headers stay verbatim
+- `canon design render` previews it in `.canon/tmp/render/design/`
+- `canon design install` copies a neutral base to `.claude/design/base.css`, so override values in `.claude/design/project/`. See `canon/context/features/design.md`.
 
-#### Reviewing and measuring
+These skills cover the tier:
 
-- `canon:ui-checklist` for what a reviewer has to look at after UI changes, and what ships without a test
-- `canon:ux-audit` for UX gap detection on existing surfaces
-- `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
+- `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
+- `canon:draft-and-pick` drafts candidates as frames on the canvas and takes your pick
+- `canon:canvas-board` works a direction out as HTML frames you edit in the browser. Only the pick moves into `canon/DESIGN.md`.
+- `canon:draft-identity` drafts a logo mark and social card
 
-#### Drafting
-
-- `canon:draft-and-pick` for a call settled by looking, drafting several candidates as frames on the canvas and taking your pick
-- `canon:canvas-board` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
-- `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.
-- Anthropic's `frontend-design` plugin optional for light visual steering
-
-### When to pick
-
-- UI is not the core product
-- Design decisions are few and can be written as sentences
-- No designer on the project
-- Stakeholders review code or behavior rather than mockups
+Pick tier 0 when the UI is not the core product, decisions fit in sentences, and stakeholders review code.
 
 ## Tier 1: visual companion
 
-Prose stays as source of truth. Add a visual render as a feedback surface for the agent and for human review.
-
-- Excalidraw handles agent-drawn layouts when the round-trip canvas loop matters
-- Claude Design joins only when codebase extraction or the annotated handoff bundle is worth the ceiling cost
-
-Both produce derived artifacts, so human edits are review annotations rather than source changes.
-
-### Seed shape
-
-Same as tier 0. `DESIGN.md` stays human-maintained.
-
-Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in its own format. These are separate files from the toolkit's `canon/DESIGN.md` and are not synced with it. Treat impeccable's pair as its own source of truth for its commands, and the toolkit's `canon/DESIGN.md` as the source other toolkit skills read.
-
-### Tools
-
-- Excalidraw canvas server on localhost plus the community [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw) MCP shim, for projects that need an agent to draw, read back, and revise a canvas. MIT-licensed, plaintext JSON scene format. `describe_scene` and `get_canvas_screenshot` let the agent verify its own layout before claiming it is correct.
-- Playwright MCP ([`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp)) for browser-side verification, driven off the accessibility tree rather than screenshots.
-- Chrome DevTools MCP ([`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)) for live frontend debugging: performance traces, network inspection, and DOM and CSS inspection.
-- Claude Design as the ceiling option for codebase extraction or polished handoff bundles. See [Claude Design](../../wiki/claude/design.md).
+Prose stays the source of truth, with a visual render as a feedback surface. Human edits to these derived artifacts are review annotations.
 
-### Skills
+- Excalidraw canvas server plus the community [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw) MCP, where the agent draws, reads back, and revises
+- Playwright MCP ([`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp)) for browser checks off the accessibility tree
+- Chrome DevTools MCP ([`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)) for traces, network, DOM, and CSS
+- Claude Design for codebase extraction or a polished handoff bundle
+- A frontend design skill: [pbakaus/impeccable](https://github.com/pbakaus/impeccable), [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), or Anthropic's `frontend-design`
 
-- Everything from tier 0
-- A frontend design skill to steer visual quality. Pick one of [pbakaus/impeccable](https://github.com/pbakaus/impeccable), which bundles curated anti-pattern references and is the strongest default, [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), which maps product type to UI rules through a reasoning engine, or Anthropic's `frontend-design` plugin.
+Impeccable keeps its own root `DESIGN.md` and `PRODUCT.md`, separate from `canon/DESIGN.md`. Use Excalidraw for agent-driven layout iteration, and Claude Design for one extraction pass or the final handoff. Most projects pick one.
 
-### When to pick
-
-- UI is a meaningful part of the product but not the entire product
-- Stakeholders want to see layout proposals before code exists
-- Design decisions benefit from visual inspection
-- A single contributor owns both design and implementation
-
-### Excalidraw vs Claude Design in tier 1
-
-The two tools solve non-overlapping halves of the visual companion problem.
-
-Excalidraw gives the agent a canvas it can read back over MCP. Output is agent-facing and persists as a JSON file in the repo. Pick it when Claude Code needs to iterate on layouts autonomously, not when a human needs polished review artifacts.
-
-Claude Design reads the raw codebase without prose curation and produces a polished handoff bundle with chat history. Weekly quota makes it expensive, so reserve it for the extraction pass or the final handoff moment, not daily iteration.
-
-Most tier 1 projects pick one. Projects with a messy codebase and no curated `DESIGN.md` may want Claude Design once for the initial extraction.
+Pick tier 1 when stakeholders want layouts before code and one contributor owns design and implementation.
 
 ## Tier 2: visual as source of truth
 
-Design happens in a graphical tool. `canon/DESIGN.md` either regenerates from the graphical source or takes a secondary role as agent-facing summary. Implementation follows the graphical source, either through an MCP round-trip or a one-way handoff bundle. Fits teams with a dedicated designer or projects where design iteration outpaces code changes.
-
-### Seed shape
-
-`canon/DESIGN.md` becomes a generated artifact. A top-of-file note identifies the upstream source, either a Claude Design project ID or a Figma file URL. Manual edits in the seed carry a warning tag because they will not survive regeneration.
-
-### Tools
-
-- Figma desktop app with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture of a running Claude Code UI into editable Figma frames.
-- Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../../wiki/claude/design.md).
-- Playwright and Chrome DevTools MCPs as in tier 1
+Design happens in a graphical tool, and implementation follows it. `canon/DESIGN.md` becomes generated, with a top note naming the upstream Claude Design project ID or Figma file URL.
 
-### Skills
+- Figma desktop with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/) for teams with a designer already on Figma. It syncs both ways and captures a running UI into editable frames.
+- Claude Design with its Claude Code handoff bundle for teams without Figma. The handoff is one-way.
+- The Playwright and Chrome DevTools MCPs from tier 1
 
-- Everything from tier 1
-
-### When to pick
-
-- UI is the product or a major differentiator
-- A dedicated designer is on the project or will join
-- Design review happens in the graphical tool rather than in code
-- Design changes more often than implementation
-
-### Figma vs Claude Design in tier 2
-
-Figma wins when a dedicated designer already owns a Figma file, external collaborators expect Figma for review, or the workflow needs the agent to capture a running Claude Code UI and push it back as editable frames via Code to Canvas. Figma's MCP is bidirectional.
-
-Claude Design wins when nobody on the team has a Figma workflow yet and the handoff bundle with chat history is the intended implementation path. Claude Design's handoff is one-way, and its quota limits daily iteration, so it is most useful for the initial extraction pass and the final handoff moment rather than day-to-day design work.
+Pick tier 2 when the UI is the product, a designer owns it, and design changes more often than code.
 
 ## Decision guide
 
-Four questions. Each yes weighs toward a higher tier.
+Count yes answers to four questions. Zero or one is tier 0, two or three is tier 1, and four is tier 2.
 
 - Is the UI the product rather than a thin interface over a backend?
 - Do non-engineers review visual proposals before code exists?
 - Is there a dedicated designer, or will there be one?
 - Does design iterate independently of code?
-
-Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2.
-
-Resist over-tiering early. Moving up is cheap because tiers stack. Moving down means abandoning tooling and confusing collaborators.
-
-## References
-
-- [Claude Design](../../wiki/claude/design.md): first-party hosted design product and handoff bundle
-- `canon/context/claude-plugin/skill-strategy/overview.md`: how to decide between workflow and domain-knowledge skills
-- [`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp): browser automation MCP used in tier 1 and tier 2
-- [`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp): live frontend debugging MCP used in tier 1 and tier 2
-- [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw): community MCP server behind the tier 1 visual companion

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.39.0",
+  "version": "5.41.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/cases/git.ts

@@ -6,6 +6,10 @@ export const GIT_CASES: readonly SkillCase[] = [
     prompt: 'Come up with a conventional name for this branch.',
     expect: 'git-branch',
   },
+  {
+    prompt: 'I am on main and about to start a feature, create its branch.',
+    expect: 'git-branch',
+  },
   {
     prompt: "Turn what's staged into one commit message.",
     expect: 'git-commit',

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,6 +319,11 @@ 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.md states, and naming a path is evidence for it',
         'rather than the answer.',
@@ -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/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',