@erclx/canon 5.38.0 → 5.40.0

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/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 `commands.md` 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/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/hooks.md

@@ -1,58 +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, and the line each record maps to
----
-
-# 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`.
-
-## 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`.