@erclx/canon 5.39.0 → 5.40.0

package/docs/agents/counts.md

@@ -1,74 +0,0 @@
----
-title: Self-stated counts
-description: Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
----
-
-# Self-stated counts
-
-`canon gov counts` reports a sentence stating how many members a closed catalog holds where the stated figure disagrees with what the tree actually counts. A document that reports its own catalog size carries a number nothing else compares against the tree, so it goes stale on the edit that moves the catalog and reads as current until a reviewer happens to recompute it.
-
-```bash
-canon gov counts
-canon gov counts --json
-canon gov counts --root ../my-app
-```
-
-| Option          | Behavior                                                   |
-| --------------- | ---------------------------------------------------------- |
-| `--root <path>` | Tree to read, defaulting to the current directory          |
-| `--json`        | Add a machine-readable record on stdout, keeping the frame |
-
-Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
-
-## The catalogs it reads
-
-A closed set of four, each with a filesystem reader behind it rather than every list command this CLI ships:
-
-- `skills`: shipped plugin skills, a folder per `claude/skills/*/SKILL.md`
-- `rules`: authored governance rules, a file per `governance/rules/**/*.md`
-- `commands`: top-level `canon` commands, read off `src/cli.ts`'s registration imports
-- `audits`: the registered set in `src/audits/catalog.ts`, this entry included
-
-The set is closed rather than derived, so widening it is a deliberate change to this file rather than a side effect of a new list command shipping elsewhere. `commands` is the one catalog with no meaning outside this repository: a project installing this CLI carries no `src/cli.ts` of its own, and that catalog reads as not applicable there rather than as zero, since zero would report a finding against any such project stating its command count as anything but zero, forever.
-
-## How a match is decided
-
-A sentence has to carry an assertion verb (`loads`, `ships`, `carries`, `holds`, `counts`, `totals`, `documents`, `declares`, `installs`, `lists`, `contains`, `comprises`, `authors`), the quantifier `all`, or an article (`the`, `a`, `an`) immediately ahead of the number, which is immediately ahead of the catalog noun, with one optional qualifying word between the number and the noun (`sixty-one shipped skills`). The number reads either as digits or as a spelled-out cardinal through ninety-nine, since this corpus states a catalog size in words as often as in digits.
-
-Nothing stands between the trigger and the number, which is the rule an author writing a new count has to know. It separates `the toolkit authors 49 rules` and `took all 49 rules`, both read, from `a domain of 55 skills` and `denominator of sixty-one shipped skills`, neither of them read. A figure meant as a past state takes a date in the same sentence instead, which reads the sentence past whatever its shape.
-
-## How the trigger set grew
-
-The verb gate is not the first design tried. A bare number next to a catalog noun anywhere in the tracked corpus returned 290 findings against a repository whose actionable instance count was one. Reading that run showed why: `18 rules citing a standard`, `21 skill bodies`, and `eight internal skills` all pair a number with a catalog noun while naming a subset, an example, or a different catalog than the one matched, and that shape dominates ordinary prose. Every instance this sweep was written against reads the number as the direct object of a verb asserting the catalog's own total, and gating on that verb is what took the false-positive count from 290 to five on the same tree.
-
-The article half was added after a first review of the shipped design found a live miss: the development domain's gating-stages entry stated a stale audit total while the tree held 20, and the verb gate never reached it, since that sentence puts its verb after the noun rather than ahead of the number. Widening the trigger set to admit an article ahead of the number closed that gap.
-
-The quantifier `all` and the verb `authors` joined on the same evidence, two more live misses failing only the trigger test. Allowing words to stand between the trigger and the number was the other candidate, measured and declined: at widths of one, two, and three it reached 77, 104, and 132 sentences against a baseline of 65, missed `took all 49 rules` at every width, and reached `the toolkit authors 49 rules` only at a width admitting the indirect-noun shape below. The two words reach both at 75 sentences and no false positive.
-
-## The plausibility filter
-
-The verb gate alone still left four false positives standing: `carries two rules about a standard's own lifecycle`, `holds one rule or one fact` (twice, once per mirrored copy), and `documents two similar commands`. Each pairs an assertion verb with a catalog noun used for something the `rules` or `commands` catalog does not mean, and what tells those apart from the one live finding is magnitude: a catalog this sweep tracks drifts by a few members between the day a sentence was written and the day it is read, so a genuine staleness claim sits near the true count. `2` beside a true count of `59` is not a catalog that shrank, it is a different `rules` entirely.
-
-A stated figure is read only when it sits within a factor of two of the true count, in either direction. That bound is tuned against the run this sweep was written against rather than reasoned to from first principles, the way `restated.ts` tunes its own document-frequency ceiling, and it is a property of the scale every catalog here sits at (the tens) rather than a universal rule.
-
-The article gate is looser than the verb list and carries a real cost. Re-running against the tree once it widened caught the live miss above and also misread a passage in the standards destinations entry, since retired, naming a real subset, a standard outside the retired bundled fan-out, as a claim about the whole standards catalog. The qualifying adjective there fills the same optional-word slot `sixty-one shipped skills` needs to match at all, and no syntactic rule tells a qualifier that narrows a catalog from one that only restates it. The finding could not be closed by correcting a figure, since the sentence was true when the corpus held it, only unmarked as a past state, which is the class the date exclusion already reads past. Naming the moment, the same way a context entry dates its own figures, closed it with no change to the matcher.
-
-## What it does not measure
-
-A delta phrased as a transition (`from fourteen to fifteen`), a fraction (`thirteen of sixteen`), and a total reached through an indirect noun (`denominator of sixty-one shipped skills`) are all catalog-size claims this corpus carries, and none matches the trigger shape this reads. Each stays a known gap. The false-positive rate that gated closing them has a measurement behind it now, and what it showed is that the widening these three need is the one that costs a false positive rather than the one that does not.
-
-A second figure in a sentence whose first figure already matched is a fourth gap and a structural one, since one match is taken per catalog per sentence. `authors 49 rules under governance/rules/ and consumes 31 into .claude/rules/` is read for its 49 alone, which is correct here because the two figures name different populations, and a sentence stating one catalog twice would go unread the same way.
-
-A calendar date (`2026-08-21`) or a backticked commit reference in the same sentence reads the whole sentence past, since that is how this corpus already marks a figure as a historical record rather than a live claim. The context entries carry a figure this way deliberately, and every one of them stays correct forever.
-
-The wider check over prose restatements is deliberately out of reach here. `canon gov restated` already records a parser over prose as rejected, and this sweep reaches a number with a command behind it rather than two sentences a reader has to judge as agreeing.
-
-## Exit codes
-
-Exit codes are `0` when no stated figure disagrees with the tree, `1` for a refusal, and `2` for at least one disagreement.
-
-Nothing wires this into `bun run check` or into a hook. The false-positive rate is read off the first real run rather than assumed ahead of it, and gating a measure with an unmeasured rate is what teaches a contributor to route around the stage. `canon gov restated` and `canon gov test-order` are the siblings this reasoning already governs.
-
-Both refusals are breaks rather than absences. A tree with no git history or no markdown file at all is a broken checkout, matching what `canon markdown audit` already reads `no-git` and `no-markdown` as, since this sweep shares that corpus.
-
-An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `findings` rather than the exit when a skill consumes this.

package/docs/agents/demo.md

@@ -1,140 +0,0 @@
----
-title: Demo
-description: Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
----
-
-# Demo
-
-`canon demo` drives a project's running application and writes a recording of what it did, plus a still frame of the same run. It exists so a project card and a short demo stop depending on someone sitting down to record one by hand.
-
-Two verbs, and they are separate because the artifact between them is edited.
-
-```bash
-canon demo compile demos/inline-edit/beats.md --slug inline-edit
-canon demo run demos/inline-edit/plan.json
-canon demo run demos/inline-edit/plan.json --cursor ~/cursors/theme --out assets
-canon demo frames demos/inline-edit/take/inline-edit.webm --fps 2
-```
-
-## One folder per demo
-
-Each demo owns a folder, `demos/<slug>/`, and `compile` writes the plan into it.
-
-| Path         | Committed | Holds                                                 |
-| ------------ | --------- | ----------------------------------------------------- |
-| `beats.md`   | yes       | The draft `draft-screencast` wrote                    |
-| `plan.json`  | yes       | The compiled plan, with its hand-tuned timing         |
-| `index.html` | yes       | The HyperFrames composition, when the demo is wrapped |
-| `demo.gif`   | yes       | The one deliverable a README embeds                   |
-| `take/`      | no        | The raw recording, its still, and its timeline        |
-| `renders/`   | no        | The composed mp4, written by the render               |
-
-A project carries `demos/*/take/` and `demos/*/renders/` in its `.gitignore`, since both are one command away and a webm is large. A plan compiled before this layout, at `demos/<slug>.json`, still runs by path, because only the default moved.
-
-## The draft and the plan are different files
-
-`draft-screencast` drafts beats for a person. A beat carries what is on screen, one verb, what to watch for, an emphasis, and a caption, and none of that names a selector, a URL, a wait condition, or a timing. Those four are what an executor needs and what would ruin the draft, since the format is pre-seeded so the operator edits down rather than fills blanks.
-
-So `canon demo compile` writes a second artifact rather than adding fields to a beat. It maps each beat's verb to a step, seeds the timing, marks which beat the still comes from, and leaves the target and the URL empty for a person to fill. The report names every field it could not supply.
-
-The plan is committed, not scratch. Its timing is a starting point tuned by watching a recording, and the draft cannot reproduce a tuned value, so a recompile over an existing plan refuses and names `--force`.
-
-A plan can carry an optional `colorScheme` of `light` or `dark`, which the recording context starts in so a page following the system preference paints that scheme with no click beat of its own. An absent field keeps the engine's default, which is light, and `compile` never seeds it. Any other value makes the plan unreadable. A page keyed on a stored theme rather than the preference ignores the field.
-
-A recording that has to match both themes takes one plan per scheme, committed side by side, rather than one plan run twice. The pair shares its beats and differs in `colorScheme`, `slug`, and the `output` paths. Neither plan clicks a theme toggle, since a stored theme overrides the preference. Nothing checks that the two plans keep the same beats, so an edit to one is made to both.
-
-`record-screencast` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
-
-| Option          | Behavior                                                          |
-| --------------- | ----------------------------------------------------------------- |
-| `--out <dir>`   | Directory the plan and its output paths point at, default `demos` |
-| `--slug <slug>` | Demo folder name, defaulting to the draft filename                |
-| `--force`       | Overwrite an existing plan, losing any field set by hand          |
-| `--json`        | Add a record on stdout carrying the beats and what is unfilled    |
-
-## What a run does
-
-`canon demo run` reads the plan, refuses if a field is still empty, and drives the application the plan's URL names. It records the whole run to `webm` and writes the still from the beat the draft calls the hero, falling back to the last beat, since a demo's final state is the payoff and a cold open is usually an empty screen.
-
-A step's caption from the draft renders as an overlay while its hold plays, so the narration a person wrote is what shows on screen rather than the name of the action the engine performed.
-
-Beside the webm, the run writes `<video-basename>.timeline.json`, so a composition can aim a zoom at the moment and the place of an action rather than adding up holds by hand. It holds an `entries` array with one entry per step, each carrying the step's `index`, its `kind`, and `startMs` and `endMs` counted from the recording's first frame. A step ends once its hold has played. A click, fill, or hover entry also carries `box`, the target's `x`, `y`, `width`, and `height` in viewport pixels, which are the video frame's own coordinates. A navigate, scroll, wait, or hold entry carries no `box`, and the file is still written. A run under `--no-video` writes no timeline, since there is no video for it to sit beside. The `--json` record names the file under `timeline`, and `null` when none was written.
-
-When `ffmpeg` is on PATH, the run also writes an mp4 beside the webm, since webm plays in a `<video>` tag but nothing else accepts it. A target without `ffmpeg` still gets the webm and a line naming what to install, and the run does not fail over the missing converter.
-
-`--gif` adds a third file from the same converter, and it is opt-in where the mp4 is not. A gif runs several times the size of the webm it derives from, and the destination that needs one is a README on a host that strips `<video>`, which GitHub does. The filter generates a palette from the source and then applies it, rather than quantizing per frame, since a per-frame palette is what makes a recording of flat interface colors band and shimmer. It applies that palette without dithering, because the command records applications rather than photographs and the dither writes noise the encoder then stores. One recording measured 3,193,715 bytes dithered against 2,701,941 without, with the same text region cropped from both and read as identical. A missing converter is reported the same way it is for the mp4, so an absent `ffmpeg` costs the gif and not the run.
-
-| Option           | Behavior                                                            |
-| ---------------- | ------------------------------------------------------------------- |
-| `--out <dir>`    | Directory to write into, overriding what the plan names             |
-| `--cursor <dir>` | Cursor theme folder to draw the pointer from                        |
-| `--no-video`     | Write only the still                                                |
-| `--no-still`     | Write only the recording                                            |
-| `--gif`          | Also write a gif, for a host that strips video                      |
-| `--json`         | Add a record on stdout carrying every path written and the duration |
-
-A step waits on its `waitFor` selector becoming visible and then holds for its own `holdMs`, which is what puts a finished state on screen long enough to read. `navigate` uses the plan's URL unless the step names its own.
-
-## What frames does
-
-`canon demo frames` pulls numbered PNG stills back out of a recorded video through the same `ffmpeg` binary the mp4 and gif conversion already shells to. Nothing reads a recording back today, so a broken one ships until a person opens it, and this verb is what a skill calls to read one instead. It writes one frame a second by default, sampling at a rate matched to how long a tuned recording runs rather than at a rate tuned for any one clip. Frames land beside the video by default, named `<video-basename>-frame-<NNN>.png`, so they fall under the same `take/` ignore entry the still already uses.
-
-| Option            | Behavior                                                 |
-| ----------------- | -------------------------------------------------------- |
-| `-o, --out <dir>` | Directory to write frames into, default beside the video |
-| `--fps <n>`       | Frames extracted per second of video, default `1`        |
-| `--json`          | Add a record on stdout carrying every frame path written |
-
-`read-frames` is the routed way to call this verb and read the frames back: it runs the verb, reads each returned frame with the Read tool, and reports one plain description per frame. It never renders a verdict, since a frame read is evidence a person weighs rather than a pass or fail this toolkit states on their behalf.
-
-## The pointer is painted inside the page
-
-The browser engine offers an annotation of its own that draws a dot on the interacted element and a title naming the API call it made, and this recorder does not turn it on. It paints no cursor, so a run relying on it looks like the pointer teleports between targets, and the two overlays below supersede it: a real cursor where the dot is a marker, and the beat's narration where the title reads `Mouse move`. Running both put four overlays on the frame, and the two the engine drew were the two a viewer reads as noise.
-
-The recorder injects a pointer element before navigation and moves it through the engine's pointer with interpolated steps rather than through the element-clicking helper, which resolves a target and jumps to it. The step count is the whole difference between a cursor that travels and one that appears, and how many steps a move takes is derived from the machine's own round-trip cost rather than fixed, so the same plan glides at roughly the same pace on a loaded machine as an idle one. It also reads the element under it on every move and switches between an arrow, a hand, and a text beam, so it reflects the page the way a real cursor does.
-
-`--cursor` points at a folder of Windows cursor resources and the browser decodes them directly, with no conversion step and no image tooling. Each resource carries a hotspot per size, and the largest entry's hotspot scaled to the drawn size is what puts the artwork's tip where the click lands. A theme contributes per state, so a folder holding an arrow and no hand still supplies its arrow and the bundled artwork covers the rest.
-
-Three of the nineteen states a theme carries are read. A drag, a resize, or a wait shows the arrow where a real session would show something else, and the two animated states have no still frame to draw.
-
-## What the refusals report
-
-Every refusal exits 1 and names its reason in the `--json` record, so a skill branches on `reason` rather than on the exit code.
-
-| Reason                | What happened                                                                       |
-| --------------------- | ----------------------------------------------------------------------------------- |
-| `draft-missing`       | No file at the path given to `compile`                                              |
-| `draft-unreadable`    | The draft carries no beat sheet, or a sheet with no beats                           |
-| `plan-exists`         | A plan is already there and `--force` was not passed                                |
-| `plan-unresolved`     | A URL or a target is still empty, named field by field                              |
-| `no-output-requested` | `--no-video` and `--no-still` together, which would drive the app and write nothing |
-| `plan-unreadable`     | The plan is not JSON, or a step names a kind nothing drives                         |
-| `browser-missing`     | The browser binary is not installed, with `install` carrying the command            |
-| `engine-missing`      | The browser package itself did not resolve                                          |
-| `video-missing`       | No file at the path given to `frames`                                               |
-| `converter-missing`   | `ffmpeg` is not on PATH, so `frames` extracted nothing                              |
-| `extraction-failed`   | `ffmpeg` exited non-zero, with `message` carrying its stderr                        |
-
-## The browser reaches every target
-
-This command was the first browser command to ship, and `canon capture` has since joined it. Capture was held back because its only caller was this repository regenerating its own committed images, which was a fact about that caller rather than about the render.
-
-The cost is stated rather than hidden: the browser binary installs separately, so a target runs `bunx playwright install chromium` once before a recording works at all. A run that cannot launch reports that command inside the frame and exits 1.
-
-## Composing the take into a finished video
-
-The take is raw. When the draft's `## Wrap` section asks for an intro, an outro, or music, `record-screencast` composes the take into `demos/<slug>/index.html` through [HyperFrames](https://hyperframes.heygen.com) and renders `renders/<slug>.mp4`, the deliverable. The skill loads HyperFrames' own `hyperframes` skill for the composition rules and `canon:video-craft` for the captions, zoom, pointer, and audio judgment a video of software needs, aims each zoom from the take's timeline, and runs `bunx -y hyperframes check` and `render`, then hands the render to `read-frames`. A wrap section reading `none` throughout stops at the take. The webm is only the raw take, and a gif is for a host that strips video.
-
-Canon neither ships nor installs HyperFrames, and there is no `canon` verb for composing, since the render is one command already. The operator installs it once per machine:
-
-```bash
-bunx -y hyperframes init
-```
-
-`hyperframes init` installs its skills machine-wide without asking, so run it knowing that. A machine without it stops the skill with this command and nothing else.
-
-## What it does not do
-
-Nothing in `canon demo` itself trims a take or scores it beyond the caption each beat already carries. Composing is the skill's step and HyperFrames' work.
-
-It also does not replace a narrated screencast. That has a hero moment, a cut list, and a voice, none of which survives being generated. This answers the case where the alternative is recording nothing.

package/docs/agents/driver.md

@@ -1,103 +0,0 @@
----
-title: Driver
-description: Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
----
-
-# Driver
-
-`canon drive <url> <run>` walks a page through a sequence of interactions and measures every state it reaches. A render answers about a page as it loads, so a defect that exists only after a menu opens, an answer is chosen, or the page scrolls is invisible to one. That second axis is what this adds.
-
-```bash
-canon drive http://localhost:4173 run.json
-canon drive http://localhost:4173 run.json --json
-```
-
-| Option   | Behavior                                |
-| -------- | --------------------------------------- |
-| `--json` | Add a machine-readable record on stdout |
-
-## The run file
-
-The run is a JSON file rather than a key in a project config, because a route catalog is state a project holds and an interaction sequence is a script written for one question. It carries the viewport, the probes to run by default, and the steps.
-
-```json
-{
-  "viewport": { "width": 1440, "heights": [900, 1200, 1500] },
-  "probes": ["focus", "details"],
-  "steps": [
-    { "name": "on load", "kind": "wait", "ms": 0 },
-    { "name": "open the menu", "kind": "click", "target": "#menu summary" },
-    {
-      "name": "reach the diagram",
-      "kind": "scroll",
-      "target": "figure",
-      "probes": ["diagram-geometry", "diagram-strokes"]
-    }
-  ]
-}
-```
-
-Every step names what it did, and that name is carried onto each finding it produced, alongside the viewport. A step naming its own `probes` overrides the run-level list for that step alone. Omitting `probes` at the run level runs all four.
-
-| Step kind | Fields             | What it does                                   |
-| --------- | ------------------ | ---------------------------------------------- |
-| `click`   | `target`           | Presses the first element the selector matches |
-| `scroll`  | `target`           | Brings the first match into view               |
-| `fill`    | `target`, `text`   | Types into the first match                     |
-| `tab`     | `count` (optional) | Advances keyboard focus, once by default       |
-| `wait`    | `ms`               | Holds, for a state the page reaches alone      |
-
-Probes run after a step and never on arrival, so a run reaches the load state by opening with a `wait` step of its own, as the example above does. Nothing probes before the first step runs, which makes that leading step the only way to measure the page as it first painted, and naming it is what puts the load state on its own findings rather than under whatever ran next.
-
-Write one wherever no capture runs against the page. `canon capture` renders a single state from a source on disk or a URL, so where it runs it already answers about arrival and a leading `wait` duplicates it. Where it does not, this command is the only thing measuring the page at all, and a run without that step reports every driven state and nothing about the one a visitor sees first.
-
-Each height is driven in a context of its own from a fresh navigation, rather than by resizing the page the previous height already drove, since a sweep asks the same question of each height rather than a later question of an already-driven page.
-
-## The probes
-
-Four probes, a fixed catalog rather than a subject system a project extends. Each carries a class of false finding that a throwaway version of this command produced before it produced true ones, and a probe a project authored for itself would re-pay those.
-
-| Probe              | What it reports                                                                            |
-| ------------------ | ------------------------------------------------------------------------------------------ |
-| `focus`            | An element that takes keyboard focus and changes nothing visible                           |
-| `details`          | A `details` panel off the viewport, or a row under the tap minimum, both read open         |
-| `diagram-geometry` | An SVG label outside its frame, covered by a filled shape, or colliding with another label |
-| `diagram-strokes`  | An SVG label a stroke crosses, sampled along the stroke's own geometry                     |
-
-`focus` presses Tab before it reads anything. `:focus-visible` does not match a scripted `.focus()` once the page has taken a pointer interaction, and a driver clicks by definition, so a reader without that press reports every correctly styled element as unstyled. It also ignores an outline width, color, or offset moving underneath an outline that resolves to `none`, which paints nothing.
-
-`details` discovers every `details` on the page rather than taking a selector, measures each shut and again open, and judges only the open reading. A shut menu still reports a layout box and the box describes the trigger rather than the panel, so the shut numbers travel in the record as context. Discovery is automatic because the one real menu defect in the originating run was missed by a hand-picked probe: nobody thought to name that menu.
-
-Both diagram probes read after `document.fonts.ready` and never compute from the markup. A generated page is routinely authored against one font and restyled to another, so a label that cleared a line at its authored width can overlap it once rendered. Every rect either probe compares is inset vertically and never horizontally, since a text rect is loose above and below the glyphs and tight to them left and right, and a horizontal inset passes a real overrun.
-
-`diagram-strokes` is separate from `diagram-geometry` because a bounding box cannot answer for a stroke. A probe comparing filled boxes filters out every `line` and every `fill="none"` panel border before it compares, and a diagonal connector's box covers most of a diagram while the stroke itself touches almost none of it. Both paint orders are findings: a stroke drawn after a label crosses the glyphs out, and one drawn before it shows through them, since SVG text carries no plate of its own.
-
-## Viewport heights are never defaulted
-
-A run with no `viewport.heights` refuses. The heights that separate a passing render from a failing one belong to the layout being driven, and the only evidence behind any default this could ship is one fixture's failure range, too narrow a sample to hand every later caller a number they never chose. A scroll rail that skipped its middle sections passed at 900 and failed at 1200 and 1500, so one height reports clean over a live defect.
-
-## What it reports
-
-It reports findings and never gates, and the exit code says only whether the drive completed. Every probe here carries a class of false finding already paid for once, so a command ending a build on its own reading makes a claim this catalog has not earned. A caller that wants a verdict reads `findings` off the `--json` record and decides for itself.
-
-| Reason               | What it means                                          |
-| -------------------- | ------------------------------------------------------ |
-| `no-run-file`        | Nothing readable at the path given                     |
-| `unreadable-plan`    | The run file is not valid JSON                         |
-| `no-steps`           | The run names no step                                  |
-| `no-probes`          | The run names an empty probe list                      |
-| `unknown-probe`      | The run names a probe this build does not ship         |
-| `bad-step`           | A step is missing what the driver needs to perform it  |
-| `no-viewport`        | The run declares no viewport                           |
-| `no-width`           | The viewport has no width to wrap at                   |
-| `no-heights`         | The viewport names no height, which is never defaulted |
-| `engine-missing`     | The browser engine is not installed in this project    |
-| `browser-missing`    | The engine is installed and its browser binary is not  |
-| `server-unreachable` | Nothing answered at the URL, so no state was reached   |
-| `drive-failed`       | The drive failed against a reachable page              |
-
-An unreachable page refuses rather than returning an empty report, since nothing measured and nothing found read the same to anything counting findings.
-
-The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo`, `inventory`, and `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, so the two surfaces move independently.
-
-See `canon --help` for where this sits among the browser commands, and `capture.md` for the single-state render it adds an axis to.

package/docs/agents/gate.md

@@ -1,90 +0,0 @@
----
-title: Merge gate
-description: Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
----
-
-# Merge gate
-
-`canon gate run` runs every stage that guards a branch here, in order, stopping at the first stage that finds a fact. `bun run check` and `bun run check:ci` resolve to it, and the `update` package script runs `bun run check` after a dependency update.
-
-```bash
-canon gate run
-canon gate run --all
-canon gate run --json
-```
-
-| Option     | Behavior                                                                      |
-| ---------- | ----------------------------------------------------------------------------- |
-| `--all`    | Run every stage instead of scoping shell, types, and tests to the changed set |
-| `--nested` | Suppress the outer frame when a calling script has already opened one         |
-| `--json`   | Add a machine-readable record on stdout                                       |
-
-## What the command owns and what it runs
-
-Three things sit in the command: the stage table in `src/gate/stages.ts`, the changed-file scoping and the run loop in `src/gate/sequencer.ts`, and every threshold comparison in `src/gate/measures.ts`. Each individual check is the script or the verb it already was, under `scripts/core/` or behind another `canon` command, and the move changed none of them. Sequencing, scoping, and comparison are where the recurring defects were, and a check whose behavior changed while its sequencing moved would make any regression impossible to attribute.
-
-A stage is a list of checks and a check is one of four kinds:
-
-| Kind      | What it is                                                                      |
-| --------- | ------------------------------------------------------------------------------- |
-| `command` | Any binary, run from the project root                                           |
-| `cli`     | This checkout's own `src/cli.ts`, never a globally installed `canon`            |
-| `drift`   | A regenerated pathspec asserted against the index and against the untracked set |
-| `measure` | A reading whose verdict is a comparison rather than an exit code                |
-
-A `cli` check runs the source rather than the binary because a globally installed `canon` resolves to the main checkout no matter which worktree is running, so a gate reading through it would measure the wrong tree and pass a branch it never opened.
-
-Every check is an argument vector rather than a shell line, so no stage carries a quoting hazard and a `drift` pathspec reaches git exactly as the table spells it.
-
-## Scoping
-
-Shell, types, and tests read the changed set. Everything else always runs, because its input is diffuse enough that no path predicts it.
-
-The changed set unions the branch diff against the merge base with `origin/main`, the working tree, and untracked files, which is what a pull request will contain. The baseline is the remote ref and not local `main`, since on `main` itself the local ref is HEAD and every unpushed commit would drop out. Every fallback widens rather than narrows: no merge base at all runs every stage, and a local baseline equal to HEAD does the same. `--all` turns scoping off outright, which is what `bun run check:ci` passes so CI stays the backstop for a wrong local scoping decision.
-
-## A stage that cannot read its input
-
-A stage reports one of four states. It passed, it was scoped out, it found a fact, or it could not measure its input at all.
-
-The fourth is the one worth naming. An absent tool, a catalog that did not report, a corpus with nothing under it: each used to print a line that read like a pass. Now the run records it as unmeasured, the closing line says how many stages measured nothing, and the reader is not told a verdict nobody took.
-
-What happens next depends on where the run is. On a contributor's machine it warns and the run still exits 0, because an absent tool there is somebody mid-setup. Under CI, read off `CI=true`, it refuses, because the same absence on a runner is a broken workflow step.
-
-## Exit codes
-
-| Code | Meaning                                                       |
-| ---- | ------------------------------------------------------------- |
-| `0`  | every stage that ran reported, and none found a fact          |
-| `1`  | a stage found a fact, or could not measure its input under CI |
-
-One code for a failure, which is what a `bun run` caller and a git hook both read. An unmeasured stage takes no code of its own, since it has already refused under CI and reports on a contributor's machine, so a second code would name a state no caller branches on.
-
-## The record
-
-`--json` puts one record on stdout and keeps every diagnostic on stderr:
-
-```json
-{
-  "ok": true,
-  "root": "/path/to/checkout",
-  "scoped": true,
-  "changed": 12,
-  "summary": {
-    "ran": 23,
-    "passed": 22,
-    "skipped": 1,
-    "unmeasured": 0,
-    "failed": 0
-  },
-  "ms": 44453,
-  "stages": [
-    { "id": "indexes", "label": "Indexes", "status": "passed", "ms": 210 }
-  ]
-}
-```
-
-A failing stage carries its remedy in `failure`, and the same line goes to stderr so a caller reading neither the record nor the frame is still told what to fix.
-
-`ms` carries the wall time each stage took, including every process spawn, and the top-level `ms` sums them. Neither reading changes what a stage measures. Both exist so a slow run is attributable to a stage rather than read off a stopwatch held against the whole thing.
-
-The Tests stage holds a machine lock so one box runs one suite at a time, and its `ms` includes any time it queued behind another worktree's suite. A stage that queued carries `queuedMs`, the part of `ms` spent waiting, which is how to separate a queue from a slow suite. The field is absent on a stage that never waited. The wait is also announced on stderr when it starts, naming the holder's pid and worktree, in every mode.

package/docs/agents/hooks.md

@@ -1,78 +0,0 @@
----
-title: Hooks
-description: Running the post-merge steps through one verb, the order and the child call behind each, the root and working directory each step reads, the skip switches, the line each record maps to, and the reply link check
----
-
-# Hooks
-
-`canon hooks post-merge` runs the steps a git `post-merge` hook drives, so the hook itself stays a guard plus one call. It reads which pull requests the merge brought in, runs each step as a child `canon` call with `--json`, and prints one line per outcome worth reporting.
-
-```bash
-canon hooks post-merge
-canon hooks post-merge --root "$root"
-```
-
-| Option          | Behavior                                                                                             |
-| --------------- | ---------------------------------------------------------------------------------------------------- |
-| `--root <path>` | Main worktree root holding the board and the records, resolved from `git worktree list` when omitted |
-
-The base stack ships the same call as its `.husky/post-merge`, behind the same board guard and upgrade bootstrap, so a target that syncs it runs these five steps.
-
-Exit codes: `0` on every path, since a hook failing aborts nothing useful. Lines go to stderr, and stdout stays empty. An ordinary merge prints nothing.
-
-## The steps
-
-The steps run in this order, and the verb's `--help` lists the child calls from the same table it runs them from.
-
-| Step                     | Child call                                                    | Runs from        |
-| ------------------------ | ------------------------------------------------------------- | ---------------- |
-| Archive the merged task  | `canon tasks archive --pull-request <n> --root <root> --json` | the caller's cwd |
-| Push the records         | `canon records push --root <root> --json`                     | the caller's cwd |
-| Reclaim merged worktrees | `canon worktrees reclaim --json`                              | the caller's cwd |
-| Reinstall the CLI        | `canon upgrade --json`, under `CANON_NON_INTERACTIVE=1`       | the caller's cwd |
-| Update the plugin cache  | `canon claude plugin-update --json`                           | the caller's cwd |
-
-The archive runs once per pull request number, read as the trailing `(#NNN)` on every subject in `ORIG_HEAD..HEAD`, or on the tip alone when the merge left no `ORIG_HEAD`.
-
-The reclaim takes no `--root`. It refuses the worktree its own working directory names, so a root would let a pull inside a linked worktree remove the worktree it stands in. The archive and the push take the root because the board and the records live at the main worktree root.
-
-Each step is a separate process rather than an in-process call, so the plugin update runs the binary the upgrade just installed. Every child, and every `git` read, runs with the repository variables a hook exports stripped, since `GIT_DIR` beats `-C`.
-
-## Reply links
-
-`canon hooks reply-links` checks that every markdown link in a reply names a file on disk. The `Stop` hook `reply-links.sh` runs it on the closing message of a turn, so a dead link is corrected in the same turn.
-
-```bash
-printf '%s' "$reply" | canon hooks reply-links
-canon hooks reply-links --json < reply.md
-```
-
-| Option          | Behavior                                                                                          |
-| --------------- | ------------------------------------------------------------------------------------------------- |
-| `--root <path>` | Root a relative link resolves against, the main worktree root from `git worktree list` if omitted |
-| `--json`        | Write `{ ok, missing, message }` to stdout. `message` is present only when `ok` is false          |
-
-The reply comes on stdin, and a terminal on stdin is refused. A relative link resolves against the root, an absolute one is checked as written. The check skips placeholders such as `<path>`, globs, URLs, anchors, and any link inside a code span or fence. A `:42`, `:42-50`, or `#L42` tail is stripped before the check.
-
-Each entry in `missing` carries the `destination` as written and the `path` that was checked. A link into `.claude/worktrees/<name>/.canon/` also carries a `suggestion` with the main-root path when that file exists there.
-
-Exit codes: `0` when every link resolves or the reply holds none, `1` when at least one does not. The missing list goes to stderr. The hook turns a finding into exit 2 so the session continues, and exits 1 without blocking when it could not run the check, such as with no `jq` or no `canon` on `PATH`.
-
-## Skip switches
-
-| Variable                     | Skips                   |
-| ---------------------------- | ----------------------- |
-| `CANON_SKIP_RECLAIM=1`       | the worktree reclaim    |
-| `CANON_SKIP_UPGRADE=1`       | the CLI reinstall       |
-| `CANON_SKIP_PLUGIN_UPDATE=1` | the plugin cache update |
-
-Any non-empty value skips the step, and each switch skips its own step only.
-
-## What prints
-
-Each line is decided from the child's parsed record. A child producing no parseable record is an older binary carrying no such subcommand, and that step stays quiet.
-
-- Archive: the archived task and its number, plus a `Links not repointed in:` line naming the files in a non-empty `relinkFailed`, or the refusal's `message` with a pointer to the task board. A record carrying no `relinkFailed` reads as empty. `no-match` and `no-board` stay quiet.
-- Records push: the count of changed paths when above zero, or the refusal reason. `no-repository` stays quiet.
-- Reclaim: the removal count and the failure count, both read from the fields whatever the exit, or an unreadable reason. `gh-missing` stays quiet.
-- Upgrade and plugin update: the record's `message` on any state but `current`, or on a failure. The plugin update stays quiet on `no-claude` and `no-plugin`.

package/docs/agents/intake.md

@@ -1,81 +0,0 @@
----
-title: Intake
-description: Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
----
-
-# Intake
-
-## List
-
-`canon intake list` reports the intake folders under `.canon/intake/`, or the items one folder holds. It reads and never writes, because an answer belongs to the operator and a verb that filled one would decide what the folder exists to ask.
-
-A folder carries a two-digit ordinal ahead of its slug, as in `21-toolkit-overview`, so a listing sorts by when each opened. A bare slug still resolves: passing `toolkit-overview` matches the one folder whose name is an ordinal ahead of it, and the folder's real name is what every command reports back.
-
-```bash
-canon intake list
-canon intake list toolkit-overview --unread --json
-```
-
-| Option          | Behavior                                                                  |
-| --------------- | ------------------------------------------------------------------------- |
-| `--unread`      | Keep only what is unread: folders carrying one, or a folder's empty slots |
-| `--json`        | Emit a machine-readable record on stdout                                  |
-| `--root <path>` | Intake root, defaulting to the main worktree                              |
-
-With no slug it reports per-folder counts. With one it reports every item grouped by the cluster file holding it, each carrying its label, title, open question, suggestion, and answer.
-
-An item sits in one of three read states, and the counts keep them apart:
-
-| State     | What it means                                           |
-| --------- | ------------------------------------------------------- |
-| unread    | The slot is present and empty, so nobody has reached it |
-| answered  | The slot carries text, which is a decision already made |
-| malformed | The item carries no slot, so no verb here can answer it |
-
-The third is counted apart from both rather than folded into either. Counted as answered it hides a file that needs fixing behind a folder reading as fully worked through, and counted as unread it joins a list whose every entry `answer` then refuses.
-
-The index is skipped, since it points at items and answers nothing itself. So is any item a file displays inside a fence, which is how a folder copying the item format into its own overview is read as the sample it is rather than as an item offering a slot no reader owns.
-
-## Answer
-
-`canon intake answer` writes selections into the answer slots of one cluster file.
-
-```bash
-canon intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok
-canon intake answer toolkit-overview --cluster 11-intake-skill.md --set 3d=ok --set 9="not worth it" --json
-```
-
-| Option                | Behavior                                              |
-| --------------------- | ----------------------------------------------------- |
-| `--cluster <file>`    | Cluster file the items live in, with or without `.md` |
-| `--set <item=answer>` | Answer to land on an item, repeatable                 |
-| `--json`              | Emit a machine-readable record on stdout              |
-| `--root <path>`       | Intake root, defaulting to the main worktree          |
-
-Items are labeled per cluster file, so a selection names the cluster and the label together. A label alone names an item in every cluster at once.
-
-A label may carry a letter suffix, as in `3a` beside `3`, which is how a pass records a finding split after the fact rather than renumbering every item below it. Pass it exactly as the heading spells it.
-
-One call writes one cluster. A call per selection is the alternative, and several of those against the same file read it before any of them writes, so every answer but the last is lost with nothing reporting it. The selections split on the first `=`, so an answer carrying its own survives intact.
-
-An item already carrying an answer refuses rather than being overwritten, and one filled item refuses the whole batch, so a partly applied write never lands. Drop the named item and send the rest.
-
-Exit codes: `0` every named item now carries its answer, `1` refused. The `reason` field carries `no-intake`, `no-folder`, `ambiguous-slug`, `no-cluster`, `no-item`, `answered`, or `bad-input`. A bare slug matching more than one ordinal-prefixed folder refuses as `ambiguous-slug` rather than `no-folder`, naming every match in `detail`.
-
-An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this, which matters most here because the verb writes.
-
-`bad-input` covers a malformed command line: no cluster, no selection, a selection that parses to no label and answer, an empty answer, an answer carrying a line break, or two answers for one item. It is separate from the reasons describing the folder, so a caller that mistyped a flag is not sent to repair a file that is fine.
-
-An empty answer refuses rather than writing an empty slot. The slot means unread while it is empty, so writing one back would report an item as answered that nobody decided.
-
-An answer occupies one line, and one carrying a line break refuses before anything is read. Writing it splices a bare continuation into the item that matches none of the patterns the reader tests, so the slot reads back as the text before the break while the item counts as answered, and the refusal on an already-answered item then leaves hand-editing the file as the only correction. The whole batch refuses, so a good selection beside a broken one never lands half applied.
-
-The folder is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. The write is an edit inside a file that already exists, which `Edit` and `Write` refuse from a linked worktree and a shell stream editor may not do, so the verb resolves the root in-process and rewrites whole lines.
-
-Skills branch on the reason rather than on the exit code:
-
-```bash
-canon intake list toolkit-overview --unread --json | jq -r '.clusters[] | .cluster'
-```
-
-For the folder layout, the item format, the answer contract, and retrieval, see `claude/skills/plan-intake/references/intake.md`.