@erclx/canon 4.0.0

package/claude/skills/youtube-transcripts/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: youtube-transcripts
+description: Why the transcript fetch stays in the CLI, and why fetching stops short of reading
+---
+
+# Youtube transcripts requirement
+
+## Gap
+
+Without this skill, a pasted video link turns into captions printed in chat, which persist nowhere and cannot be cited by a later session. The file is the point. A transcript saved with its metadata is context the repository holds, and a transcript in a message is context that ends with the turn.
+
+A session that fetches on its own gets the shape wrong. Raw captions carry timing cues and duplicated lines, and a file written without frontmatter has no title, no source URL, and no way to tell which video it came from. Reimplementing the cleanup also duplicates logic the CLI already owns, so the two drift and the drift shows up as inconsistent files rather than as an error.
+
+Two smaller failures follow the fetch. A video with no captions produces a file that looks empty rather than one reported as having none, so the user reads it as a failed fetch. And a session that summarizes what it fetched answers a question nobody asked, spending context on a reading the user may not want yet.
+
+## Must
+
+- Run the CLI, which owns the fetch, the caption cleanup, and the frontmatter
+- Surface the written path as a full relative path, in the form the project's instruction file sets under `## Output`
+- Report a video with no captions as a fact about the video, since the file still exists and carries its metadata
+- Name the missing external binary and stop, leaving the install to the user
+
+## Must not
+
+- Reimplement the fetch or the cleanup
+- Summarize or annotate the transcript unasked, which is a separate request against the file
+- Install the external binary the command shells out to
+
+## Guards
+
+- No URL stops, since there is nothing to fetch
+- A link that is not a YouTube URL stops rather than attempting a generic fetch the command cannot do
+
+## Out of scope
+
+- Downloading the video or its audio
+- Summarizing a transcript already on disk, which is a read of that file
+- Choosing where transcripts live, which the command defaults and a flag overrides

package/claude/skills/youtube-transcripts/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: youtube-transcripts
+description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `canon transcripts`. Use when the user pastes a YouTube URL and asks to "grab the transcript", pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
+---
+
+# YouTube transcripts
+
+Turn a pasted YouTube URL into a markdown file with YAML frontmatter and a cleaned prose body. The `canon transcripts` command owns the fetch, VTT cleanup, and frontmatter. Do not reimplement that logic. The output format and field list live in the toolkit's `.claude/context/transcripts.md`, which a target does not receive.
+
+## Guards
+
+- If no URL is provided, stop: `❌ No URL. Paste a YouTube link to fetch.`
+- If the link is not a YouTube URL, stop: `❌ Not a YouTube URL. This skill fetches YouTube captions only.`
+
+## Prerequisite
+
+The command shells out to the `yt-dlp` binary. If a run fails with a `yt-dlp not found` message, tell the user to install it from `https://github.com/yt-dlp/yt-dlp` and stop. Do not attempt to install it.
+
+## Run
+
+From the project root, fetch the URL:
+
+```bash
+canon transcripts <url>
+```
+
+- Pass `--keep-timestamps` when the user wants `[mm:ss]` markers per line instead of prose.
+- Pass `--out <dir>` to override the output directory. The default is `transcripts/` in the current directory.
+- The written file path prints to stdout. Surface it back to the user as a full relative path, in the form the project's instruction file sets under `## Output`.
+
+## After the fetch
+
+- When the run reports `has_transcript: false`, tell the user the video has no auto-captions. The file still exists with frontmatter for later use.
+- Do not summarize or annotate the transcript unless the user asks. Fetching and reading are separate requests.

package/docs/agents/audits.md

@@ -0,0 +1,98 @@
+---
+title: Audits
+description: Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
+---
+
+# Audits
+
+`canon audits run` runs every audit this repository owns, reports each one under a single verdict, and compares each count to the floor the last recorded run left behind. Nothing here is a new measure. Every number it prints comes from a verb that already published it, which is what makes the command cheap and what separates it from writing another check.
+
+```bash
+canon audits run
+canon audits run --json
+canon audits run --record
+canon audits list --json
+```
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+| `--root <path>` | Measure this tree instead of the current worktree                 |
+| `--record`      | Write this run's tracked counts to `.claude/audits/baseline.json` |
+
+## What it runs
+
+Nineteen verbs, listed by `canon audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+
+The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `canon deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
+
+Sixteen of the nineteen read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads four such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
+
+Each is invoked as the CLI the caller is running rather than as a global `canon`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
+
+## What gates and what reports
+
+Four findings fail the run: an unresolved context citation, a banned character, word, or spelling, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
+
+Three of the four are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
+
+Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
+
+Growth against the baseline reports too. The standards behind the largest measures set no hard cap, so a count that rose is a fact about the corpus and a judgment about whether it matters.
+
+## Exit codes
+
+| Code | Meaning                                                              |
+| ---- | -------------------------------------------------------------------- |
+| `0`  | Every audit reported and none carried a finding that is a fact       |
+| `1`  | Refused, with the reason on stderr                                   |
+| `2`  | An audit carries a finding that is a fact                            |
+| `3`  | An audit did not report, so the run measured less than the whole set |
+
+`3` is a defect in the run rather than in the tree, which is why it takes a code of its own. An aggregate reporting a pass over a set it never finished measuring is the failure the command exists against, so an unparseable record, a verb that could not be started, and an exit no verb documents all land there instead of quietly counting as clean. The `markdown audit` empty-ban-set exit is the precedent: a corpus walked with nothing looked for is a broken check, not a clean tree.
+
+The verdict is published as a field as well as an exit code. A reader branching on `summary.verdict` gets `clean`, `reported`, `findings`, or `incomplete` without inferring the difference between a quiet corpus and one nobody finished measuring.
+
+### An absent corpus is not an unmeasured one
+
+A per-machine folder that is not on this disk reports as `absent` and moves neither the verdict nor the exit code. Every one of those folders is gitignored, so a fresh clone and every CI run carry none of them, and counting six expected absences as failures pins the verdict at `incomplete` forever. A signal that never changes is one nobody reads after the second time they see it.
+
+Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. Several tracked audits override that default too, wherever the corpus not being there is the ordinary state of a target rather than a broken checkout: the secret scan for a project that publishes nothing, the skill corpora, the citation reach check, and the routing measure for a project holding no skills tree, and the context audit for a project that adopted none of the folders it measures.
+
+Everything else stays `unmeasured`. That covers a tree git cannot list, which is a broken checkout, and a package declaring no `files` field, where a publish would pack the whole tree and the scan read none of it. Both are a corpus that exists and went unread, so softening either would report a pass over a shipped tree nobody measured.
+
+Each override exists because the corpus answers the wrong question for that audit. The secret scan earns its from `private: true`, the one declaration that a package is never published, so a project carrying it reports an absent corpus rather than a broken one. Without that the aggregate would report `incomplete` in every such project on every run, which is the permanent signal this section opens by rejecting.
+
+`upstream` is the third corpus value, carried by the advisory check alone. Its count moves when someone publishes rather than when someone edits here, so it is kept out of the retained baseline for the mirror image of the reason gitignored scratch is, and an offline run reports it absent rather than pinning the verdict at `incomplete` on every machine without a network.
+
+Every run states how many corpora it measured against how many it skipped, including a run with no findings at all. A count of what passed reads as a verdict on the whole set unless the run also says what it never reached.
+
+### What a shallow checkout changes
+
+`canon gov test-order` scopes its range against the trunk and falls back to the root commit when no trunk ref resolves. A depth-1 checkout has neither, so the range is empty and the verb reports zero of everything rather than refusing. The numbers are real for the history present, which means a shallow run under-reports against a baseline taken from a full clone and shows as shrinkage. That is the safe direction, and it is the reason a `test-order` delta is worth reading only from a clone carrying the history.
+
+## The retained baseline
+
+`.claude/audits/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at. Each later run reports which counts moved and by how much.
+
+The file is committed. A per-machine record cannot answer the question this half exists for, which is whether a number grew since anyone last looked, and a fresh checkout has to inherit that answer rather than start over. The cost is that a branch moving a count either fixes it or re-records it and says why, which is the shape the consumed-copy assertion already carries.
+
+It sits under the project root rather than beside the aggregator in `src/`. The numbers describe one repository's corpus, and `src/` ships to every project that installs the CLI, so a baseline in the package would hand a target these counts to measure its own tree against.
+
+### What is kept out of it
+
+A gitignored record folder holds one machine's session scratch. Its counts describe somebody else's disk, so committing them writes a floor no other clone can reproduce and every contributor reads a regression against a number that was never about their tree. The board and five of the six record kinds are therefore reported on every run and recorded in none. `records-standards` is the exception, because that corpus is tracked.
+
+An audit that did not report is left out rather than written as zero. Zero there records a clean corpus nobody measured, and the next run reads its real numbers as a regression against a floor that was never taken.
+
+### The first run
+
+A run with no baseline behind it says so rather than showing a delta of zero. Those two states say the same thing to a reader and mean opposite things, which is a defect this repository has already had to fix twice elsewhere. The same reasoning covers a check the baseline never recorded, a key the run produced that the record does not carry, and a key the record carries that this run did not produce. Each is named for what it is.
+
+A hand-edited baseline that does not parse refuses the whole run. Reading a broken record as an absent one would reset the floor the file exists to hold, silently.
+
+## In the verify pipeline
+
+`bun run check` runs the set as a reporting stage after the three gating stages, and never fails on it. Those three stages keep their own specific remedies, so the aggregate reports the rest and the growth, and a fact still fails the push at the stage that names what to do about it.
+
+The stage reads `summary`, a flat object of scalars published beside the nested arrays. Every key in it is unique across the whole record, so a shell stage greps one out without a JSON parser. The three verbs the gating stages already ran walk their trees a second time here, which is the 0.8 seconds measured above and the reason the whole set runs rather than only the part those stages skip: one verdict over every audit is the value, and a stage measuring a subset would report a health nobody took.

package/docs/agents/capture.md

@@ -0,0 +1,37 @@
+---
+title: Capture
+description: Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+---
+
+# Capture
+
+`canon capture [source]` renders HTML capture sources to PNG, which is how a committed documentation image regenerates from its committed source. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same bare command.
+
+```bash
+canon capture
+canon capture assets/install.html
+canon capture assets --out .claude/review/captures
+```
+
+`assets/` now holds two sources, so a bare `canon capture` rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference.
+
+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/hero.html` when the check reports the 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. Nothing hand-edits it, and 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.
+
+| Option             | Behavior                                          |
+| ------------------ | ------------------------------------------------- |
+| `--out <dir>`      | Write every PNG here instead of beside its source |
+| `--selector <sel>` | Element to capture (default: `.window`)           |
+
+## What the command asserts
+
+Each source renders at `deviceScaleFactor` 2 with a transparent background, and the success line reports the pixel dimensions the element wrapped to. Size is reported and never asserted. The height of a terminal frame is whatever its text wrapped to at a fixed width, so pinning that number would harden an accident.
+
+What is asserted is the font. The command reads the first family the captured element declares and fails when the browser did not resolve it, because a fallback face rewraps the block and silently changes the output. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
+
+The browser binary installs separately from the package. A fresh clone runs `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
+
+The command is toolkit-only. Its render module holds every browser reference capture makes and `files` in `package.json` excludes it, so an installed `canon` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
+
+`canon demo` is the other browser command and it ships, because the reason capture stays here is that it regenerates images committed to this repository and a target has nothing to regenerate. See `demo.md`.

package/docs/agents/census.md

@@ -0,0 +1,23 @@
+---
+title: Census
+description: Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
+---
+
+# Census
+
+`canon census [path]` reports how large a tree is: the tracked-plus-untracked file count, a breakdown by extension, and a line total. It reads `listRepositoryFiles`, the same corpus the citation check, the markdown corpus, and the secret scan already read, so this is not a fourth definition of what counts.
+
+```bash
+canon census
+canon census src --json
+```
+
+| Option   | Behavior                                                   |
+| -------- | ---------------------------------------------------------- |
+| `--json` | Add a machine-readable record on stdout, keeping the frame |
+
+Grouping is by extension rather than by a named language category. A config file and a source file land in separate buckets and two source files sharing an extension land in one, and a file with no extension, such as `Dockerfile`, lands under `no-extension`.
+
+Line counts are text-only. A file that reads as binary, and a file git lists that will not open, such as a symlink leaving the tree, are counted toward the file total and their extension's file count, and left out of every line count. The record's `skipped` field states that gap rather than leaving a reader to infer it from the difference between the file count and the summed extension line counts. It carries both causes as one number: on a healthy tree the two are indistinguishable, so a `skipped` count above what the tree's own binary files explain is itself the signal that something in the corpus will not open.
+
+The command reports a snapshot rather than a delta. It registers in the audit catalog with an empty gating set, so `canon audits run --record` is what turns two snapshots into the growth series a hand count used to approximate: 481 files on one date and 965 five weeks later, with nothing between them because nobody had counted again.

package/docs/agents/commands.md

@@ -0,0 +1,146 @@
+---
+title: Command catalog
+description: Every project-level command and every domain subcommand, plus the shape each domain exposes
+---
+
+# Command catalog
+
+Full help: `canon <command> --help`. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
+
+## Project-level
+
+| Command                     | Purpose                                                                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon init [path]`         | Bootstrap a project with selected toolkit domains                                                                                                                     |
+| `canon sync [path]`         | Sync all installed domains in a target project                                                                                                                        |
+| `canon sync --check`        | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                                                 |
+| `canon sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                                                    |
+| `canon sandbox reset`       | Reset sandbox to baseline                                                                                                                                             |
+| `canon sandbox clean`       | Wipe the sandbox                                                                                                                                                      |
+| `canon sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                                                                 |
+| `canon sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                                                                        |
+| `canon indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                                                                                                  |
+| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                              |
+| `canon design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                     |
+| `canon slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                                                                                            |
+| `canon slides list`         | List the available slide layouts (`--json` for the catalog)                                                                                                           |
+| `canon feedback`            | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github`                                                               |
+| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                 |
+| `canon tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                                                   |
+| `canon tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                              |
+| `canon tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                                             |
+| `canon tasks validate`      | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`)                                                           |
+| `canon intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                                                 |
+| `canon intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                                                        |
+| `canon teach list`          | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                                                    |
+| `canon teach open`          | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                                       |
+| `canon teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                                                 |
+| `canon teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                                                   |
+| `canon records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                          |
+| `canon records migrate`     | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                        |
+| `canon records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                          |
+| `canon records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                            |
+| `canon records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
+| `canon migrate rename`      | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
+| `canon sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
+| `canon worktrees list`      | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
+| `canon comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
+| `canon context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                             |
+| `canon markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                |
+| `canon claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                        |
+| `canon standards audit`     | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                 |
+| `canon claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                             |
+| `canon claude skills reach` | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one                                            |
+| `canon claude skills rank`  | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)                       |
+| `canon claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                                        |
+| `canon gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                                               |
+| `canon gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`) |
+| `canon gov restated`        | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`)  |
+| `canon gov citations`       | Resolve every path a rule cites and every internal frontmatter glob, failing on one reaching nothing (`--json`)                                                       |
+| `canon secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                                                 |
+| `canon deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)                        |
+| `canon labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
+| `canon labels scan`         | Fail a pull request whose title or body carries a phase label, sorting a release pull request's tokens as semver rather than as a leak (`--event`, `--json`)          |
+| `canon autoship classify`   | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
+| `canon pr key-changes`      | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
+| `canon census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                  |
+| `canon audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                                |
+| `canon audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                             |
+| `canon gate run`            | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                           |
+| `canon inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                  |
+| `canon capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
+| `canon serve [dir]`         | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                               |
+| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                 |
+
+`canon serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
+
+A port already in use is the ordinary case rather than a refusal, so it walks forward to the next free one and reports which it took. That is why a caller reads `url` off the `--json` record instead of composing one from the port it asked for. Only contention is walked past. Any other bind failure refuses as `bind-failed` carrying the error's code, rather than being retried twenty times and reported as a range being full, which names a cause nothing checked.
+
+A request naming a directory is redirected to its trailing-slash form rather than answered in place. A browser resolves a relative asset against the last slash of the URL it is on, so answering `/lesson` directly leaves the page asking for `/course.css` instead of `/lesson/course.css`, and it renders unstyled through the server that exists to prevent exactly that.
+
+Containment is tested after symlinks are followed rather than on the path as written, and the test sits immediately before the read rather than beside the request that produced it. Resolving a request lexically clears a link pointing outside the served root, and this repository is a live instance of that shape, since `claude/standards` and `claude/snippets` are links out of `claude/`. Position is what makes the property hold: a directory request appends its index after the request path has been checked, so a check placed earlier leaves that index untested. An `--entry` that escapes the root refuses with `no-entry` before a port is taken, because `url` is the field a caller hands to a reader.
+
+`canon demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
+
+`canon inventory` is the third and takes the same answer for the same reason. It reads `inventory.toml` at the project root for its base URL, its routes, and the element query each subject runs over, so what it walks comes from the project rather than from the toolkit. It reports how many different answers a site gives for one property and never gates, because whether five focus rings across four routes is a defect is a judgment. A missing server and an unmatched query are both refusals rather than empty listings, since a listing with no rows reads as one consistent answer.
+
+```toml
+base-url = "http://localhost:4173"
+routes = ["/", "/pricing", "/docs"]
+
+[subjects.focus]
+query = "button, a[href], input, select, textarea, [tabindex]"
+```
+
+## Domain commands
+
+Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
+
+| Domain      | Subcommands                                                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                                |
+| `snippets`  | `list`, `create`                                                                                                                      |
+| `standards` | `list`, `audit`, `<name>`                                                                                                             |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`, `citations`                                                  |
+| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
+| `demo`      | `compile`, `run`                                                                                                                      |
+| `inventory` | `run`                                                                                                                                 |
+| `wiki`      | `init`                                                                                                                                |
+| `design`    | `render`                                                                                                                              |
+| `slides`    | `render`, `list`                                                                                                                      |
+| `tasks`     | `archive`, `validate`                                                                                                                 |
+| `intake`    | `list`, `answer`                                                                                                                      |
+| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                                |
+| `comments`  | `scan`                                                                                                                                |
+| `context`   | `audit`                                                                                                                               |
+| `markdown`  | `audit`                                                                                                                               |
+| `secrets`   | `scan`                                                                                                                                |
+| `deps`      | `audit`                                                                                                                               |
+| `labels`    | `audit`                                                                                                                               |
+| `migrate`   | `rename`                                                                                                                              |
+| `autoship`  | `classify`                                                                                                                            |
+| `audits`    | `run`, `list`                                                                                                                         |
+| `gate`      | `run`                                                                                                                                 |
+
+Common patterns:
+
+- `list --json` → machine-readable catalog on stdout.
+- `install <name> <path>` → install a specific entry into a target project.
+- `sync <path>` → reapply all installed entries in a target project.
+- `create [name]` → scaffold a new authoring entry in this repo.
+
+`migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
+
+## Version skew
+
+`canon sync --check` and `canon claude skills drift` are the two moments a target
+already stops to reconcile with the toolkit, so each reports the installed
+version against the newest published one. No other command performs the lookup,
+which keeps a registry round trip out of the catalog reads an agent runs in a
+loop.
+
+The report carries three states and never changes an exit code. `behind` names
+`canon upgrade` as the remedy, `current` says so, and `unknown` carries the
+reason the registry could not be reached. Branch on the `skew.state` field in
+the JSON record rather than on the exit, since an offline machine has to read as
+unmeasured rather than as a failing check.

package/docs/agents/comments.md

@@ -0,0 +1,34 @@
+---
+title: Comments
+description: Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
+---
+
+# Comments
+
+`canon comments scan [path]` reports comment density for a tree, split by language and by comment kind. It is the only command that parses the target's own source, so its scope stays deliberately narrow: TypeScript and bash, line-oriented, no AST.
+
+```bash
+canon comments scan
+canon comments scan src --json
+canon comments scan --since v0.5.0
+```
+
+| Option               | Behavior                                                        |
+| -------------------- | --------------------------------------------------------------- |
+| `--json`             | Add a machine-readable record on stdout, keeping the frame      |
+| `--since <rev>`      | Report the trend from this revision instead of a snapshot alone |
+| `--languages <list>` | Comma-separated subset of `ts,sh` (default: both)               |
+
+A line counts as a comment when its first non-whitespace token opens one, which is what keeps a URL in a string literal from reading as a `//` comment without a parser. Density is `commentLines / lines`, reported and never graded. The command produces the number and a rule produces the judgment.
+
+Two exclusions are structural rather than tuning. Heredoc bodies are dropped from both the numerator and the denominator, because a scenario script carrying markdown inside one has `#` opening a heading rather than a comment, which inflated a measured 112 comment lines to 427. Fixture trees are pruned by path segment for the same reason. The line-1 shebang is not a comment, since every script has one and counting it puts a floor under density that reports the file count.
+
+`--since` recomputes each point from git via `ls-tree` and `cat-file --batch`, checking nothing out. No ledger is written or read. Six points spread evenly across the window by default, and the boundary revision is always included so the series keeps the reading it is measured against.
+
+This works only because density is a pure function of a tree. Which author or session wrote a comment is not recoverable from git and does not belong here.
+
+## Degradation sweep
+
+The degradation sweep reads its vocabulary from whichever rule publishes a `## Degradation vocabulary` heading, preferring `.claude/rules/` over `governance/rules/`, so one definition serves the toolkit and every target. Discovery anchors on the heading rather than a filename, because a renumbered rule would otherwise empty the vocabulary while the sweep still reported clean. With no such rule the sweep reports **skipped** rather than zero hits, since finding nothing and looking for nothing mean opposite things.
+
+`090-code-comments` is the rule that publishes the list, and it ships on the `base` stack. A project that installs or syncs governance for the first time after that rule landed gets a sweep that previously reported skipped, so hits appear where the command used to stay quiet. Edit the backticked terms in the installed copy to change what that project sweeps for. The sweep matches comment text, so a comment naming a term as an example is a hit, and a hit is a prompt to read the line rather than a verdict on it.

package/docs/agents/context-audit-checks.md

@@ -0,0 +1,120 @@
+---
+title: Context audit checks
+description: What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
+---
+
+# Context audit checks
+
+What each finding from `canon context audit` means. The command surface, its flags, and the two gating checks are in `context-audit.md`.
+
+## Required sections
+
+The required-section check reports what does not declare `## Overview` and `## Layout`, the two sections `standards/context.md` marks required. The list is held in code beside the numeric checkpoints rather than parsed out of the standard, so it fails on a defect rather than on a rewrite of the wording around it. A heading at any level counts, because a domain that split into a folder carries its overview in a sibling named `overview.md` where the section is the `#` title and an `##` beneath it would repeat the filename. Matching exactly is what keeps `## Layout catalog` from satisfying `Layout`.
+
+Which unit answers depends on the folder. Entries of the folder named under `.claude/` are one domain each, so each answers for itself and a finding names the entry. Entries of a folder a domain split into describe that one domain between them, so any sibling answers and a finding names the folder. Holding a split folder to the rule per file would report every child beside its `overview.md`, and rolling the named folder up would let one conforming entry stand in for every other domain sitting next to it.
+
+It reports rather than gates by default, the closer call because a missing section reads more like a fact than the other judgments. What settles it is that the standard sanctions omitting `## Layout` from a domain owning no paths in the repo, and no measure separates that from an entry that forgot it. A domain covering only external tools is that case, and it reports on every run. The JSON record carries the findings as `missingSections` and the list as `checkpoints.requiredSections`.
+
+`--gate` promotes the finding to a failing exit code, which the seed stage runs and no other caller does. That mode needs an answer to the sanctioned omission above, so a file declaring `stub: true` in its frontmatter is dropped before the check and reported nowhere. Both are described in `context-audit.md`.
+
+## Reference form
+
+The reference-form check reports an entry naming a sibling entry by bare filename where `standards/context.md` asks for the path it sits at. A bare name resolves against whichever folder its reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A path is checkable, which is what makes the form rule worth measuring at all: once a reference spells its path, the citation gate resolves it and a split that moves the file fails the push.
+
+A finding is a backticked filename carrying no folder, matched against the entries beside the one that wrote it. The backticks are required, since a filename in running prose is not a reference a reader follows.
+
+A name matching no sibling is left alone, which is the measure reaching less than the rule does rather than the rule stopping there. The standard governs a reference to any other entry, so a split entry naming one that sits in a different folder is a violation this check never sees. What the sibling set buys is that a name resolving inside the folder is a reference by construction, where a bare filename matched anywhere would report every sentence that happens to name a file.
+
+An entry naming itself is left alone on separate grounds, since no split can strand it. Fenced blocks are excluded with the scans above, and a line carrying the citation ignore marker is excluded because that marker already means the line displays a name rather than pointing at one.
+
+The check covers the folders a domain split into and stops at the flat folder above them. A split folder's entries are named for sub-areas of one domain, so a bare name matching one of them points at it. The flat folder's entries are named for whole domains, and a domain name is a common noun that a seed or another tree spells the same way, which is where both false positives measured against this corpus sat. What the exemption costs is the references a future split of the flat folder would strand, and it is taken because a report firing on correct prose teaches a reader to stop reading the section.
+
+It reports and never gates, which is the split the citation check already draws. An unresolved path is a fact and a form violation is a judgment with a measured false-positive rate, the same line `canon markdown audit` draws between a ban and a weight checkpoint. The JSON record carries the findings per entry as `entries[].bareReferences`.
+
+## Length
+
+Length quotes its checkpoint from `standards/context.md`: roughly 150 rendered lines for an entry, applied to each of the 60 entries the audit measures, 51 of them under `.claude/context/` and 9 diagram files beside them. It counts rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights.
+
+A line is wrapped at the width it renders at, so a link counts as its anchor text and a backticked path counts whole, which parts the rendered count from a source count wherever an entry cites a path in backticks rather than as a link. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see.
+
+The measure counts fenced blocks and frontmatter, so a reference-heavy entry ranks by its examples, which the legend states on every run alongside the width, since a number in rendered lines cannot be reproduced without it.
+
+Every entry past the checkpoint carries the three questions the standard asks of it rather than a count alone: whether it still covers one domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. The checkpoint is not a cap, so the count is not the finding. What a reader acts on is which question came back true, and the standard directs the fix at that rather than at the number.
+
+Only the third is mechanical, and it is the provenance check already reported below, so the length finding cites that count rather than measuring it again. What it cites is a count of change markers, which is why an entry recording what its own runs cost answers `no` there while carrying dates throughout. An entry outside the governed folder reads open there too, since provenance is scoped to the standard stating it and a clean list there is a scan that never ran. The other two stay open beside every entry, because whether a domain is still one domain is a judgment about its subject and recognizing reproduced content needs a reader who knows what those commands emit. Omitting them would read as an entry nothing found rather than one nothing checked.
+
+It reports and never gates, which the standard settles rather than the usual judgment-against-fact line: there is no hard cap, so an entry that answers all three and is still long is a correct outcome. The JSON record carries the joined findings as `length`, each with a `causes` array in the standard's order, and the jurisdiction the join reads as `entries[].governed`. That flag is what parts a provenance list measured and empty from one never scanned, which the count alone cannot say. The join is published rather than left to a consumer, since deriving it means restating which question the provenance count answers.
+
+Depth and bullet weight are quoted from `standards/markdown.md`, which states both over every markdown file rather than over a context entry, so `canon markdown audit` measures them and this command no longer does. They share `renderedHeight` with the length measure, since the two checkpoints sit in one section of that standard and a reader compares them. What the split costs is that a session wanting both numbers for one entry runs two commands, and what it buys is that either number can be had for a file in a folder this audit refuses to resolve.
+
+## Tables
+
+The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose. It stays here rather than moving with depth, because the shape it routes a catalog into is a judgment the context standard makes about an entry.
+
+## Provenance
+
+The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open.
+
+A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on #632 and #634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts.
+
+A release label reports with or without its leading `v` at three segments, since the rule cuts the label rather than a spelling of it. Two segments still need the `v`, which keeps a dollar cost and a duration out. Another tool's version reports too, and the check cannot tell one from a release, so treat a version beside a tool name as a line to read rather than one to cut.
+
+Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
+
+## Narration
+
+The narration check reports a bullet that states the design a sibling bullet replaced instead of rewriting it. `standards/context.md` asks for the rewrite because the subject is still live and two bullets on one subject leave a reader to work out which of them is current, and no other measure sees that shape.
+
+It reads structure rather than words, which the corpus decided. Measured across the 39 entries this toolkit held the day it shipped, the terms carrying clean signal for a supersession are too rare to catch anything: `superseded` appears twice, `previously` three times, and `formerly`, `originally`, and `at first` never. The one term that would have caught the case a review caught by hand is `now`, which appears 57 times across 24 entries in correct present-tense prose. A list including it reports 57 lines to catch one, and a list excluding it reports nothing.
+
+What it matches instead is a bullet doing three things at once: opening with a pronoun whose antecedent is the bullet above it, carrying a past-tense verb, and following another top-level bullet. All three are required. Eight bullets in the corpus open with a back-reference, and the verb set narrows those to one.
+
+The pronoun is matched cased and anchored to the opening, since a mid-sentence `this` is a determiner rather than a reference back. The verb is matched uncased anywhere in the bullet, and rejected when a copula sits in front of it, since `is used to resolve the folder` is the passive of `use` rather than the past habitual the set means.
+
+Both sets are published under `## Narration pronouns` and `## Narration verbs` in a governance rule and read at run time, so widening either costs a rule edit rather than a TypeScript change. The copula list stays in code, because it is English grammar rather than corpus vocabulary and a rule publishing two of three headings would be another absent state to carry. Discovery keys on the headings rather than the filename, because rules are numbered and a renumber would empty the sets while the check kept reporting clean. A run finding no rule that publishes both says it scanned nothing rather than reporting clean.
+
+A blank line does not end the run. Markdown reads the bullets around one as a single loose list, so a walker that broke there would leave the shape reachable by anyone who spaced their bullets out. What ends a run is content that is neither a bullet nor indented under one, which is what keeps the first bullet under a heading from reading as a reply to the last bullet above it.
+
+A fence answers that test for itself, because every scan here skips a fenced line before reaching it. An unindented fence ends the run, since CommonMark reads one at column zero as interrupting the list and the bullets around it are then two lists with no antecedent crossing between them. A fence indented under its bullet stays inside the item and leaves the run intact.
+
+The opening delimiter decides that for the whole block rather than each line deciding for itself. A blank line inside an indented fence carries no indentation to read, and a content line may sit at column zero inside one because CommonMark strips the fence's own indent and nothing further. Reading either as unindented ends a run that should have continued, which costs findings rather than inventing them, so no corpus count moves when it is wrong.
+
+Two fenced blocks with nothing between them are one contiguous run of fenced lines, so the mark alone cannot say where the first ends. The line walker reports which block each line sits in, and the boundary re-reads indentation whenever that number changes, so an unindented block written directly behind an indented one ends the run rather than inheriting the answer above it. No markdown file this repository tracks holds that shape, because a formatter inserts a blank line between two fences on contact, and a target running these commands over an unformatted tree still can.
+
+Precision is the whole value, so recall is the accepted exposure, and two shapes are knowingly out of reach. A narration written as one bullet carrying its own before and after slips through, and nothing else sees it either. So does the perfect passive, since `has been superseded` narrates a supersession and the copula guard rejects it with the passives it exists for.
+
+A rejected alternative is a back-reference in the past tense by construction, and the standard keeps what was tried and why it lost, so a legitimate hit exists and no measure separates it from a violation. The report states that on every run, which is why the finding names a line to read rather than a line to delete.
+
+The JSON record carries the findings per entry as `entries[].narration` and the sets as `checkpoints.narration`, which is absent under `--citations-only` where the run never loads them and null where no rule publishes both.
+
+## The architecture record
+
+Two findings read `.claude/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
+
+The length check compares the record against the ceiling it derives for itself, and only a record that states its own allowances has one. No standard sets a length rule for this document, so the numbers belong to whichever record declares them. The check reads a frame allowance and an allowance per decision out of the record's own prose and puts the ceiling at the frame plus the allowance times the decision count. The JSON record carries what it read as `architecture.allowances` and the reading as `architecture.lines` against `architecture.ceiling`.
+
+A record stating no such rule is measured and reported and never gated, which is the ordinary shape of a project that wrote an architecture record and no convention about its length. Holding a pair of numbers in the toolkit and gating every project against them would fail a record on a ceiling that project never agreed to, and the framed line would credit the rule to a file that does not state it.
+
+What the derivation costs where it does apply is that the ceiling rises when a decision is added and falls for nothing, so the check passes exactly when the file grew. It gates anyway, because a record that states a limit for itself and makes it computable from a count has turned it into a fact, which is what separates it from every judgment below. A rewrite of the declaring sentence past the clauses the check reads falls back to reporting rather than to a stale ceiling, so the failure shows up in the run's own output.
+
+The coverage report classifies each decision as carrying a countable claim, a structural invariant, or neither, then reports each testable entry against whether it names a check that exists. A countable claim carries a figure a run could recompute, and an invariant quantifies over a named tree closely enough that a walk could falsify it. A check is a `scripts/**.sh` path the entry spells that is on disk, or a `canon` invocation matching a registered audit, so coverage reads the entry rather than the tree and a claim some check happens to cover without the entry saying so reads as unchecked.
+
+Three limits are stated on every run rather than hidden. The countable signal reads digits alone, so a measured claim written in words reads as uncounted. Entries are counted by heading, and one heading holding several decisions counts once. Nothing is stored, so an entry rewritten tomorrow is classified afresh the next time the verb runs and no verdict goes stale.
+
+The report gates nothing. Deciding whether a sentence states a claim is a judgment no parser settles, so the output names candidates for a reader. This answers a different question from the verification anchors `standards/architecture.md` describes, which record that one cited number was re-read. That mechanism says whether a marked figure held, and this one says how much of the record could be checked at all.
+
+## Which folders each check reaches
+
+The provenance, required-section, and narration checks cover `.claude/context/` alone, the reference-form check covers the split folders inside it, and length and the table finding reach every audited folder.
+
+What narrows the three is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere, and a diagram entry carries a heading per kind rather than a run of bullets deciding anything. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
+
+Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: the names are the context standard's own, and neither sibling standard states a required section at all.
+
+The same test is what moved depth and bullet weight out of this command entirely. A rule stated at the attribute tier reaches every markdown file, and a check reaching every markdown file has no reason to require a folder that resolves.
+
+The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
+
+## Index drift
+
+Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.