@erclx/canon 5.38.0 → 5.39.0

package/docs/agents/commands.md

@@ -1,154 +0,0 @@
----
-title: Command catalog
-description: Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report
----
-
-# Command catalog
-
-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. A pipe gets the same text without the frame glyphs. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
-
-`canon <command> --help` lists subcommands, and `canon <command> <subcommand> --help` a leaf's flags, exit codes, and examples. `canon <command> --help --all` prints both. An unknown subcommand exits 1 under a group taking no operand.
-
-## Project-level
-
-One row per top-level command, in the order `canon --help` prints them. A domain's subcommands are in `## Domain commands` below.
-
-| Command                     | Purpose                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------ |
-| `canon init [path]`         | Bootstrap a project with selected toolkit domains                                          |
-| `canon sync [path]`         | Sync every installed domain, or report drift and version skew with `--check`               |
-| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names                 |
-| `canon migrate <verb>`      | Move a project off a retired name or layout, reporting the plan until `--write`            |
-| `canon targets <verb>`      | Report the projects this toolkit installed into                                            |
-| `canon gov <verb>`          | Install and sync governance rules, and audit the tree against them                         |
-| `canon tooling <verb>`      | Sync, diff, and verify tooling stacks                                                      |
-| `canon claude <verb>`       | Install the Claude workflow and audit both skill corpora                                   |
-| `canon wiki <verb>`         | Scaffold the wiki pages                                                                    |
-| `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them                      |
-| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                   |
-| `canon design <verb>`       | Render or regenerate `canon/DESIGN.md` tokens, emit their CSS, install the base stylesheet |
-| `canon slides <verb>`       | Render a deck folder of HTML slides, or list the decks                                     |
-| `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved                          |
-| `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                             |
-| `canon demo <verb>`         | Compile and record a running app                                                           |
-| `canon inventory [subject]` | Group every route's elements by one computed property, never gating                        |
-| `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                              |
-| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                      |
-| `canon teach <verb>`        | Open and author learning workspaces                                                        |
-| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them             |
-| `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                                 |
-| `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive                         |
-| `canon intake <verb>`       | Report intake folders and write answers into them                                          |
-| `canon records <verb>`      | Validate, size, prune, and back up the session records                                     |
-| `canon sessions <verb>`     | Resolve live sessions to worktree and branch, and move one between machines                |
-| `canon worktrees <verb>`    | Report and remove worktrees whose pull request merged                                      |
-| `canon hooks <verb>`        | Run the steps a git hook drives                                                            |
-| `canon pr <verb>`           | Read a pull request's diff, head, checks, and review, and post its evidence                |
-| `canon feedback`            | Open a GitHub issue from toolkit feedback on stdin, or print the block on failure          |
-| `canon audits <verb>`       | Run every audit as one set under one verdict against the recorded baseline                 |
-| `canon gate <verb>`         | Run every stage that guards a branch here                                                  |
-| `canon secrets <verb>`      | Report credential-shaped values in the tree the package ships                              |
-| `canon deps <verb>`         | Report published advisories against the resolved dependency set                            |
-| `canon labels <verb>`       | Read a changed set against the label map, and scan pull request text                       |
-| `canon comments <verb>`     | Measure comment density by language and kind, with a trend from git                        |
-| `canon context <verb>`      | Report context folder health, and classify changed or stale sections                       |
-| `canon markdown <verb>`     | Fail markdown on a banned character or a dead link, and report its structure               |
-| `canon census [path]`       | Report tracked file count, extensions, and a line total skipping binaries                  |
-| `canon upstream <verb>`     | Read Claude Code releases from a cursor, and list the toolkit's own mechanisms             |
-
-`canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses 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. A teach lesson's stylesheet is embedded rather than linked, so only its script still needs a server. 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 a link out of the served root is the shape it guards against. 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. `--index` answers a directory holding no `index.html` with a listing read per request, where the default stays a 404. Every entry the listing names takes the same containment test a request for it would, so a link out of the root is absent rather than greyed, and dotfiles are hidden. With no `--entry` and no root `index.html`, the printed link is `/` and `entryExists` reads true. 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]"
-```
-
-`canon drive` is the fourth and ships for the same reason the three before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
-
-## Domain commands
-
-Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`. The page named beside a domain carries its flags, records, and refusals, and `canon <domain> --help --all` prints every subcommand's flags.
-
-- **`migrate`**, in `migrate.md`: `rename`, `skill-names`, `records`, `surface-roots`, `record-tree`, `rule-layout`, `scratch-evidence`, `record-layout`
-- **`targets`**, in `targets.md`: `list`, `pulls`
-- **`gov`**, in `install-and-sync.md`: `list`, `install`, `sync`, `build`, `regen`, `detect` (in `gov-detect.md`), `test-order`, `counts`, `superseded`, `citations`, `restated`
-- **`tooling`**, in `install-and-sync.md`: `list`, `sync`, `diff`, `reference`, `verify`, `inject`, `prune-gitignore`
-- **`claude`**, in `skills-audit.md`: `init`, `sync`, `setup`, `routing`, `plugin-update`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`
-- **`wiki`**, in `scripting.md`: `init`
-- **`indexes`**, in `indexes.md`: `regen`, `list`
-- **`docs`**, in `docs.md`: `list`, `<topic>`
-- **`design`**, in `install-and-sync.md` for `install`, `sync`, and `fonts`, and below for the rest: `render`, `regen`, `css`, `install`, `sync`, `fonts`
-- **`slides`**, described below: `render`, `list`
-- **`demo`**, in `demo.md`: `compile`, `run`, `frames`
-- **`inventory`**, described above: `run`
-- **`teach`**, in `teach.md`: `list`, `up`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`
-- **`canvas`**, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `frame resize`, `fit`, `arrange`, `selection`, `edit`, `editing`, `capture`
-- **`sandbox`**, in `sandbox.md`: `run`, `equivalence`, `reset`, `clean`, `check`, `coverage`
-- **`tasks`**, in `tasks.md`: `next-label`, `archive`, `decline`, `plan-citations`, `plan-answers`, `plan-branch`, `plan-reach`, `plan-link`, `pull-request`, `outcome`, `list`, `validate`
-- **`intake`**, in `intake.md`: `list`, `answer`
-- **`records`**, in `records.md`: `validate`, `ordinal`, `size`, `stale`, `prune-tmp`, `push`, `pull`
-- **`sessions`**, in `sessions.md`: `list`, `export`, `import`
-- **`worktrees`**, in `worktrees.md`: `list`, `reclaim`, `repair-bare-flag` (hidden)
-- **`hooks`**, in `hooks.md`: `post-merge`
-- **`pr`**, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`, `frames`, `lift` (in `pr-lift.md`), `tick` (in `pr-tick.md`)
-- **`upstream`**, in `upstream.md`: `fetch`, `catalog`, `due`, `advance`
-- **`audits`**, in `audits.md`: `run`, `list`
-- **`gate`**, in `gate.md`: `run`
-- **`secrets`**, in `state-scoped-risk.md`: `scan`
-- **`deps`**, in `state-scoped-risk.md`: `audit`
-- **`labels`**, in `label-coverage.md`: `audit`, `apply`, `scan`
-- **`comments`**, in `comments.md`: `scan`
-- **`context`**, in `context-audit.md`: `audit`, `classify diff`, `classify sweep`, `classifier show`, `classifier set`
-- **`markdown`**, in `markdown-audit.md`: `audit`
-
-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.
-
-Subcommands no other page describes:
-
-- **`claude plugin-update`** matches the installed marketplace plugin against `claude/.claude-plugin/plugin.json`'s own name and runs `claude plugin update` on it, reading the version back off `claude plugin list --json`, since the update call reports none of its own (`--json`).
-- **`claude skills rank`** scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
-- **`design regen`** rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
-- **`slides list --json`** emits one row per deck under `.canon/slides/`, carrying `name`, `title`, `slides`, and `path`.
-- **`slides render [deck]`** takes a deck name or a folder, defaulting to the only deck, and lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
-- **`slides.md`** describes a deck folder's `deck.json` and the faces it embeds, its per-slide `<body>` attributes, transitions and entrances, speaker notes, and charts.
-- **`canvas`**, with its verbs, content format, and write routes, is described in `canvas.md`.
-- **`labels apply <number>`** adds the labels this branch earns to its open pull request, refusing a pull request whose head is not the current branch or that is not open, and never creating a label the remote lacks or removing one a person added (`--check` writes nothing and exits 2 when labels are owed, `--base`, `--json`).
-- **`labels scan`** fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a banned character, a body heading outside the closed section list or a missing `## Summary` or `## Key changes`, or a title breaking `claude/skills/git-pr/references/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
-
-## 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.
-
-`canon upgrade --json` carries one further state, `pending`, that the skew
-report does not: the working directory's checkout holds a release npm does not
-serve yet, so there is nothing to install. The record names it in `checkout`
-beside `latest`, exits 0, and its `message` starts `CLI stays at`. Outside a
-canon checkout it never reads `pending`.

package/docs/agents/docs.md

@@ -1,27 +0,0 @@
----
-title: Docs
-description: How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
----
-
-# Docs
-
-`canon docs` emits the toolkit's own reference docs so an agent in a target project can orient without the toolkit source checked out. The CLI resolves `docs/` and `canon/context/` from its install root, and which of the two it finds depends on how the CLI was installed. A registry install carries `docs/` alone, since `.claude/` is not published. A clone or a linked worktree carries both.
-
-- `canon docs list [--json]` lists the downstream catalog: the consumer-facing `docs/` surface plus per-domain narrative from `canon/context/` when that root is present. Toolkit-internal context entries (`ci`, `development`, `sandbox`) are dropped. From a registry install the context section is absent rather than empty.
-- `canon docs <topic>` prints one doc to stdout, resolved by exact name from `docs/` first, then `canon/context/`. Any doc the install carries is reachable by name, including the toolkit-internal topics the list omits.
-
-## How a name resolves
-
-A domain too large for one file splits into `<domain>/` with a generated `index.md`, and both verbs name it by the folder. `canon docs <domain>` prints that index, which is the catalog routing to the sub-area files, and the listing describes it from the index's `subtitle` where a sibling file supplies `description`. A folder carrying no `index.md` is absent from both, since a catalog is what makes the sub-areas reachable, and so are the files inside it.
-
-A sub-area file resolves by its bare name too, so `canon docs operating-model` reaches `docs/workflow/operating-model.md`. Three spellings are tried in order, being a sibling file, a folder of that name, then a sub-area file one level down, and each spelling is tried across both roots before the next one runs. A sibling file therefore wins over a folder of the same name, and both win over a sub-area file. Reading the folder last is what keeps the sub-area spelling from changing any name that resolved before it existed.
-
-The sub-area spelling keeps the root order too. The first root whose folders carry the name answers, so `canon docs indexes` reaches `docs/agents/indexes.md` even though a context folder holds an entry of the same name. A bare name carried by two folders of that one root resolves to neither, which names the available topics and exits 1 rather than answering with whichever folder sorts first.
-
-`canon docs list` stops at the folder where `canon docs <topic>` goes on to name each file inside it. The listing is the downstream catalog rather than the index of what a name reaches, so a sub-area file appears there only where it declares a target-facing `category` of its own, and no sub-area file of the context root appears at all. A name that resolves and does not list is the divergence the toolkit-internal topics already carry.
-
-## Output
-
-Data prints to stdout and the frame to stderr, so `canon docs <topic> > out.md` captures clean markdown. With no topic and no verb, `canon docs` runs `list`. An unknown topic names the available topics on stderr and exits 1.
-
-Only a `---` block opening on the first line counts as frontmatter, so a document body carrying horizontal rules emits whole.

package/docs/agents/drift-surfaces.md

@@ -1,201 +0,0 @@
----
-title: Drift surfaces
-description: The seven sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, surfaces at the old root, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
----
-
-# Drift surfaces
-
-`canon sync --check` reports seven sections outside the per-domain scan that
-`install-and-sync.md` describes, because each names something
-that walk cannot see: `seeds`, `superseded`, `unmigrated`, `unmovedSurfaces`,
-`newSkills`, `newRules`, and `reverse`. None of them produces a change, and no
-sync command applies any of them. The headings below group the first four
-together and give `newSkills` its description under `newRules`, which answers the
-same question about a different corpus.
-
-All seven report only against a toolkit-managed target, which is one carrying a
-`.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
-report says so through `managed` in the JSON and routes an unmanaged directory to
-`canon init`. Seeds are why the gate exists, since they enumerate from the toolkit
-source rather than from what a target installed, so an unmanaged directory would
-otherwise report every seed as `missing`.
-
-A root-layout domain counts as a marker on its own, because the detection fires
-only on root files the toolkit ships and a project in the old layout is one the
-toolkit installed. When `managed` is false every section comes back empty rather
-than the render alone going quiet, so a consumer reading `--json` never acts on a
-finding the rendered half withheld.
-
-## Seeds, superseded artifacts, unmigrated domains, and old-root surfaces
-
-`seeds` classifies every seed the toolkit ships against the target's copy, as
-`matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
-equivalent, since the domain walk lists what a target installed and cannot see a
-file that never arrived. There is no `customized` verdict here, because that one
-needs a stamp and seeds carry none, so a file history cannot attribute stays
-`drifted`. Merge the section by hand against the toolkit copy rather than
-replacing a file the project edits.
-
-A markdown seed installs rewritten rather than copied, since the `stub: true`
-marker the toolkit's own seed gate reads is stripped on the way in. The
-comparison above runs against what the install would write, so a marked seed a
-target never touched still reports `matching`. Every other seed copies byte for
-byte.
-
-`superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
-against the `.canon/tasks/` that now ships. The entry carries `replacedBy` and
-nothing else, and the file is never deleted, since the content belongs to the
-project and only its author can decide where it moves. The list derives from the
-seed tree rather than from a fixed set of filenames, so a folder added later is
-covered without a code change. Only an exact stem matches, which leaves a
-suffixed variant such as `TASKS-ARCHIVE.md` unreported.
-
-No skill splits the file. The destination's shape lives in the skill that owns
-it, so the split is the project's own to make.
-
-`unmigrated` names a domain sitting at the root layout an older toolkit installed
-to, with nothing at the path the current one reads. It carries `rootPath`,
-`installPath`, and a file count. Without it a project holding an older layout at its
-root reports zero entries for that domain and reads as clean, which is the most
-misleading state the report can produce.
-
-The field currently names no domain. Snippets was the one the toolkit ever
-installed at a project root, and it retired outright. A leftover `snippets/`
-folder reports under the reverse walk instead, where `docs/target/sync.md` says
-what to do with it.
-
-`unmovedSurfaces` names a tracked surface the target still holds at its `.claude/`
-spelling with nothing at the `canon/` one, such as `.claude/REQUIREMENTS.md` or
-`.claude/context/`. Each entry carries `rel` and `movesTo`, and the render names
-`canon migrate surface-roots`, the verb that moves them. Rules glob the `canon/`
-spelling alone, so a target on the old root stops loading the rules scoped to
-those files until it moves. <!-- canon-keep-surface-root -->
-
-## Rules the target never received
-
-`newRules` names a rule the target could receive and its tree does not hold. A
-sync refreshes the files a target already holds and adds none, so without this
-section a project's rule set freezes at its install date while every file it
-does hold reports as current. That is the report's most confident wrong
-answer, since a clean result reads as a target holding everything the toolkit
-publishes.
-
-The list rides beside `newSkills`, which asks the same question about the plugin
-catalog. Both are names rather than paths, and neither queues a change, because
-the two remedies differ: a skill loads live from the plugin directory and needs
-nothing run, while a rule reaches a target only when someone runs
-`canon gov install`.
-
-Read a clean section as reporting rather than as delivering. Nothing here
-installs, nothing counts toward `--exit-code`, and a target can read the list and
-act on none of it. The value stops at an operator reading it, which is the same
-contract the skills list already sets.
-
-Since `canon gov install` records the stack it resolved, a target carrying that
-record answers this by comparing its current entitlement against its current
-tree, with no anchor and no git diff involved. That is what lets the section
-name a rule that shipped before the target's last sync: the anchor a sync
-advances plays no part in the read, where an anchor-bound diff can never see a
-rule on the far side of a window a later sync moved past it. The per-file
-`missing` state `canon gov sync` reports comes from the same comparison, so a
-rule the chain lists reaches both surfaces the same way.
-
-A target stamped before governance recorded a chain falls back to the older
-rule-folder-inference read below. The measurement there anchors on governance's own
-stamp rather than on the oldest anchor across domains, since rules are
-domain-scoped and a shared anchor would let another domain's sync move the
-revision rules are measured from. A target carrying no chain and no governance anchor
-reports nothing at all: it has no date to measure against, and diffing from the
-start of history would read the whole catalog as new.
-
-An anchor this toolkit cannot resolve reports nothing by the same route, and that
-one is not visible. A stamp naming a revision the running clone has never seen,
-which is what a registry install without history or a shallow clone produces,
-fails the read and yields an empty list rather than a stated absence. It looks
-identical to a target holding every rule the toolkit publishes. `newSkills`
-behaves the same way, and neither carries the `historyUnavailable` flag the
-per-domain scan uses to separate the two. Treat an empty section on a toolkit
-that is not a full clone as unmeasured rather than clean. This gap does not
-reach the chain-based read above, since it consults no anchor at all.
-
-In the fallback, entitlement is filtered, because a stack does not receive
-every rule. The base stack names ten rules, the language stacks add `code` and
-their own language and testing rules, and every other rule is opt-in, so an
-unfiltered list would tell a base consumer about rules it can never receive and
-train the reader to skip the section.
-
-The filter accepts a rule folder on either of two grounds. A folder holding a rule the
-base stack resolves to is entitled to every target, read through the stack file so
-a rule added to base later needs no code change. Every other rule folder is read off the folders the
-target already carries, which is the fallback's only evidence of what a target
-was entitled to before it recorded a chain. One rule folder can be reached by more than
-one stack, so the test over-reports inside a folder the target holds, which
-costs a line where under-reporting would cost the section its point.
-
-A rule the target already holds is dropped by name. That is what keeps a rule the
-toolkit moved between rule folders out of the list, since a rename reaches this
-read as an addition and only the name tells the two apart.
-
-This closes the dangling-citation case as a side effect rather than checking for
-one. The live instance is a rule citing a sibling authored after the target's
-install, and the section names the sibling as new rather than naming the citation
-as broken. That is enough for an operator to act on, and it is not a citation
-check.
-
-## The reverse walk
-
-`reverse` is the one section built by walking the target rather than the
-catalog. Every other surface enumerates toolkit-owned keys and asks whether the
-target matches, so a folder the toolkit deleted appears in none of them. It
-carries `unclaimed` and `historyUnavailable`.
-
-`unclaimed` names a folder the target holds at a top-level path the toolkit once
-shipped and has since deleted. The candidate roots come from the toolkit's own
-history rather than from a list, so a root dropped later is covered without a
-code change. Scoping to those roots is what keeps the walk useful: walking the
-whole tree reports every project folder as unclaimed, which is true and says
-nothing.
-
-The managed gate above applies here too, and it is the one place it surprises.
-A directory holding a dropped folder and nothing else reports an empty `reverse`
-rather than the folder, because it carries none of the three markers. Read an
-empty section on an unmanaged target as a walk that never ran rather than as a
-clean result.
-
-Each entry carries `rel`, a file count, and an `attribution` of `dropped`,
-`project`, or `unattributed`. A dropped folder and one the project wrote are the
-same bytes at the same path, so the verdict is traced from history rather than
-guessed from the filesystem.
-
-Content matching a version the toolkit published reads as `dropped` and carries
-the `since` commit that published it. Names the toolkit shipped holding content
-it never published read as `unattributed`, which is a state in its own right
-rather than a soft yes. No overlap at all reads as `project`, and the render
-drops those while the JSON keeps them.
-
-Only files whose path the toolkit once held are hashed, so a project folder
-colliding on a retired name costs the walk no reads. The cost is that a file the
-toolkit shipped and the target renamed goes unmatched, the same limit the
-`unmigrated` count carries.
-
-## What counts toward the gate
-
-`unmigrated` counts toward `--exit-code`, since running the relocation closes it.
-`superseded` and every seed state are excluded, for the reason `orphaned` already
-is: only the user can move content they wrote, so failing a job on it leaves the
-job red with no mechanical remedy.
-
-`unmovedSurfaces` is excluded although `canon migrate surface-roots` closes it.
-The move rewrites citations across the project, so it is a change the project
-schedules, and a job counting it would go red the day a target updated the CLI.
-
-`newRules` is excluded on a different ground, since a command does close it. What
-excludes it is that installing a rule changes what a project is governed by, so
-gating on the count would pressure a target into adopting rules nobody chose.
-`newSkills` is excluded because it needs no command at all.
-
-The whole `reverse` section is excluded on the same grounds, and more strongly.
-Every entry in it is a judgment about a file the project may own, and one of its
-three verdicts is a labelled unknown by design. The unmigrated detection shipped
-that exact false positive once, failing a push with no action that cleared it,
-so this section reports and gates nothing.

package/docs/agents/gov-detect.md

@@ -1,47 +0,0 @@
----
-title: Rule detection
-description: Proposing opt-in governance rules from a target's dependencies and paths, the evidence file the verb reads, the record it emits, and its exit codes
----
-
-# Rule detection
-
-`canon gov detect` proposes the opt-in governance rules a target's evidence points at, and writes nothing. A rule no stack names reaches a project only through this verb, which `canon:target-setup` calls before it previews an install.
-
-```bash
-canon gov detect
-canon gov detect ../my-app --stack node --json
-```
-
-| Option            | Behavior                                         |
-| ----------------- | ------------------------------------------------ |
-| `--stack <stack>` | Leave out every rule this stack already resolves |
-| `--json`          | Emit the record on stdout instead of the frame   |
-
-## Evidence
-
-Each opt-in rule keeps a table in the toolkit's `governance/detect.toml`, keyed by rule basename. Its `deps` are package names, read from `package.json` (`dependencies` and `devDependencies`), `pyproject.toml`, `go.mod`, and `composer.json`. Its `files` are globs matched against the target's git-listed paths and against each folder on those paths, so `.github/workflows` matches a folder holding a workflow. A glob with no wildcard is also tested on disk, which is how `.canon/canvas` matches in a target that gitignores `.canon/`.
-
-Both reads stop at depth two, which reaches a service folder and a workspace package under `packages/<name>/`. Outside git the verb walks the directory to the same depth and skips `.git`, `node_modules`, `vendor`, and `.venv`. A manifest that does not parse contributes nothing.
-
-## Record
-
-```json
-{
-  "target": "/abs/path/my-app",
-  "stack": "node",
-  "proposals": [
-    {
-      "rule": "react",
-      "evidence": [{ "kind": "dep", "match": "react", "path": "package.json" }]
-    }
-  ]
-}
-```
-
-`kind` is `dep` for a dependency, with `path` naming the manifest that declares it, or `file` for a glob, with `path` naming what it matched. `stack` is null when no `--stack` was passed.
-
-## Exit codes
-
-The verb exits 0 on every readable target, including one with no evidence, which returns an empty `proposals` array. A target that does not exist and a `--stack` that does not resolve each exit 1 with the reason on stderr.
-
-Install what the operator kept with `canon gov install --add <rules> <target>`, which needs no stack.

package/docs/agents/scripting.md

@@ -1,142 +0,0 @@
----
-title: Scripting
-description: The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
----
-
-# Scripting
-
-What a skill or script reads to discover names at runtime, and how each domain is invoked with no TTY.
-
-## Runtime catalogs
-
-Use these to discover what's available instead of hardcoding names.
-
-| Command                           | Returns                                                          |
-| --------------------------------- | ---------------------------------------------------------------- |
-| `canon tooling list --json`       | Stacks, extends chain, dep and script counts                     |
-| `canon gov list --json`           | Governance stacks, rule sets, evidence, and unreferenced rules   |
-| `canon gov detect --json`         | Opt-in rules a target's dependencies and paths propose           |
-| `canon claude seeds list --json`  | Seed doc sources with content                                    |
-| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag, family vocabulary |
-| `canon docs list --json`          | Consumer docs plus per-domain context                            |
-| `canon audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
-
-### Catalog fields
-
-Every catalog serializes through `JSON.stringify`, so a name carrying a quote
-emits valid JSON. `canon tooling list` previously built
-its output with `printf` and no escaping.
-
-`canon claude seeds list` reads the same plan `canon claude init` applies, so the
-listing and the install cannot disagree. It now reports
-`canon/context/index.md`, which `init` has always installed and the listing
-never named, and it emits the project-level `CLAUDE.md` last rather than first.
-
-`canon gov list` reports each stack's rules already expanded. A stack entry names
-either a rule or a whole rule folder under `governance/rules/`, and the folder
-form reaches this listing as the rules it stands for rather than as the folder
-name. A consumer deduping `--add` extras against a stack therefore reads the same
-set the install writes, whichever form the stack file uses.
-
-It also carries `unreferenced`, the rules no stack reaches, on every invocation
-rather than behind a flag. These install only through `--add`, so the key answers
-what a stack leaves out without a caller resolving every stack itself. The key is
-present alongside `stacks` and `rules` and survives `--stacks` or `--rules`
-narrowing the other two.
-
-### The skills catalog
-
-`canon claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder
-name with the frontmatter description, sorted by name. Internal skills under
-`.claude/skills/` are excluded, since they never install into a target and a
-count spanning both overstates what ships. A skill whose frontmatter is missing
-or unparseable returns an empty description rather than failing the listing, so
-one malformed file cannot hide the rest of the catalog. `--names` emits skill
-names one per line.
-
-Each skill in `--json` carries `family`, the `metadata.family` its frontmatter
-declares, or `null` where it declares none. A top-level `families` array holds
-the vocabulary as `{ key, group }` entries in skill map order, where `group` is
-the map heading the family's rows sit under. Read a new skill's family from it
-rather than from the map. `--by-family` prints the human listing as one step per
-family, with a trailing step for any skill whose family is missing or unknown.
-
-Each entry also carries `requirement`, whether the folder holds a sibling
-`REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
-close rather than a recorded exemption, and the flag answers which skills are
-missing theirs without a caller listing the directory itself. `canon claude skills
-audit` gates that rule across both corpora, so read this flag for the state of
-the shipped catalog and the audit for whether a working tree conforms. Its
-surface is in `skills-audit.md`.
-
-## Non-interactive examples
-
-```bash
-# Report what a stack would change, writing nothing
-CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
-
-# Sync a stack into a target project, overwriting its golden configs
-CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
-
-# Install a governance stack (the stack argument is required headlessly)
-CANON_NON_INTERACTIVE=1 canon gov install node --add astro,shadcn /path/to/project
-
-# Update installed governance rules, dropping a retired .claude/GOV.md
-CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project
-
-# Concatenate installed rules into a paste payload
-CANON_NON_INTERACTIVE=1 canon gov build /path/to/project
-
-# Sync a monorepo subtree, skipping the base layer the repo root already owns
-CANON_NON_INTERACTIVE=1 canon tooling sync vite-react /path/to/repo/frontend --skip base --write
-
-# Verify a stack end-to-end in a throwaway scaffold
-canon tooling verify vite-react
-
-# Apply one stack without scanning or prompting, for scripted provisioning
-canon tooling inject base /path/to/project
-canon tooling inject base /path/to/project --configs --seeds
-
-# Drop managed gitignore entries a manifest no longer declares
-# Prints the number removed on stdout, diagnostics on stderr
-canon tooling prune-gitignore base /path/to/project
-
-# Bootstrap a project. Any flag suppresses the confirmation prompt
-CANON_NON_INTERACTIVE=1 canon init --stack node --skip wiki /path/to/project
-
-# Run every domain sync. The git workflow is refused headlessly, so nothing is pushed
-CANON_NON_INTERACTIVE=1 canon sync /path/to/project
-
-# Scaffold .claude/wiki/ with a stub index. The target must already exist
-CANON_NON_INTERACTIVE=1 canon wiki init /path/to/project
-
-# Run a sandbox scenario non-interactively
-SANDBOX_SCENARIO=sync canon sandbox infra:tooling
-
-# Read every audit as one record. Exit 2 is a fact, 3 an audit that did not report
-canon audits run --json
-
-# Read committed state rather than an arriving change. Exit 2 carries findings
-canon secrets scan --json
-canon deps audit --json
-```
-
-The two state-scoped verbs both exit 2 on findings and mean different things by
-it. A credential in the shipped tree is a fact and fails `canon audits run`, while
-a published advisory is a judgment that reports and moves no verdict. Neither
-reads a diff, so a consumer already running a review surface gets no overlap.
-
-Both refuse rather than report clean when they have no corpus, and the refusal
-reason is the field to branch on. A project publishing nothing refuses the secret
-scan with `no-manifest`, and one whose dependencies are not installed refuses the
-advisory check with `no-lockfile`. The aggregate reads those as an absent corpus
-rather than a broken run, so neither pins its verdict at `incomplete`.
-
-`canon tooling sync` is the one verb above whose flag is mandatory headlessly. It
-overwrites every golden config a stack ships, which reaches the CI workflow, the
-git hooks, the end-to-end harness, and the shell scripts under `scripts/`, so a
-headless run carrying neither `--check` nor `--write` reports what it would
-replace and exits 1 rather than applying it. Run `--check` first to read the
-list, then `--write` to apply it. `canon tooling sync --help` names both, and
-`canon tooling diff <stack> <target>` reports the per-stack path list resolved
-against a real target.

package/src/markdown/growth.ts

@@ -1,43 +0,0 @@
-import { bodyLines } from '@/markdown/scan'
-import {
-  CHECKPOINTS,
-  type Checkpoints,
-  type LongBlock,
-  longBlocks,
-} from '@/markdown/structure'
-
-/**
- * Reduces text to the words a reader meets, so a block reflowed, re-marked, or
- * moved under another heading still matches the copy it came from.
- *
- * List markers and emphasis marks are dropped because turning a bullet into a
- * labelled bullet or a paragraph changes the shape of a statement and none of
- * its words, which is the edit the sweep makes. A word changed is a text
- * changed, and that is what the growth stage exists to see.
- */
-export function normalizeProse(text: string): string {
-  return text
-    .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, '')
-    .replace(/[*_]/g, '')
-    .replace(/\s+/g, ' ')
-    .trim()
-}
-
-/**
- * The paragraphs and top-level bullets of `source` past their checkpoints whose
- * text appears nowhere in `base`.
- *
- * Containment rather than line matching, so an unchanged long block passes
- * wherever it sits and an edited or new one fails. `base` is every document the
- * caller counts as the copy it may have come from, already normalized, since a
- * block moved into a sibling entry is as unchanged as one left in place.
- */
-export function grownBlocks(
-  source: string,
-  base: string,
-  checkpoints: Checkpoints = CHECKPOINTS,
-): LongBlock[] {
-  return longBlocks(bodyLines(source), checkpoints).filter(
-    (block) => !base.includes(normalizeProse(block.text)),
-  )
-}