@erclx/canon 4.106.0 → 4.108.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.106.0",
+  "version": "4.108.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/document-health/REQUIREMENT.md

@@ -0,0 +1,46 @@
+---
+name: document-health
+description: What the document health check is for, the gap it closes, and why it reports three axes rather than one number
+---
+
+# Document health requirement
+
+## Gap
+
+Without this skill, a project learns which documents are missing and never learns which have rotted. `target-check` reports per domain what a target holds against what the toolkit ships, and every one of its domains asks a structural question: does the file exist, does it hold the required sections, do the bytes match what shipped. A document that exists, holds every section, and describes a tree that moved six months ago passes every one of them.
+
+The second half of the gap is the axes being read as one thing. Length, placement, and staleness answer to different evidence, and a run that reports them in one undifferentiated list hands the reader a judgment wearing the authority of a measurement. The operator's own complaint was staleness, which is the axis with nothing behind it, so the flattening runs in the direction that overstates the weakest finding.
+
+The third is silence on an unread axis. Both measured verbs resolve their folders by surface root, so a project whose layout differs resolves nothing and the verb refuses. A run reading that refusal as an empty finding set reports a healthy corpus for documents nothing looked at.
+
+## Must
+
+- Report per document across three named axes, so a reader can tell which question a finding answers
+- Read length and placement through the verb that already owns each measurement, rather than re-deriving either by hand
+- Mark every finding with its evidence class, so a judgment is never read as a measurement
+- Ship the staleness axis, and mark it as a reading rather than cutting it for lacking a verb
+- Report a refusal, an absent key, and a missing subcommand as an unread axis, naming the cause
+- Say which layer answered the classifier sweep, since its model layer being off narrows the read without refusing it
+- Take every checkpoint from the record the verb returns rather than from a number written into the skill
+- Run standalone, and stay callable from the structural check rather than reachable only through it
+
+## Must not
+
+- Repair a finding, write a file in the project, or open a pull request. A check that repaired as it read leaves the reader unable to tell a finding from a fix.
+- Emit a verdict across the three axes, or a score across the documents. Two axes answer from verbs and one answers from a reading, so any roll-up is a figure that lies about the third.
+- Report a finding against a file nobody hand-authors. A generated index, a gitignored file, and a copied reference each name a file an author cannot fix.
+- Answer an axis by file inspection where a verb answers it. The verb is the surface under test and a hand-rolled read of the same files is not.
+- Read a document's modification time as its staleness. A file untouched beside code untouched is current, and the timestamp answers a different question.
+
+## Guards
+
+- `canon` absent from the path: stop, since neither measured axis can be read
+- No tracked markdown under the working root: stop, since there is no corpus to read
+
+## Out of scope
+
+- Whether a document exists or holds its required sections, which is the structural question `target-check` answers across six domains
+- Conformance of changed markdown to the authoring standards declaring jurisdiction over its paths, which is `standards-audit`. That skill is diff-scoped and standard-declared, taking a changed file and reporting which stated rule it breaks with a line number. This one is corpus-scoped and reads rot in documents nobody changed, which is the case a diff-scoped audit never reaches. The two sit beside each other rather than one absorbing the other.
+- Rewriting a stale claim once this run has named it, which is `markdown-propose`
+- Running the toolkit's own checks as one gating set over its own corpus, which is `canon audits run`. That set gates a push and this reports to a reader.
+- Repairing anything an axis names. Each routes to the command or skill that owns it.

package/claude/skills/document-health/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: document-health
+description: Reports which of a project's documents have rotted, one section per document, across length, placement, and staleness. Reads each axis through the verb that owns it and marks the evidence class each answer carries. Use when asked to "check document health", "which docs have gone stale", "audit the docs for rot", "are these documents still accurate", "which docs are too long", or after a target check reports the structural side. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use to check whether a document exists or holds the right sections, which is `target-check`.
+---
+
+# Document health
+
+Reports which documents have rotted rather than which are missing. `target-check` answers whether a project's documents exist and hold the right kind of content, and this answers whether the ones that exist still earn their place. It reports and never repairs, matching the structural check beside it.
+
+Three axes carry the report. Two answer from a verb and the third answers from a reading, which it says rather than hiding. `${CLAUDE_SKILL_DIR}/references/axes.md` holds what each axis measures, the checkpoint it reads against, and where a finding routes. This body holds the order, the guards, and the report shape.
+
+## Guards
+
+- `canon` absent from the path: stop. `❌ canon is not on PATH, so neither measured axis can be read.`
+- `git ls-files '*.md'` listing nothing: stop. `❌ No tracked markdown here, so there is no corpus to read.`
+- Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point. A caller reaching this from a rollout wave has nobody present to answer.
+- Branch on each record's own fields rather than on an exit status. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, which reports every refusal as success.
+- Repair nothing, write no file in the project, and open no pull request. Whoever read the report decides what to fix.
+
+## Step 1: scope the corpus
+
+Take the documents the project hand-authors, defaulting to every tracked markdown file the two measured verbs reach. Narrow to a path the caller named when one was given, and say which scope the run took.
+
+Drop what nobody hand-authors before reporting a finding against it: a generated `index.md`, a file under a gitignored folder, and a bundled reference a generator copied out to its consumers. A finding against a copy names a file an author cannot fix, since the next regeneration overwrites it.
+
+## Step 2: read the two measured axes
+
+Run these from the project root, in parallel:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown audit --json
+CANON_NON_INTERACTIVE=1 canon context audit --json
+```
+
+The first answers length, carrying the bullet, paragraph, and depth checkpoints and the per-file weights read against them. The second answers placement for the folders it resolves, carrying entry length, reference form, and index drift.
+
+Then read which classifier would run, and deepen placement with the verdicts per section:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon context classifier show
+CANON_NON_INTERACTIVE=1 canon context classify sweep --json
+```
+
+The first names the backend, the model, and the source that decided both. Report which layer answered, since a project with the model layer off reads from the regex layer alone and the sweep says nothing about which one it used.
+
+Take the checkpoints from the record each verb returns rather than from a number written here. A checkpoint the CLI moves reaches this report with no edit, and a number held in this body goes stale on its own cadence.
+
+### An unread axis is not a healthy one
+
+A refusal, an absent key, and a subcommand the project's binary does not carry each leave an axis unread. Report it as unread against the documents it would have covered, name the read that could not be taken, and name the cause.
+
+`canon context audit` refuses with `reason: "no-folders"` in a project whose folders resolve to nothing, which is the ordinary shape where the layout differs from the one the verb looks for. That refusal is the honest answer rather than a failure, and reading it as an empty finding set reports a healthy corpus for documents nothing looked at.
+
+A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so it is reported with the layer named rather than as an axis nothing reached.
+
+## Step 3: read the staleness axis
+
+No verb answers whether a document still describes the tree it was written about. Read each document against the surfaces it names and report where the two have parted, taking the file paths, commands, and counts it states as the claims to test.
+
+Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
+
+## Step 4: report per document
+
+Give each document its three axes, and give each axis three things: the state, the evidence class, and the command or skill that repairs it. Naming the repair is not running it.
+
+The three classes are what keep the axes apart:
+
+- `measured`: a verb returned a number read against a stated checkpoint
+- `classified`: a verb returned a verdict carrying its own confidence
+- `read`: this session's judgment, backed by no verb
+
+Emit no verdict across the three. Two answer from verbs and one answers from a reading, so a roll-up is a figure that lies about the third. Emit no score across the documents either, for the same reason one level up.
+
+## Output
+
+Lead with the table, then one detail block per document carrying a finding:
+
+```markdown
+Document health: `<scope>`, <n> documents read.
+
+| Document         | Length              | Placement           | Staleness        |
+| ---------------- | ------------------- | ------------------- | ---------------- |
+| `path/to/doc.md` | ok / heavy / unread | ok / moved / unread | ok / stale / n/a |
+
+Length and placement are measured. Staleness is a reading.
+```
+
+Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.

package/claude/skills/document-health/references/axes.md

@@ -0,0 +1,78 @@
+---
+title: Document health axes
+description: What each axis measures, the verb behind it, the evidence class it carries, and where a finding routes
+---
+
+# Document health axes
+
+One section per axis. Each states what it measures, the verb that answers it, the evidence class the answer carries, and the surface a finding routes to.
+
+The skill body holds the order, the guards, and the report shape. This holds the detail a run dereferences once it has a finding to place.
+
+## Length
+
+**Measures:** whether a document, or a passage inside it, has grown past what a reader takes in one pass.
+
+**Verb:** `canon markdown audit --json`.
+
+**Evidence class:** `measured`.
+
+The record carries the checkpoints it read against under `checkpoints` and the per-file weights under `entries`. Read both from the record rather than from a number stated here, since the CLI moves a checkpoint on its own cadence and a copy of one goes stale in place.
+
+Four weights answer this axis, each naming a different shape of overgrowth:
+
+- `heavyBullets`: a top-level bullet past the character checkpoint, which is a paragraph wearing a dash
+- `heavyParagraphs`: a paragraph past the sentence or character checkpoint
+- `longestRun`, against `longestRunLine`: unbroken rendered lines between headings, which is the depth checkpoint
+- `cadence`, carrying `measured`, `flat`, and `repeating`: sentence-length spread and repeated openers
+
+Weight is a judgment a reader settles rather than a defect, which the verb states for itself and which this axis carries forward. A finding here is an argument for a split or a trim rather than a rule broken.
+
+**Routes to:** a split of the document, or a move of the overgrown passage to the surface that owns it. Where the project states what a given document may hold, that statement decides whether the passage belongs in it at all, and the finding routes there rather than to a trim.
+
+**Caveat:** the cadence numbers are drawn from prose a person reads straight through. Terse reference prose sits below that range correctly, so a flat paragraph in a table-heavy or bullet-heavy file is not a finding.
+
+## Placement
+
+**Measures:** whether a document's content sits in the file that owns it, and whether the catalogs pointing at it still resolve.
+
+**Verbs:** `canon context audit --json` for the structural half, `canon context classify sweep --json` for the per-section verdicts.
+
+**Evidence class:** `measured` for the audit's findings, `classified` for the sweep's verdicts.
+
+The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. A citation resolving to nothing is a fact and gates. Entry length, reference form, table shape, and provenance are judgments under every flag.
+
+The sweep classifies each section as keep, replace or rewrite, history, or move. A `move` verdict is the placement finding proper, naming content sitting in the wrong document. Each verdict carries its own confidence, which is why the class is `classified` rather than `measured`, and a low-confidence `move` is a prompt to look rather than an instruction to cut.
+
+**Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
+
+**Caveat:** both verbs resolve their folders by surface root rather than by a path written into them, so a project whose layout differs from the one they look for resolves nothing. The audit says so, refusing with `reason: "no-folders"` and naming the folders it looked for. Report that refusal as an unread axis. The sweep degrades differently: with the model layer off it answers from its regex layer alone, which is a narrower read rather than a refusal, so say which layer answered.
+
+## Staleness
+
+**Measures:** whether a document still describes the tree it was written about.
+
+**Verb:** none.
+
+**Evidence class:** `read`.
+
+This is the axis the operator names first and the one nothing measures. A document goes stale by the tree moving under it rather than by anything changing in the document, so no property of the file answers it and a timestamp answers a different question. A file untouched for a year beside code untouched for a year is current, and one edited yesterday against a refactor from this morning is stale.
+
+Read each document against the surfaces it names. Four claim shapes are testable without leaving the project:
+
+- A file or folder path the document states, against whether it resolves
+- A command or verb the document names, against whether it exists and carries the flags shown
+- A count the document states over a tree, against the tree
+- A cross-reference to another document, against what that document now says
+
+A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
+
+**Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
+
+**Caveat:** a reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class is what keeps the two facts together in the reader's hands.
+
+## Why the three stay apart
+
+The axes are not equally actionable and a report flattening them implies they are. A length finding is a number against a checkpoint, a placement finding is a verdict carrying a confidence, and a staleness finding is a judgment with nothing behind it. Each is worth reporting and each is worth a different response, so the class travels beside the state on every row rather than being stated once in a preamble a reader skims.
+
+Shipping staleness on weaker evidence than the other two is the trade taken deliberately. Cutting it would leave the report answering the two questions that were never the operator's complaint.

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/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

@@ -240,6 +240,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | ------------------------ | --------------------------------------------------------------------------------------- |
 | `canon:review-branch`    | On the local branch diff, before anything is pushed                                     |
 | `canon:standards-audit`  | When changed markdown has to answer to the authoring standards                          |
+| `canon:document-health`  | When the documents themselves have to answer for length, placement, and staleness       |
 | `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
 | `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
 | `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.106.0",
+  "version": "4.108.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

@@ -117,6 +117,16 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Check whether the markdown I changed violates any authoring standards.',
     expect: 'standards-audit',
   },
+  // Rot across documents nobody changed is what separates this from
+  // `standards-audit`, which is diff-scoped and reports a stated rule broken on
+  // a given line. It is also not `target-check`, which asks whether a document
+  // exists and holds its sections rather than whether it still describes the
+  // tree.
+  {
+    prompt:
+      'Which of our docs have gone stale, grown too long, or ended up in the wrong file?',
+    expect: 'document-health',
+  },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
     expect: 'task-board',

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/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 },
     ],

package/src/teach/nav.ts

@@ -17,6 +17,7 @@ import {
   type TeachRefused,
   type WorkspaceDetail,
   type WorkspaceSummary,
+  writeStylesheet,
 } from '@/teach/workspace'
 
 const FAVICON = `<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='10 10 80 80'%3E%3Cpath d='M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z' fill='rgb(224,114,75)' /%3E%3Crect x='44' y='15' width='12' height='70' rx='2' fill='rgb(224,114,75)' /%3E%3C/svg%3E" />`
@@ -769,6 +770,15 @@ interface LessonRefused {
  * check first. Nothing is written when any region is missing, which is what
  * keeps a partially-spliced file off disk.
  */
+/**
+ * A lesson embeds the workspace stylesheet, and an `@import` resolves against
+ * the lesson's own folder there rather than the assets folder, so it never
+ * loaded anything. The base sheet reaches the page through the `<link>`.
+ */
+function stripImports(css: string): string {
+  return css.replace(/^@import[^;]*;[ \t]*\n?/gm, '')
+}
+
 async function rewriteLesson(
   root: string,
   detail: WorkspaceDetail,
@@ -899,6 +909,9 @@ export async function generateNav(
     const detail = found.workspace
     const metas = await readLessonMetas(root, detail)
 
+    const cssPath = join(root, detail.path, TEACH_ASSETS, TEACH_STYLESHEET)
+    if (!existsSync(cssPath)) await writeStylesheet(root, detail.slug)
+
     const contentsPath = join(root, detail.path, 'index.html')
     await writeFile(
       contentsPath,
@@ -906,8 +919,7 @@ export async function generateNav(
     )
     contents.push(relative(root, contentsPath))
 
-    const cssPath = join(root, detail.path, TEACH_ASSETS, TEACH_STYLESHEET)
-    const css = existsSync(cssPath) ? await readFile(cssPath, 'utf8') : ''
+    const css = stripImports(await readFile(cssPath, 'utf8'))
 
     for (let index = 0; index < metas.length; index += 1) {
       const outcome = await rewriteLesson(