@erclx/canon 4.105.0 → 4.107.0

package/claude/skills/session-relay/SKILL.md

@@ -1,27 +1,92 @@
 ---
 name: session-relay
-description: Composes the relay a worker or planner owes its controller when the session holds no message-sending tool, carrying the sender's own name, the addressee the calling role's own ladder resolves, and the message body that role already names, opened with a header naming all three so an operator can copy the block whole. Fires only from inside `role-worker` or `role-planner`'s own `## The channel` section, at the point that section finds no tool to send through. Do NOT invoke it when a message-sending tool exists, which is the ordinary channel, and do NOT invoke it to resolve an addressee for anything other than a channel obligation those two roles already state.
+description: Relays a message to another session, turning the sessionId the caller named into an address at the moment of sending and composing a copyable block where no send tool exists. Use when asked to "relay this", "message the controller", "send this over to the session that dispatched me", or "tell the other session", with or without a role. Do NOT use to decide what the message says, and do NOT use to assert what a session may write or is on the hook for, which is `role-worker` or `role-planner`.
 ---
 
 # Session relay
 
-`role-worker` and `role-planner` each owe their controller a set of messages, and each assumes a message-sending tool exists to carry them. A session holding none has nothing to send through, and the paragraph stating what to do about that used to sit inline in both bodies, repeating the same protocol twice. This skill is that paragraph, and both role bodies point to it instead of each carrying their own copy.
+This is the one place a session sends to another session. It holds the
+mechanical half of the send: naming the sender, turning a `sessionId` or a
+branch into an address that reaches, and putting the text through whichever
+route exists. It holds none of the other half. What the message says and who it
+goes to come from whatever dispatched this session, and from the calling role's
+own `## The channel` section where the session holds a role.
 
-Read the calling body's `## The channel` section for the message owed and the ladder that resolves its addressee. This skill does not restate either.
+It fires for a session holding a role and for one holding none. A roleless
+session reaches this body directly and finds everything it owes stated here,
+rather than reading a ladder written for a role it does not have.
 
-## Guards
+## Step 1: name the sender
 
-- Refuse to fire when the calling session holds neither `role-worker` nor `role-planner`. Say so, and state what it owes instead: resolve the addressee at send time through `canon sessions list --json`, never by name prefix, and send a block out as a message before it becomes an interactive prompt, leaving the message content to whatever dispatched it. Checked first, since a caller that never held either role never had a ladder here to run, and the tool guard below reads as the whole reason only once this one has cleared.
-- Refuse to fire when a message-sending tool is available. Say so, name the tool, and send through it. This skill exists for the gap, never as an alternative to the ordinary channel.
+Read this session's own name from `canon sessions list --self --json`. A
+message an operator relays by hand needs a sender as much as an addressee, and
+a message arriving through a tool is read against whoever sent it.
 
-## Steps
+A refusal carrying `no-self-identity` or `no-self-row` means the roster holds
+nothing to name the sender with. Report the refusal and its reason in place of a
+name rather than guessing one.
 
-1. Read this session's own name from `canon sessions list --self --json`. A refusal here, `no-self-identity` or `no-self-row`, means the roster carries nothing to name the sender with. Report the refusal and its reason in place of a name rather than guessing one.
-2. Resolve the addressee. Run the calling role's own `## The channel` ladder to the letter rather than a second one here, and take its outcome, whatever it is, as this skill's addressee.
-3. Carry the message body the calling role's bullet already names, verbatim. This skill composes and never drafts, so the pull request announcement, the address-review announcement, or the blocked question is exactly the text that bullet states, with its own facts filled in.
-4. Open the composed text with a header naming the sender, the addressee, and what the message is. Close the turn with nothing after it, so the block above is the whole of what an operator copies.
+Where the installed CLI answers `--self` with an unknown option, that flag is
+newer than the release this session holds, so there is no refusal and no reason
+to report. Name the sender from what the environment states instead, and say the
+roster did not answer, so the reader knows the name was not confirmed against
+it.
 
-Where the installed CLI answers `--self` with an unknown option, that flag is newer than the release this session holds, so step 1 meets no refusal with a reason to report. Name the sender from what the environment states instead, and say the roster did not answer, so the reader knows the name was not confirmed against it.
+## Step 2: resolve the addressee
+
+The caller names the addressee as a `sessionId` or as a branch, never as a name.
+A name is derived from what a session turns out to be doing and goes stale
+inside the window a build or a plan takes, so resolve it at the moment of
+sending rather than at launch.
+
+- From a `sessionId`: run `canon sessions list --json`, find the row carrying that id, and take the `name` on it.
+- From a branch: run the same read and take the row whose `branch` matches. Nothing renames a session when it takes a role, which is why an id is the stronger key and a branch is the fallback rather than the default.
+
+Then check that name against the agent listing before sending it. A name is not
+unique, and the roster carries no field separating two live sessions holding
+one, so the resolution can end on a string that reaches the wrong session.
+
+- One row under the name: send it bare.
+- More than one row: complete the address with the `[ref]` that listing prints beside each row, rather than sending to the name alone, which lands on whichever row the channel resolves first. Two sessions differing only by a trailing ` (3)` is the shape this meets in practice.
+
+Never filter that roster by a name prefix. Every self-dispatched worker is named
+`worker-<project>-<slug>`, so a prefix scan returns a sibling or this session
+itself, which is the defect that sent messages owed to a controller somewhere
+else.
+
+Report a resolution that returns nothing rather than falling back to a guess.
+The roster and the send channel enumerate different populations in both
+directions, measured at one moment: a live background session sat on the roster
+that the agent listing did not carry, and nine sessions were addressable there
+with no roster row at all. Those nine were driving through Remote Control, which
+writes no local process record.
+
+Where the caller named nobody at all, the calling role's own `## The channel`
+section carries the last rung, since a worker and a planner infer differently
+and a roleless caller has no ladder to defer to. Ask the operator where one is
+present, put the candidate rows through the structured question surface so they
+pick a row rather than recall a name, and say the addressee was inferred
+wherever an inference decided it.
+
+## Step 3: send
+
+- A message-sending tool exists: send through it, addressed to what Step 2 resolved. This is the ordinary route.
+- No message-sending tool, or Step 2 found no row to address: compose the block below and close the turn with nothing after it, so the block is the whole of what an operator copies.
+
+Send the block out as a message before it becomes an interactive prompt. A
+session already waiting on input never reaches the tool round that drains an
+inbound message, so an answer relayed afterwards arrives under the open question
+and changes nothing. This holds on both routes.
+
+The shipped channel rule states the same thing for a session holding neither
+role, so the restatement here is for the target that installed the plugin and
+not governance, where that rule never arrives. A session that does load it reads
+the rule and this body in agreement rather than one of them alone.
+
+Carry the message body verbatim from whatever names it. This skill composes and
+never drafts, so a pull request announcement, an address-review announcement, or
+a blocked question is exactly the text the calling bullet or the dispatch
+states, with its own facts filled in.
 
 ## Header
 
@@ -30,8 +95,12 @@ Relay: from <sender> to <addressee>, <what the message is>
 <message body>
 ```
 
-States a default rather than a fixed vocabulary. A session may write the header in its own words, since it exists to be read once and copied rather than parsed by anything downstream. Name the same three parts however phrased.
+States a default rather than a fixed vocabulary. A session may write the header
+in its own words, since it exists to be read once and copied rather than parsed
+by anything downstream. Name the same three parts however phrased.
 
 ## Output
 
-Nothing beyond the composed block. Report the Guards refusal instead when the roster cannot answer for the sender, and report the calling body's own halt or inference when its ladder cannot resolve the addressee.
+The sent message, or the composed block and nothing beyond it. Report Step 1's
+refusal in place of a sender the roster cannot answer for, and report the halt
+or the inference in place of an addressee Step 2 cannot resolve.

package/docs/agents/capture.md

@@ -18,7 +18,7 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds five sources and the three templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+A capture set here spans two folders. `assets/captures/` holds five sources and the three templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
 
 Two of the three templates take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
 
@@ -26,9 +26,9 @@ The README shows each still in two themes through `<picture>`, so a frame is a p
 
 A stamp for a URL source digests the address string rather than the page it served, so two themes of one address carry one `source-sha256` and only `image-sha256` tells the frames apart. That holds for `examples/teach/evidence/root-listing-light.png`, which is retaken by serving a copy of the fixture with `data-theme="light"` on its `<html>` element at the same address, since the page follows the dark default and the command takes no scheme.
 
-`assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
+`assets/captures/` is read flat and never descends, by the regeneration script and by this command alike. A source nested a further folder down is skipped by both with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
 
-Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/captures --selector .window --out assets/evidence` when the check reports the HTML changed.
+A branch is not asked whether the HTML is current. The PNG is a chromium render whose bytes move with the browser version, so the refresh workflow rebuilds it with `canon capture assets/captures --selector .window --out assets/evidence` only when the regenerated HTML changed.
 
 Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. A capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
 

package/docs/agents/commands.md

@@ -5,7 +5,7 @@ description: Every project-level command and every domain subcommand, plus the s
 
 # Command catalog
 
-Full help: `canon <command> --help`. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
+Full help: `canon <command> --help`. Bare `canon --help` lists every top-level command under five headings, Project, Domains, Author and render, Session and ship, and Repo reports, with descriptions cut at 80 columns. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
 
 ## Project-level
 

package/docs/agents/tasks.md

@@ -54,6 +54,8 @@ An outcome whose body is struck reads as cut rather than open or closed, whateve
 
 The task carries its plan with it. When the closing task is the last live one whose `Plan:` line resolves onto that file, the plan moves to `.canon/plans/archive/` under its own name and the archived task's line is rewritten as `Plan: [feature-<slug>](../../plans/archive/feature-<slug>.md)`, a folder deeper than the live task wrote it. The `plan` field on the success record carries that `from` and `to`, and is `null` when nothing moved.
 
+Every other relative link in the task is re-resolved for the deeper folder too, whether its target moved or not: `Groundwork:`, `Intake:`, a `Plan:` or `Ready:` line whose target stayed put, and a link in the body. Fenced blocks, inline code spans, absolute URLs, `#` anchors, and rooted paths are left alone. `canon tasks decline` applies the same rebase, since `declined/` sits at the same depth. The rebase runs before the plan and ready retargets, so a moved plan keeps its own line.
+
 The ready folder the task's `Ready:` line names moves with the plan to `.canon/ready/archive/`, falling back to a `.canon/ready/<nn>-<slug>/` path in the plan when the line is absent. The `Ready:` line and the plan's literal path to the folder are retargeted, and the `ready` field on the success record carries `from` and `to`, or `null` when nothing moved. A folder that resolves to nothing, sits already archived, or meets a taken destination moves nothing and refuses nothing.
 
 A plan several tasks share stays where it is, and its ready folder with it, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.

package/docs/agents/teach.md

@@ -174,6 +174,8 @@ With no topic it rewrites every workspace. The teach-root listing is always rewr
 
 A lesson carries its chrome as four marker pairs the authoring skill writes empty: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. This verb splices each one from the current workspace state, embedding the shared stylesheet, rebuilding the breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts, and leaves the authored `<h1>`, lede, body, and quiz between the header and the footnav untouched.
 
+A workspace carrying no `course.css` gets its stylesheet pair seeded first, so the contents page it links is never unstyled, and an existing `course.css` is never overwritten. The embedded copy drops the seed's `@import` line, which resolved against the lesson's own folder and never loaded anything.
+
 A lesson missing one of the four marker pairs is refused by name rather than rewritten, and every other lesson in the run still rewrites. The record's `skipped` list carries the refused files and which marker each is missing.
 
 The `style` region carries the quiz stepper after the workspace stylesheet, for every lesson but the one shape named three paragraphs down, so it wins the cascade at equal specificity and reaches a workspace seeded before it existed. The stepper is CSS over the radio inputs a quiz is written from: it hides every question that follows one holding no checked input, and hides a question's feedback until that question does. The general sibling combinator is what keeps that from depending on the markup contract holding, since it selects the same questions as the adjacent one for a quiz written correctly and goes on gating when anything sits between two of them, where the adjacent one matches nothing and shows them all at once. Gating there rather than in a script is what keeps a later stem from answering an earlier question with nothing to bind, and the whole block sits inside `@supports selector(:has(*))`, so an engine without `:has()` renders every question rather than a stepper showing nothing. Feedback there follows the workspace stylesheet, shown by one that says nothing about `.fb` and hidden by one grown under the retired script.

package/docs/workflow/ai-workflow.md

@@ -272,15 +272,15 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Run several tracks at once
 
-| Skill                     | When to use                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------- |
-| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR  |
-| `canon:role-planner`      | To assert the planner role for a cold session writing one plan under one task   |
-| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan |
-| `canon:session-relay`     | When a worker or planner owes its controller a message and holds no send tool   |
-| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                  |
-| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board  |
-| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff       |
+| Skill                     | When to use                                                                                          |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                       |
+| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass |
+| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                      |
+| `canon:session-relay`     | When this session owes another session a message, with or without a role                             |
+| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                       |
+| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board                       |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                            |
 
 ### Keep the project current with the toolkit
 

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

@@ -42,7 +42,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
 - `canon:ux-walkthrough` for a multi-finding inspection pass over a running app with the operator, drafting arms from the app's own markup and recording each pick for a builder
-- `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
+- `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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.105.0",
+  "version": "4.107.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -46,6 +46,21 @@ PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 ASSET_DIR="$PROJECT_ROOT/assets/captures"
 LISTED=10
 
+# `--check` fills every template into a temp folder and discards it, so a renamed
+# featured skill, an empty catalog, or an unresolved placeholder still fails a
+# branch while no frame file changes. Frames are refreshed after a merge rather
+# than committed by each branch, so a branch asks whether the regen can run and
+# never whether its output is current.
+OUT_DIR="$ASSET_DIR"
+case "${1:-}" in
+'') ;;
+--check) OUT_DIR="$(mktemp -d)" ;;
+*)
+  echo "regen-hero: unknown argument $1" >&2
+  exit 1
+  ;;
+esac
+
 # `bun src/cli.ts` rather than `canon`, since a globally linked binary resolves to
 # the main checkout no matter which worktree is running.
 catalog() {
@@ -97,7 +112,7 @@ done
 # fails the exec with E2BIG before any stage can report a stale count. A file
 # path is bounded whatever the catalogs grow to.
 PAYLOAD_DIR="$(mktemp -d)"
-trap 'rm -rf "$PAYLOAD_DIR"' EXIT
+trap 'rm -rf "$PAYLOAD_DIR"; [ "$OUT_DIR" = "$ASSET_DIR" ] || rm -rf "$OUT_DIR"' EXIT
 
 printf '%s' "$COUNTS_JSON" >"$PAYLOAD_DIR/counts.json"
 printf '%s' "$SKILLS_JSON" >"$PAYLOAD_DIR/skills.json"
@@ -109,12 +124,12 @@ printf '%s' "$COMMANDS_HELP" >"$PAYLOAD_DIR/commands-help.txt"
 printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
-export ASSET_DIR LISTED PROJECT_ROOT
+export ASSET_DIR OUT_DIR LISTED PROJECT_ROOT
 
 bun --eval '
 const { readFileSync, readdirSync } = require("node:fs")
 
-const { PAYLOAD_DIR, ASSET_DIR, LISTED, PROJECT_ROOT } = process.env
+const { PAYLOAD_DIR, ASSET_DIR, OUT_DIR, LISTED, PROJECT_ROOT } = process.env
 
 const payload = (name) => readFileSync(PAYLOAD_DIR + "/" + name + ".json", "utf8")
 
@@ -438,6 +453,6 @@ for (const { template, out, tokens } of frames) {
     process.exit(1)
   }
 
-  await Bun.write(ASSET_DIR + "/" + out, html)
+  await Bun.write(OUT_DIR + "/" + out, html)
 }
 '

package/src/claude/cases/workflow.ts

@@ -155,7 +155,7 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt:
-      'I owe my controller the pull request announcement but I have no message-sending tool. Compose the relay so an operator can copy it over.',
+      'Relay this over to the session that dispatched me. It gave me a sessionId rather than a name, so work out who that is and send it.',
     expect: 'session-relay',
   },
 

package/src/cli.ts

@@ -45,6 +45,95 @@ import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
 
+const HELP_WIDTH = 80
+const SIGNATURE_WIDTH = 19
+const ROW_INDENT = '│    '.length
+
+type CommandRow = [signature: string, description: string]
+
+// The grouping mirrors the README's domain table and has no other source, so a
+// command added to the program needs a row here or help-option.test.ts fails.
+const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
+  {
+    title: 'Project',
+    rows: [
+      ['init [path]', 'Bootstrap a project with toolkit domains'],
+      ['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)'],
+    ],
+  },
+  {
+    title: 'Domains',
+    rows: [
+      ['gov [cmd]', 'Governance rules (install, sync, list)'],
+      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
+      ['snippets [cmd]', 'Prompt snippets (create, 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>)'],
+    ],
+  },
+  {
+    title: 'Author and render',
+    rows: [
+      ['design [cmd]', 'Design system (render, board)'],
+      ['slides [cmd]', 'Slide decks (render, list)'],
+      ['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)'],
+      ['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)'],
+    ],
+  },
+  {
+    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)'],
+      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
+      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
+      ['autoship [cmd]', 'Decide whether a changed set needs review'],
+      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
+      ['feedback', 'Write toolkit feedback from stdin'],
+    ],
+  },
+  {
+    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 standards (audit)'],
+      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
+      ['census [path]', 'Report file count, extensions, and line totals'],
+    ],
+  },
+]
+
+// A row past the width is cut rather than wrapped, since a wrapped row breaks
+// the alignment the grouping exists to buy.
+function commandRow(signature: string, description: string): string {
+  const { GREY, NC } = palette(process.stdout)
+  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
+  const text =
+    description.length > room
+      ? `${description.slice(0, room - 1)}…`
+      : description
+  return `${GREY}│${NC}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
+}
+
 function showHelp(): void {
   // The help text is the one framed surface written to stdout, so it asks
   // about that stream rather than the stderr every other writer here uses.
@@ -54,46 +143,13 @@ function showHelp(): void {
     `${GREY}├${NC} ${WHITE}Usage:${NC} canon [command]`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
-    `${GREY}│${NC}    init [path]        ${GREY}# Bootstrap a project with toolkit domains${NC}`,
-    `${GREY}│${NC}    sync [path]        ${GREY}# Sync all installed domains in a project${NC}`,
-    `${GREY}│${NC}    sandbox [cat:cmd]  ${GREY}# Provision and run sandbox scenarios${NC}`,
-    `${GREY}│${NC}    gov [command]      ${GREY}# Governance commands (install, sync)${NC}`,
-    `${GREY}│${NC}    standards [cmd]    ${GREY}# Standards commands (install, sync, list, <name>)${NC}`,
-    `${GREY}│${NC}    snippets [cmd]     ${GREY}# Snippets commands (create, list)${NC}`,
-    `${GREY}│${NC}    tooling [cmd]      ${GREY}# Manage tooling stacks (sync, ref, create)${NC}`,
-    `${GREY}│${NC}    claude [cmd]       ${GREY}# Claude workflow (init, sync, setup)${NC}`,
-    `${GREY}│${NC}    wiki [cmd]         ${GREY}# Wiki commands (init)${NC}`,
-    `${GREY}│${NC}    indexes [cmd]      ${GREY}# Regenerate index.md files (regen)${NC}`,
-    `${GREY}│${NC}    docs [cmd|topic]   ${GREY}# Emit toolkit reference docs (list, <topic>)${NC}`,
-    `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render, board)${NC}`,
-    `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
-    `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
-    `${GREY}│${NC}    serve [dir]        ${GREY}# Serve a directory over localhost and print the preview link${NC}`,
-    `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
-    `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
-    `${GREY}│${NC}    drive <url> <run>  ${GREY}# Walk a page through named interactions and measure each state${NC}`,
-    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .canon/feedback/${NC}`,
-    `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
-    `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
-    `${GREY}│${NC}    intake [cmd]       ${GREY}# Intake folders under .canon/intake/ (list, answer)${NC}`,
-    `${GREY}│${NC}    teach [cmd]        ${GREY}# Learning workspaces under .canon/teach/ (list, open, resource, glossary)${NC}`,
-    `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
-    `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
-    `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
-    `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
-    `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
-    `${GREY}│${NC}    targets [cmd]      ${GREY}# Report the projects this toolkit installed into (list, pulls)${NC}`,
-    `${GREY}│${NC}    worktrees [cmd]    ${GREY}# Reclaim the worktrees whose branches merged (list, reclaim)${NC}`,
-    `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
-    `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
-    `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
-    `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
-    `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request against its own diff and its branch tip (key-changes, head, checks)${NC}`,
-    `${GREY}│${NC}    repo [cmd]         ${GREY}# This repository's own remote metadata (metadata propose, apply)${NC}`,
-    `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
-    `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
-    `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
-    `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
+    ...COMMAND_GROUPS.flatMap((group) => [
+      `${GREY}│${NC}`,
+      `${GREY}│${NC}  ${WHITE}${group.title}${NC}`,
+      ...group.rows.map(([signature, description]) =>
+        commandRow(signature, description),
+      ),
+    ]),
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    canon sandbox             ${GREY}# Interactive scenario picker${NC}`,

package/src/design/components.ts

@@ -265,6 +265,8 @@ const TEACH_CHROME: Component = {
   --teach-shadow: none;
 }
 
+html { scroll-padding-top: calc(var(--teach-mast-h) + 1rem); }
+
 /* No horizontal padding on the body, so the sticky bar reaches both window
    edges. The gutter moves onto \`main\`, which is the only thing that needed it. */
 body {
@@ -282,7 +284,7 @@ body {
    listing page and a lesson start at the same left edge as the chrome above
    them. A narrower \`.wide-body\` was what put the navigation and the content on
    two different measures. */
-main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.25rem 1.5rem 0; }
+main { box-sizing: border-box; max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.25rem 1.5rem 0; }
 .wide-body { max-width: calc(var(--teach-measure) + 3rem); }
 
 .bar {
@@ -346,6 +348,8 @@ main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.
 
 .nav > a:hover { border-color: var(--color-accent); background: var(--color-teach-accent-bg); }
 .nav > .end { color: var(--color-muted); border-style: dashed; font-weight: 400; box-shadow: none; }
+.nav > :only-child { flex: 0 1 calc(50% - 0.3rem); }
+.nav > .to-next:only-child { margin-left: auto; }
 
 .nav .lbl {
   display: block;
@@ -360,7 +364,6 @@ main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.
 .nav > a:hover .lbl { color: var(--color-accent); }
 .nav .to-next { text-align: right; }
 .nav .to-index { flex: 0 0 auto; text-align: center; }
-.nav-foot { margin: 4.5rem 0 0; }
 
 /* ---- Masthead contents ---- */
 
@@ -476,7 +479,13 @@ main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.
 
 /* ---- Footer navigation, the only place it appears ---- */
 
-.nav { margin: 4rem 0 0; align-items: stretch; }
+.nav {
+  max-width: calc(var(--teach-measure) + 3rem);
+  margin: 4rem auto 0;
+  padding: 0 1.5rem;
+  box-sizing: border-box;
+  align-items: stretch;
+}
 
 .nav > a, .nav > span { display: flex; flex-direction: column; justify-content: center; }
 
@@ -919,6 +928,7 @@ const TEACH_QUIZ: Component = {
   font-family: var(--teach-sans);
   font-size: var(--t4);
   background: transparent;
+  box-sizing: border-box;
   width: 100%;
   text-align: left;
   color: inherit;

package/src/gate/measures.ts

@@ -818,9 +818,17 @@ export const readmeCitations: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Globs `pr-visual-checks.yml` carries with no `deploy-site.yml` counterpart,
+ * because the path changes no byte of the built site. The capture harness is
+ * the one case: a change there should report the capture job and never deploy.
+ */
+const VISUAL_ONLY_GLOBS: readonly string[] = ['tooling/web/configs/e2e/**']
+
 /**
  * `deploy-site.yml` and `pr-visual-checks.yml` each carry their own literal
- * copy of the eight path globs a landing-page change should trigger on, per
+ * copy of the eight path globs a landing-page change should trigger on, plus
+ * the `VISUAL_ONLY_GLOBS` the visual workflow adds for itself, per
  * Question 2 in `.canon/plans/archive/feature-render-visibility.md`. A YAML
  * anchor cannot cross files here, so the two copies are read live and compared
  * rather than one asserting a literal the other could drift behind unnoticed,
@@ -858,14 +866,25 @@ export const visualPathGlobs: Measure = async (ctx) => {
     }
   }
 
-  const onlyDeploy = deployPaths.filter((path) => !visualPaths.includes(path))
-  const onlyVisual = visualPaths.filter((path) => !deployPaths.includes(path))
+  const onlyDeploy = deployPaths.filter(
+    (path) => !visualPaths.includes(path) || VISUAL_ONLY_GLOBS.includes(path),
+  )
+  const onlyVisual = visualPaths.filter(
+    (path) => !deployPaths.includes(path) && !VISUAL_ONLY_GLOBS.includes(path),
+  )
+  const declaredVisualOnly = visualPaths.filter((path) =>
+    VISUAL_ONLY_GLOBS.includes(path),
+  )
 
   if (onlyDeploy.length === 0 && onlyVisual.length === 0) {
+    const visualOnlyNote =
+      declaredVisualOnly.length > 0
+        ? `, plus visual-only ${declaredVisualOnly.join(', ')}`
+        : ''
     return {
       emissions: [
         info(
-          `${deployPaths.length} path glob(s) agree between ${deployPath} and ${visualPath}`,
+          `${deployPaths.length} path glob(s) agree between ${deployPath} and ${visualPath}${visualOnlyNote}`,
         ),
       ],
     }
@@ -874,7 +893,11 @@ export const visualPathGlobs: Measure = async (ctx) => {
   return {
     emissions: [
       ...onlyDeploy.map((path) =>
-        warn(`${deployPath} carries ${path}, absent from ${visualPath}`),
+        warn(
+          VISUAL_ONLY_GLOBS.includes(path)
+            ? `${deployPath} carries ${path}, which is visual-only and must not trigger a deploy`
+            : `${deployPath} carries ${path}, absent from ${visualPath}`,
+        ),
       ),
       ...onlyVisual.map((path) =>
         warn(`${visualPath} carries ${path}, absent from ${deployPath}`),

package/src/gate/stages.ts

@@ -197,12 +197,10 @@ export const STAGES: readonly Stage[] = [
     id: 'hero',
     label: 'Hero',
     checks: [
-      script('regen-hero.sh', 'Hero regen failed'),
       {
-        kind: 'drift',
-        pathspec: 'assets/captures/*.html',
-        failure:
-          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets/captures --selector .window --out assets/evidence, and commit each assets/captures/*.html with its .png and .stamp.',
+        kind: 'command',
+        argv: ['bash', 'scripts/core/regen-hero.sh', '--check'],
+        failure: 'Hero regen health check failed',
       },
       { kind: 'measure', measure: captureStamps },
     ],