@erclx/canon 5.35.0 → 5.37.0

package/governance/rules/lib/{306-test-scope.md → test-scope.md}

@@ -20,5 +20,5 @@ paths:
 
 - Answer a question about the running page with a script against the dev server rather than with the suite.
 - Do not enable `fullyParallel` in `playwright.config.ts`.
-- Follow `.claude/rules/canon/ui/440-surface-capture.md` for capture scope.
-- Follow `.claude/rules/canon/lib/305-e2e-reliability.md` for waits and guards.
+- Follow `.claude/rules/canon/ui/surface-capture.md` for capture scope.
+- Follow `.claude/rules/canon/lib/e2e-reliability.md` for waits and guards.

package/governance/rules/ui/{410-a11y.md → a11y.md}

@@ -60,4 +60,4 @@ paths:
 
 - Let content reflow at a viewport 320 CSS pixels wide with no loss of content or function and no two-dimensional scrolling. Only content whose meaning depends on both axes, such as a data table, a map, or a diagram, may scroll sideways (WCAG Reflow, 1.4.10, Level AA).
 - Treat 320 as the criterion's own test condition rather than a device width. It is equivalent to a 1280 pixel window at 400 percent zoom, so a layout that breaks there breaks for a person who zooms.
-- Hold the same 320 floor for the content region beside persistent chrome a person can resize. The criterion measures the viewport, so this extension is this rule's own rather than the criterion's: a panel widened to 480 in a 768 window leaves 288 for the content, under the floor at a window the criterion passes. `440-surface-capture` states where the frame for it gets taken.
+- Hold the same 320 floor for the content region beside persistent chrome a person can resize. The criterion measures the viewport, so this extension is this rule's own rather than the criterion's: a panel widened to 480 in a 768 window leaves 288 for the content, under the floor at a window the criterion passes. `surface-capture` states where the frame for it gets taken.

package/governance/rules/ui/{440-surface-capture.md → surface-capture.md}

@@ -26,12 +26,12 @@ paths:
 ## What a capture covers
 
 - Capture the full page. Do not capture a component in isolation.
-- Declare the widths a layout case captures. Always include 320, the reflow floor from the reflow criterion in `410-a11y`, then add each breakpoint bucket the project writes rules for, read from the `## Layout` section of `DESIGN.md`.
+- Declare the widths a layout case captures. Always include 320, the reflow floor from the reflow criterion in `a11y`, then add each breakpoint bucket the project writes rules for, read from the `## Layout` section of `DESIGN.md`.
 - Fall back to the 320 floor alone when the project has no `DESIGN.md` or its record carries no `## Layout` section. Do not impose another project's breakpoints.
 - Add a layout case at each bound when a surface renders persistent chrome a person can resize, such as a draggable sidebar or a split pane, one with the chrome at its narrowest and one at its widest. Take both at the narrowest declared width where the chrome stays persistent rather than collapsing, since a frame where it has turned into an overlay shows none of the width it takes.
-- Read those bounds from the code that clamps the chrome, since `## Layout` has no slot for them. Judge each frame by the content width left beside the chrome rather than by the window width, against the 320 floor `410-a11y` holds for that region.
+- Read those bounds from the code that clamps the chrome, since `## Layout` has no slot for them. Judge each frame by the content width left beside the chrome rather than by the window width, against the 320 floor `a11y` holds for that region.
 - Apply the declaration to a case that covers layout only. A case driving a menu open or an answer chosen tests a state, so it takes one width rather than the full set.
-- Read a capture at 320 as proof that a frame was taken there, not that the page reflows correctly. The criterion is stated in `410-a11y` and nothing here enforces it.
+- Read a capture at 320 as proof that a frame was taken there, not that the page reflows correctly. The criterion is stated in `a11y` and nothing here enforces it.
 - Write the capture into a folder named `evidence`. The image is collected for the pull request comment when any segment of its path is literally `evidence` and its filename carries an image extension, so the folder name is fixed and its position in the tree is the project's own.
 - Several `evidence/` folders in one project is the ordinary shape rather than a problem to consolidate. One per surface is how a project with more than one rendered surface ends up.
 - Drive a state a screenshot cannot reach. An initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling.

package/governance/stacks/base.toml

@@ -3,12 +3,12 @@ extends = ""
 # `canon` or `claude` reaches no project until it is added here or proposed by
 # `canon gov detect`. Every other rule is opt-in.
 rules = [
-  "566-output",
-  "602-tasks",
-  "604-scratch",
-  "605-worktrees",
-  "606-git",
-  "611-indexes",
+  "output",
+  "task-scope",
+  "scratch",
+  "worktrees",
+  "git",
+  "indexes",
   "context",
   "tasks",
   "plan",

package/governance/stacks/go.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["code", "130-go", "335-testing-go"]
+rules = ["code", "go", "testing-go"]

package/governance/stacks/node.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["code", "100-typescript", "300-testing-ts"]
+rules = ["code", "typescript", "testing-ts"]

package/governance/stacks/php.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["code", "140-php", "336-testing-php"]
+rules = ["code", "php", "testing-php"]

package/governance/stacks/python.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["code", "110-python", "330-testing-py"]
+rules = ["code", "python", "testing-py"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.35.0",
+  "version": "5.37.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -32,7 +32,7 @@
     "test": "bun --bun vitest run",
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
-    "check:ci": "bun src/cli.ts gate run --all --no-write",
+    "check:ci": "bun src/cli.ts gate run --all",
     "update": "bun update --interactive && bun run check",
     "clean": "rm -rf node_modules && bun pm cache rm && bun install",
     "bootstrap": "./scripts/core/bootstrap.sh",

package/scripts/core/install-check.sh

@@ -101,18 +101,13 @@ log_step "Assert scaffold"
 # skills rather than installing into a target. The two
 # rule paths stand for the `claude` and `canon` groups `base` takes whole.
 for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" \
-  ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
-  ".claude/rules/canon/claude/566-output.md" ".claude/rules/canon/canon/604-scratch.md"; do
+  ".prettierrc" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.ts" \
+  ".claude/rules/canon/claude/output.md" ".claude/rules/canon/canon/scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"
   fi
   log_info "Found: $path"
 done
 
-if [ ! -x "$TARGET_DIR/scripts/verify.sh" ]; then
-  log_error "Not executable after canon init: scripts/verify.sh"
-fi
-log_info "Executable: scripts/verify.sh"
-
 log_step "Verification passed"
 log_info "Manual check still needed: bun link and global canon invocation"

package/src/capture/frame-values.ts

@@ -121,9 +121,6 @@ const plural = (count: number, noun: string): string =>
 const frameRow = (cells: string): string =>
   `<span class="frame">│</span> <span class="ok">✓</span> ${cells}`
 
-/** Rule names carry a numeric prefix that orders the load, not the identity. */
-const slug = (name: string): string => name.replace(/^\d+-/, '')
-
 /** Indented to the depth a rule inside the `<style>` block sits at. */
 const indentTokens = (css: string): string =>
   css
@@ -194,13 +191,13 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
   }
 
   const tokenCss = indentTokens(catalogs.tokenCss)
-  const rules = gov.rules.map((entry) => slug(entry.name))
+  const rules = gov.rules.map((entry) => entry.name)
   // A rule no stack names is opt-in behind `--add`, so featuring one advertises
   // an entry no ordinary `canon gov install` delivers. The column samples the
   // stack-reached subset while its count and remainder describe the whole.
   const stacked = new Set(gov.stacks.flatMap((stack) => stack.rules))
   const deliveredEntries = gov.rules.filter((entry) => stacked.has(entry.name))
-  const deliveredRules = deliveredEntries.map((entry) => slug(entry.name))
+  const deliveredRules = deliveredEntries.map((entry) => entry.name)
 
   for (const [label, list] of [
     ['skills', skills],
@@ -236,7 +233,7 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
       const scope =
         globs.length > 0 ? clip(globs.join(' '), GLOB_WIDTH) : 'every session'
       return frameRow(
-        `<span class="name">${escape(pad(slug(entry.name), 24))}</span>` +
+        `<span class="name">${escape(pad(entry.name, 24))}</span>` +
           `<span class="domain">${escape(pad(`[${entry.domain}]`, 12))}</span>` +
           `<span class="muted">${escape(scope)}</span>`,
       )

package/src/cli/help-all.ts

@@ -0,0 +1,96 @@
+import type { Command } from 'commander'
+
+export type HelpRoute =
+  | { kind: 'parse' }
+  | { kind: 'top' }
+  | { kind: 'all'; command: Command }
+  | { kind: 'unknown'; name: string }
+
+const HELP_FLAGS = new Set(['-h', '--help'])
+
+// Commander exposes no getter for a disabled help option, and `canon sandbox`
+// disables its own to forward `--help` to a bash script.
+function hasHelpOption(command: Command): boolean {
+  return command.helpInformation().includes('--help')
+}
+
+// A group with its own action, or with a default subcommand such as
+// `inventory run`, takes an operand that names no subcommand. Commander keeps
+// both on private fields.
+function takesOperand(command: Command): boolean {
+  const internals = command as unknown as {
+    _actionHandler: unknown
+    _defaultCommandName: unknown
+  }
+  return (
+    command.registeredArguments.length > 0 ||
+    internals._actionHandler !== null ||
+    internals._defaultCommandName !== null
+  )
+}
+
+function visibleChildren(command: Command): Command[] {
+  return command
+    .createHelp()
+    .visibleCommands(command)
+    .filter((child) => command.commands.includes(child))
+}
+
+function leaves(command: Command): Command[] {
+  return visibleChildren(command).flatMap((child) =>
+    visibleChildren(child).length === 0 ? [child] : leaves(child),
+  )
+}
+
+// `outputHelp` rather than `helpInformation`, since only the former emits the
+// blocks `addHelpText` registers, which carry every verb's exit codes and
+// examples.
+function captureHelp(command: Command): string {
+  const config = command.configureOutput()
+  const { writeOut } = config
+  let text = ''
+  command.configureOutput({ writeOut: (chunk) => (text += chunk) })
+  try {
+    command.outputHelp()
+  } finally {
+    command.configureOutput({ writeOut })
+  }
+  return text.trimEnd()
+}
+
+// Each block opens on its own `Usage:` line, so a blank line is the whole
+// separator and a reader splits on the usage header.
+export function renderAll(command: Command): string {
+  const blocks = [command, ...leaves(command)].map(captureHelp)
+  return `${blocks.join('\n\n')}\n`
+}
+
+// Reads argv ahead of commander, which prints a group's help for an unknown
+// subcommand because it answers `--help` before it resolves operands. Walking
+// stops at the first option, so an option's value is never read as a name.
+export function routeHelp(program: Command, args: string[]): HelpRoute {
+  if (!args.some((arg) => HELP_FLAGS.has(arg))) return { kind: 'parse' }
+
+  let command = program
+  let depth = 0
+  for (const arg of args) {
+    if (arg.startsWith('-')) break
+    const child = command.commands.find((c) => c.name() === arg)
+    if (child === undefined) {
+      const isGroupOnly =
+        command !== program &&
+        command.commands.length > 0 &&
+        !takesOperand(command) &&
+        arg !== 'help'
+      if (isGroupOnly) return { kind: 'unknown', name: arg }
+      break
+    }
+    command = child
+    depth += 1
+  }
+
+  if (!args.includes('--all')) return { kind: 'parse' }
+  if (depth === 0) return { kind: 'top' }
+  if (!hasHelpOption(command)) return { kind: 'parse' }
+  return { kind: 'all', command }
+}

package/src/cli/help.ts

@@ -20,61 +20,61 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['sync [path]', 'Sync all installed domains in a project'],
       ['upgrade', 'Reinstall the CLI with the manager that installed it'],
       ['migrate [cmd]', 'Move a project off a retired name or layout'],
-      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
+      ['targets [cmd]', 'Projects this toolkit installed into'],
     ],
   },
   {
     title: 'Domains',
     rows: [
-      ['gov [cmd]', 'Governance rules (install, sync, list)'],
-      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
-      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
-      ['wiki [cmd]', 'Wiki pages (init)'],
-      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
-      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
+      ['gov [cmd]', 'Governance rules'],
+      ['tooling [cmd]', 'Tooling stacks'],
+      ['claude [cmd]', 'Claude workflow'],
+      ['wiki [cmd]', 'Wiki pages'],
+      ['indexes [cmd]', 'Regenerate index.md files'],
+      ['docs [cmd|topic]', 'Emit toolkit reference docs'],
     ],
   },
   {
     title: 'Author and render',
     rows: [
-      ['design [cmd]', 'Design system (render, regen)'],
-      ['slides [cmd]', 'Slide decks (render, list)'],
+      ['design [cmd]', 'Design system'],
+      ['slides [cmd]', 'Slide decks'],
       ['capture [source]', 'Render HTML capture sources to PNG'],
       ['serve [dir]', 'Serve a directory on localhost, print the link'],
-      ['demo [cmd]', 'Record a running app (compile, run)'],
+      ['demo [cmd]', 'Record a running app'],
       ['inventory [subj]', 'Report one computed property across every route'],
       ['drive <url> <run>', 'Walk a page through interactions, measure each'],
       ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
-      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
-      ['canvas [cmd]', 'Local canvas of pages and frames (serve, list)'],
+      ['teach [cmd]', 'Learning workspaces'],
+      ['canvas [cmd]', 'Local canvas of pages and frames'],
     ],
   },
   {
     title: 'Session and ship',
     rows: [
       ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
-      ['tasks [cmd]', 'Task board (validate, archive)'],
-      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
-      ['records [cmd]', 'Session records (validate, size, push, pull)'],
+      ['tasks [cmd]', 'Task board'],
+      ['intake [cmd]', 'Intake folders under .canon/intake/'],
+      ['records [cmd]', 'Session records'],
       ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
       ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
-      ['hooks [cmd]', 'Run the steps a git hook drives (post-merge)'],
-      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
-      ['upstream [cmd]', 'Read Claude Code releases (fetch, catalog, advance)'],
+      ['hooks [cmd]', 'Run the steps a git hook drives'],
+      ['pr [cmd]', 'Read a pull request'],
+      ['upstream [cmd]', 'Read Claude Code releases'],
       ['feedback', 'File toolkit feedback as a GitHub issue'],
     ],
   },
   {
     title: 'Repo reports',
     rows: [
-      ['audits [cmd]', 'Run every health check as one set (run, list)'],
-      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
-      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
-      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
-      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
-      ['comments [cmd]', 'Measure comment density and trend (scan)'],
-      ['context [cmd]', 'Report context folder health (audit)'],
-      ['markdown [cmd]', 'Report markdown against the shipped bans (audit)'],
+      ['audits [cmd]', 'Run every health check as one set'],
+      ['gate [cmd]', 'Run the merge gate stage by stage'],
+      ['secrets [cmd]', 'Scan the shipped tree for credentials'],
+      ['deps [cmd]', 'Read the dependency set for advisories'],
+      ['labels [cmd]', 'Read a changed set against the label map'],
+      ['comments [cmd]', 'Measure comment density and trend'],
+      ['context [cmd]', 'Report context folder health'],
+      ['markdown [cmd]', 'Report markdown against the shipped bans'],
       ['census [path]', 'Report file count, extensions, and line totals'],
     ],
   },
@@ -111,6 +111,7 @@ const EXAMPLES = [
   'canon drive http://localhost:4173 run.json --json',
   'pbpaste | canon feedback',
   'canon transcripts https://youtu.be/VIDEO_ID',
+  'canon tasks --help --all',
   'canon tasks archive --pull-request 673 --json',
   'canon intake list toolkit-overview --unread --json',
   'canon teach list --json',
@@ -129,7 +130,7 @@ const EXAMPLES = [
   'canon labels audit --json',
   'canon census --json',
   'canon audits run --json',
-  'canon gate run --all --no-write',
+  'canon gate run --all',
   'canon upgrade --json',
   'canon upstream fetch --since 2.1.256 --json',
 ]

package/src/cli.ts

@@ -43,6 +43,7 @@ import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { renderHelp } from '@/cli/help'
+import { renderAll, routeHelp } from '@/cli/help-all'
 
 function showHelp(): void {
   console.log(renderHelp(process.stdout))
@@ -102,4 +103,10 @@ audits(program)
 gate(program)
 upgrade(program)
 
-program.parse()
+const route = routeHelp(program, process.argv.slice(2))
+if (route.kind === 'top') showHelp()
+else if (route.kind === 'all') process.stdout.write(renderAll(route.command))
+else if (route.kind === 'unknown') {
+  console.error(`error: unknown command '${route.name}'`)
+  process.exitCode = 1
+} else program.parse()

package/src/commands/claude.ts

@@ -212,6 +212,20 @@ export function register(program: Command): void {
     .description('Seed .claude/ workflow docs into a project')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Copies each workflow seed the target lacks, CLAUDE.md included, and',
+        'leaves one already present alone. Then adds the .gitignore entries',
+        'the claude manifest lists.',
+        '',
+        'Exit codes:',
+        '  0  initialized, already initialized, or the prompt was cancelled',
+        '  1  the target is missing or is the toolkit root',
+        '',
+      ].join('\n'),
+    )
     .action(async (target: string) => {
       process.exitCode = await runInit(target)
     })
@@ -221,6 +235,21 @@ export function register(program: Command): void {
     .description('Reconcile .gitignore against the claude manifest')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes .gitignore alone: adds the entries the claude manifest lists',
+        'and drops ones under its headers that the manifest no longer lists.',
+        'A seeded file is reported, never rewritten, and a missing one points',
+        'at `canon claude init`.',
+        '',
+        'Exit codes:',
+        '  0  synced, already up to date, or the prompt was cancelled',
+        '  1  the target is missing or is the toolkit root',
+        '',
+      ].join('\n'),
+    )
     .action(async (target: string) => {
       process.exitCode = await runSync(target)
     })

package/src/commands/context.ts

@@ -11,11 +11,14 @@ import {
   LENGTH_CHECKPOINT,
   matchesSiblings,
   measureFolders,
+  extraSections,
   missingSections,
   PROVENANCE_FOLDER,
+  ALLOWED_SECTIONS_BY_FOLDER,
   REQUIRED_SECTIONS,
   REQUIRED_SECTIONS_BY_FOLDER,
   requiredSections,
+  type ExtraSectionFinding,
   type SectionFinding,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -640,6 +643,7 @@ async function runAudit(
   const entries = gateOnly ? [] : await measureFolders(root, folders)
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
+  const extras = gateOnly ? [] : extraSections(entries)
   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
@@ -653,7 +657,7 @@ async function runAudit(
     reportScope(folders, unresolved)
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
-    reportSections(sections, folders)
+    reportSections(sections, extras, folders)
     reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
@@ -691,6 +695,7 @@ async function runAudit(
         // never opened an entry.
         length,
         missingSections: sections,
+        extraSections: extras,
         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
@@ -705,6 +710,7 @@ async function runAudit(
           // caller that read it first, since removing it would break that
           // caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
+          allowedSectionsByFolder: ALLOWED_SECTIONS_BY_FOLDER,
         },
       })}\n`,
     )
@@ -715,6 +721,7 @@ async function runAudit(
     requirementsOverWords:
       requirements !== undefined && isOverWordCap(requirements),
     sections,
+    extraSections: extras,
     drift,
     widened,
   })
@@ -905,6 +912,7 @@ function reportReferenceForm(
  */
 function reportSections(
   missing: readonly SectionFinding[],
+  extras: readonly ExtraSectionFinding[],
   folders: readonly AuditedFolder[],
 ): void {
   logStep('Sections')
@@ -938,13 +946,30 @@ function reportSections(
 
   if (missing.length === 0) {
     logInfo('Every entry declares each required section.')
+  } else {
+    logWarn(`${plural(missing.length, 'path')} short a required section`)
+    pipeOutput(
+      missing
+        .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+        .join('\n'),
+    )
+  }
+
+  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.`,
+  )
+
+  if (extras.length === 0) {
+    logInfo('No entry carries an H2 outside the set.')
     return
   }
 
-  logWarn(`${plural(missing.length, 'path')} short a required section`)
+  logWarn(`${plural(extras.length, 'path')} carrying an H2 outside the set`)
   pipeOutput(
-    missing
-      .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+    extras
+      .map((found) => `${found.rel}  extra: ${found.headings.join(', ')}`)
       .join('\n'),
   )
 }

package/src/commands/design.ts

@@ -161,7 +161,13 @@ export function register(program: Command): void {
         `overrides a value by writing ${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/`,
         'itself, which sync never touches. Nothing arrives on a project that',
         'has not run this, so a design value reaches a target on an install',
-        'rather than on the next sync.',
+        'rather than on the next sync. A base stylesheet already installed is',
+        'replaced.',
+        '',
+        'Exit codes:',
+        '  0  the stylesheet was installed',
+        '  1  the target is missing or is the toolkit root, or the toolkit',
+        '     source is absent',
         '',
       ].join('\n'),
     )
@@ -176,6 +182,21 @@ export function register(program: Command): void {
     )
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Replaces the shipped design files under .claude/design/ with the',
+        'toolkit copy, edited or not, and leaves',
+        `${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/ alone. It deletes nothing it finds no`,
+        'source for.',
+        '',
+        'Exit codes:',
+        '  0  synced, already up to date, or the prompt was cancelled',
+        '  1  the target is missing or is the toolkit root',
+        '',
+      ].join('\n'),
+    )
     .action(async (target: string) => {
       process.exitCode = await runDomainSync(
         createDesignAdapter(PROJECT_ROOT),

package/src/commands/gate.ts

@@ -27,7 +27,6 @@ import { repairBareFlag } from '@/worktrees/bare-flag'
 
 interface RunCommandOptions {
   readonly all?: boolean
-  readonly write?: boolean
   readonly nested?: boolean
   readonly json?: boolean
 }
@@ -48,10 +47,6 @@ export function register(program: Command): void {
       '--all',
       'Run every stage instead of scoping shell, types, and tests to changed files',
     )
-    .option(
-      '--no-write',
-      'Check formatting instead of applying it, which is what a merge gate wants',
-    )
     .option(
       '--nested',
       'Suppress the outer frame when another script opened one',
@@ -77,7 +72,7 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon gate run',
-        '  canon gate run --all --no-write',
+        '  canon gate run --all',
         '  canon gate run --json',
         '',
       ].join('\n'),
@@ -92,7 +87,6 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
   const mismatch = checkoutMismatchWarning(process.cwd())
   const emitJson = opts.json ?? false
   const nested = opts.nested ?? false
-  const write = opts.write ?? true
   const run = commandRunner(root)
 
   if (!emitJson && !nested) intro('canon gate run')
@@ -111,7 +105,6 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
     ci: process.env.CI === 'true',
     run,
     cli: cliRunner(root),
-    write,
     changed: changed.scoped ? changed.files : undefined,
     onQueue: (label, holder) => {
       const text = `${label} is waiting for the suite pid ${holder.pid} runs at ${holder.root}`

package/src/commands/gov.ts

@@ -154,13 +154,21 @@ export function register(program: Command): void {
         'Examples:',
         '  canon gov install node',
         '  canon gov install node ../my-app',
-        '  canon gov install node --add 210-astro,260-shadcn ../my-app',
+        '  canon gov install node --add astro,shadcn ../my-app',
         '  canon gov install --add tasks,plan ../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',
         'carrying a slash to force a target that shares a stack name.',
         '',
+        'Copies each rule into .claude/rules/canon/, replacing a copy already',
+        'there. Rules under .claude/rules/project/ are never read.',
+        '',
+        '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',
+        '     rule resolved, or a missing target or the toolkit root',
+        '',
       ].join('\n'),
     )
     .action(
@@ -178,6 +186,21 @@ export function register(program: Command): void {
     .description('Update rules already installed under .claude/rules/canon/')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Replaces an edited rule under .claude/rules/canon/ with the shipped',
+        'copy, deletes a rule the toolkit retired, and moves a renamed one.',
+        'It adds no new rule, which is `canon gov install`, and never touches',
+        '.claude/rules/project/.',
+        '',
+        'Exit codes:',
+        '  0  synced, already up to date, or the prompt was cancelled',
+        '  1  the target is missing or is the toolkit root',
+        '',
+      ].join('\n'),
+    )
     .action(async (target: string) => {
       process.exitCode = await runDomainSync(
         createGovAdapter(PROJECT_ROOT),
@@ -440,10 +463,9 @@ export function register(program: Command): void {
         'internal corpus ships nowhere, which makes the tree it governs the tree',
         'present and the question answerable.',
         '',
-        'Forms read, with where each resolves:',
+        'Form read, with where it resolves:',
         '  path      a backticked path carrying a directory segment and a file',
         '            extension, against the root',
-        "  sibling   a bare <nnn>-<slug>.md , against the citing rule's folder",
         '',
         'Not read, each a shape the corpus writes and none of them a citation:',
         '  a placeholder or glob segment, which describes a shape rather than',