@erclx/canon 5.39.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.39.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,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',

package/src/commands/gov.ts

@@ -84,6 +84,7 @@ const CANON_RULES_REL = join('.claude', 'rules', 'canon')
 
 interface InstallOptions {
   readonly add?: string
+  readonly yes?: boolean
 }
 
 interface RegenOptions {
@@ -147,6 +148,7 @@ export function register(program: Command): void {
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .option('--add <rules>', 'Comma-separated rules to layer on the stack')
+    .option('--yes', 'Answer the install confirm without a prompt')
     .addHelpText(
       'after',
       [
@@ -156,6 +158,7 @@ export function register(program: Command): void {
         '  canon gov install node ../my-app',
         '  canon gov install node --add astro,shadcn ../my-app',
         '  canon gov install --add tasks,plan ../my-app',
+        '  canon gov install node --yes ../my-app',
         '',
         'With --add and no stack, the named rules install alone. A first',
         'positional naming a stack is read as the stack, so pass . or a path',
@@ -164,6 +167,10 @@ export function register(program: Command): void {
         'Copies each rule into .claude/rules/canon/, replacing a copy already',
         'there. Rules under .claude/rules/project/ are never read.',
         '',
+        'The install confirm needs a TTY. --yes answers it, so a headless call',
+        'installs without setting CANON_NON_INTERACTIVE=1. It does not pick a',
+        'stack, so a headless call still names one.',
+        '',
         'Exit codes:',
         '  0  installed, the stack held no rules, or the prompt was cancelled',
         '  1  refused: no stack named headlessly, an unknown stack, no --add',
@@ -349,6 +356,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one stated figure disagrees with the tree',
         '',
+        'Reasons:',
+        '  no-git       git could not list the tree',
+        '  no-markdown  the tree holds no markdown file',
+        '',
         'It reports and never gates. The false-positive rate is read off the',
         'first run rather than assumed, and a push failing on a stated figure',
         'that reads correctly to a person would teach a contributor to route',
@@ -415,6 +426,9 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one declaration asserts either',
         '',
+        'Refuses an empty superseded value, a superseded value equal to its',
+        'replacement, and a tree git cannot list. An empty replacement is allowed.',
+        '',
         'Examples:',
         '  canon gov superseded feature-feat- feature-',
         '  canon gov superseded feature-feat- feature- --json',
@@ -496,6 +510,9 @@ export function register(program: Command): void {
         '  2  at least one cited path resolves to nothing, or one glob matches',
         '     nothing in this tree',
         '',
+        'Refuses a tree holding neither rule corpus, and a `git check-ignore`',
+        'read that fails.',
+        '',
         'Examples:',
         '  canon gov citations',
         '  canon gov citations --json',
@@ -543,6 +560,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one instruction is restated outside a declared mirror',
         '',
+        'Reasons:',
+        '  no-instructions  the tree holds no always-loaded file or seed to read',
+        '  no-surfaces      the tree holds no skills tree or rules tree to match against',
+        '',
         'Examples:',
         '  canon gov restated',
         '  canon gov restated --json',
@@ -1268,8 +1289,9 @@ async function runInstall(
   intro('canon gov install')
 
   const add = opts.add ?? ''
+  const yes = opts.yes === true
   if (add !== '' && isAddWithoutStack(stack, target)) {
-    return installExtras(add, stack ?? target)
+    return installExtras(add, stack ?? target, yes)
   }
 
   const resolved = resolveTarget(target, PROJECT_ROOT)
@@ -1314,14 +1336,7 @@ async function runInstall(
   for (const rule of missing) logWarn(`${rule} (source not found, skipping)`)
   for (const source of found) logInfo(source.rule)
 
-  const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
-    options: [
-      { value: true, label: 'Yes' },
-      { value: false, label: 'No' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const shouldInstall = await confirmInstall(found.length, target, yes)
 
   if (!shouldInstall) {
     logWarn('Cancelled')
@@ -1347,6 +1362,28 @@ async function runInstall(
   return 0
 }
 
+/**
+ * The install confirm. `--yes` answers it without a prompt, so the line it
+ * would have printed is skipped rather than duplicated under
+ * `CANON_NON_INTERACTIVE=1`.
+ */
+async function confirmInstall(
+  count: number,
+  target: string,
+  yes: boolean,
+): Promise<boolean> {
+  if (yes) return true
+  return select({
+    message: `Install ${count} rules to ${displayPath(target, CANON_RULES_REL)}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+    ttyHint: 'Pass --yes',
+  })
+}
+
 /**
  * Whether `--add` runs with no stack under it. Commander fills the first
  * positional before the second, so `--add a,b ../my-app` arrives with the
@@ -1366,7 +1403,11 @@ function isAddWithoutStack(stack: string | undefined, target: string): boolean {
  * extras are not a stack, and overwriting the chain would cost a target the
  * missing-rule report its stack install recorded.
  */
-async function installExtras(add: string, target: string): Promise<number> {
+async function installExtras(
+  add: string,
+  target: string,
+  yes: boolean,
+): Promise<number> {
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
@@ -1382,14 +1423,7 @@ async function installExtras(add: string, target: string): Promise<number> {
     return 1
   }
 
-  const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
-    options: [
-      { value: true, label: 'Yes' },
-      { value: false, label: 'No' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const shouldInstall = await confirmInstall(found.length, target, yes)
 
   if (!shouldInstall) {
     logWarn('Cancelled')

package/src/commands/intake.ts

@@ -64,6 +64,12 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake       the project holds no intake folder',
+        '  no-folder       no folder matches the slug',
+        '  ambiguous-slug  a bare slug matches more than one ordinal-prefixed',
+        '                  folder, all named in `detail`',
         '',
         'Exit codes:',
         '  0  the folders or items were listed',
@@ -105,6 +111,17 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake       the project holds no intake folder',
+        '  no-folder       no folder matches the slug',
+        '  ambiguous-slug  a bare slug matches more than one ordinal-prefixed',
+        '                  folder, all named in `detail`',
+        '  no-cluster      the cluster file named does not exist',
+        '  no-item         the item number named does not exist in the cluster',
+        '  answered        the item already carries an answer',
+        '  bad-input       a malformed command line, such as no selection, an empty',
+        '                  answer, or two answers for one item',
         '',
         'Exit codes:',
         '  0  every named item now carries its answer',

package/src/commands/labels.ts

@@ -111,6 +111,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one changed path is reached by no row',
         '',
+        'Reasons:',
+        '  no-map  the project declares no label map, so it labels nothing. An',
+        '          expected absence for `canon audits run`, not a fault',
+        '',
         'Examples:',
         '  canon labels audit',
         '  canon labels audit --json',
@@ -130,7 +134,10 @@ export function register(program: Command): void {
     )
     .argument('<number>', "This branch's open pull request")
     .helpOption('-h, --help', 'Show this help message')
-    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option(
+      '--base <ref>',
+      "Read the git range back to this ref instead of the pull request's files",
+    )
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
     .option('--check', 'Report the labels owed and write nothing')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -138,9 +145,10 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Resolves the earned set the way `canon labels audit` does, binds to the',
-        'pull request only when its head is the current branch and it is open,',
-        'and adds each earned label the pull request lacks over REST.',
+        "Resolves the earned set from the pull request's own files listing, or",
+        'from the git range when --base is passed, binds to the pull request only',
+        'when its head is the current branch and it is open, and adds each earned',
+        'label the pull request lacks over REST.',
         '',
         'It adds and never removes, so a label a person applied by hand stays.',
         'A label the remote does not carry is reported under missingOnRemote and',
@@ -155,6 +163,12 @@ export function register(program: Command): void {
         '  2  labels are still owed, being any under --check, or a label the',
         '     remote lacks or a failed add otherwise',
         '',
+        'Reasons:',
+        '  head-mismatch  the pull request is not open on the current branch, under',
+        '                 --check as well',
+        '  gh-failed      the files listing or the labels could not be read, and the',
+        '                 run does not fall back to git',
+        '',
         'Examples:',
         '  canon labels apply 123 --json',
         '  canon labels apply 123 --check',
@@ -396,7 +410,26 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   if (target === null) return refuse('gh-failed')
   if (target.trim() !== `${head} open`) return refuse('head-mismatch')
 
-  const report = await auditLabels(root, { base: opts.base })
+  // An explicit --base is an explicit request for the git route. Otherwise the
+  // pull request's own file listing is the diff the labels describe, and a
+  // failed read refuses rather than falling back, since binding needed gh too.
+  let paths: string[] | undefined
+  if (opts.base === undefined) {
+    const listing = await gh(root, [
+      'api',
+      '--paginate',
+      `repos/{owner}/{repo}/pulls/${number}/files`,
+      '--jq',
+      '.[].filename',
+    ])
+    if (listing === null) return refuse('gh-failed')
+    paths = nonEmptyLines(listing)
+  }
+
+  const report = await auditLabels(root, {
+    base: opts.base,
+    ...(paths !== undefined && { paths }),
+  })
 
   // A project declaring no map earns nothing and is labelled silently, which
   // is an answer and exits clean rather than reading as a break.