@erclx/canon 4.118.0 → 4.120.0

package/claude/skills/teach-workspace/SKILL.md

@@ -32,10 +32,10 @@ canon teach list --json
 
 It reports every workspace with its path, its counts, and the ordinal a new one would take. A `no-teach` refusal means the project has opened none yet, which is the new-workspace path in Step 1 rather than a reason to stop. The open verb creates the folder.
 
-From a linked worktree the file-editing tools refuse every path under the main root and offer a worktree copy instead, which is a second file no later session reads. Never take that redirect. The route splits by what the write does to the file:
+Every path under the main root is a main-root write, routed the way `session-worktree` states. The route splits by what the write does to the file:
 
-- Creating a whole file that does not exist yet, which is a lesson, a reference page, and a learning record, goes out as one plain shell command carrying a heredoc
-- Changing a line inside a file that already exists goes through the verb that owns it, since the stream editors are banned and no other shell route reaches it
+- Creating a whole file that does not exist yet, which is a lesson, a reference page, and a learning record, goes out as a heredoc
+- Changing a line inside a file that already exists goes through the verb that owns it
 
 ## Step 1: open or resume
 
@@ -239,7 +239,7 @@ Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to
 
 The handoff is its own file rather than a shared one. The routed-facts file another skill writes is deleted by whichever pass folds it, so a second producer's unread work goes with it, and a sibling path costs the folding skill one more read and removes the interaction.
 
-An append is a whole-file operation, so send it as a plain single `Bash` command carrying a heredoc, per Step 0. Then tell the operator that `/docs-fold` folds the file in from a branch. The proposal costs nothing tracked and runs anywhere, while the page it describes is a tracked file, so the fold is a worktree operation and the workspace it came from is not.
+An append is a whole-file operation, so send it as a heredoc, per Step 0. Then tell the operator that `/docs-fold` folds the file in from a branch. The proposal costs nothing tracked and runs anywhere, while the page it describes is a tracked file, so the fold is a worktree operation and the workspace it came from is not.
 
 ## Output
 

package/claude/skills/ui-checklist/SKILL.md

@@ -72,7 +72,7 @@ When a checklist is produced, write it directly to `.canon/tmp/handoff/ui-checkl
 
 The path names the artifact rather than this skill, so it does not move when the skill is renamed. A checklist written by an older binary still lands where the consumer looks.
 
-From a linked worktree the file-editing tools refuse that path, so the checklist goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+The checklist is a main-root write, so it goes out as a heredoc, routed the way `session-worktree` states.
 
 Skip the file write when there is nothing to verify visually and nothing shipping untested.
 

package/claude/skills/ux-audit/SKILL.md

@@ -64,7 +64,7 @@ Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to
 
 Write the full report directly to `.canon/review/ux-audit-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite.
 
-From a linked worktree the file-editing tools refuse that path, so the report goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+The report is a main-root write, so it goes out as a heredoc, routed the way `session-worktree` states.
 
 If there are no observations, write `✅ No observations.` to the file with a timestamp.
 

package/claude/skills/ux-measure/SKILL.md

@@ -108,7 +108,7 @@ Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to
 
 Write the full reading directly to `.canon/review/ux-measure-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite.
 
-From a linked worktree the file-editing tools refuse that path, so the reading goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+The reading is a main-root write, so it goes out as a heredoc, routed the way `session-worktree` states.
 
 The `.canon/review/` directory is gitignored. Do not stage or commit the file.
 

package/claude/skills/ux-walkthrough/references/relay.md

@@ -4,7 +4,7 @@ Read when the operator calls a batch, and at the start of the walkthrough when a
 
 ## Where the batch goes
 
-- Send it to the controller where the session was dispatched by one, resolved per the Channel rule, matched by name through `canon gov list --rules --json` rather than a path a target may not have installed.
+- Send it to the controller where the session was dispatched by one, through `canon:session-relay`, which resolves the address and carries the send.
 - Give it to the operator as one list in the conversation where no controller exists. The walkthrough file is the handoff either way.
 
 ## When

package/docs/agents/commands.md

@@ -23,10 +23,10 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon indexes list [path]`      | Flatten every folder index under a path into one `{path, title, description}` catalog (`--json`)                                                                                                                                                                                                                             |
 | `canon docs [topic]`             | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                                                                                                     |
 | `canon design render`            | Render `canon/DESIGN.md` tokens to HTML and CSS, declaring each vendored face the typography table names with `--embed-fonts`                                                                                                                                                                                                |
-| `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                            |
+| `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`                                                                                                                                                                                               |
 | `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, components, and references against a caller-resolved `--root` (`--out`), defaulting to the main worktree                                                                                                                                  |
 | `canon design css`               | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone)                                                                                                                                                                                                                              |
-| `canon design install`           | Install the base stylesheet into a project at `.claude/design/base.css`                                                                                                                                                                                                                                                      |
+| `canon design install`           | Install the neutral base stylesheet into a project at `.claude/design/base.css`                                                                                                                                                                                                                                              |
 | `canon design sync`              | Update a base stylesheet already installed under `.claude/design/`                                                                                                                                                                                                                                                           |
 | `canon slides render`            | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr                                                                                                                                                                                                                 |
 | `canon slides list`              | List the available slide layouts (`--json` for the catalog)                                                                                                                                                                                                                                                                  |
@@ -96,8 +96,9 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon pr head`                  | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                                                                                                                                                                              |
 | `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean, and `conflicted` when the branch conflicts with its base (`--root`, `--json`)                                                                                                                                  |
 | `canon pr review-state`          | Report the commit and instant the last review pass covered, off the pass's own marker rather than the fields GitHub stamps at submission (`--root`, `--json`)                                                                                                                                                                |
-| `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`, `--preview`)                                                                                                                         |
+| `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`, `--preview`, `--checklist`, `--local`)                                                                                               |
 | `canon pr preview`               | Dispatch the Pages deploy on a pull request's branch and report the preview address the run prints, refusing a deploy that passes no `--branch` (`--root`, `--json`, `--timeout`)                                                                                                                                            |
+| `canon pr local`                 | Report the `localhost` address of the dev server this worktree is running, never one in another worktree, or replace that line on the evidence comment with a note on `--remove` (`--root`, `--json`, `--remove`, `--note`)                                                                                                  |
 | `canon repo metadata propose`    | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)                                                                                                                                                             |
 | `canon repo metadata apply`      | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`)                                                                                                                                                        |
 | `canon census [path]`            | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                                                                                                                                                                         |

package/docs/agents/counts.md

@@ -43,7 +43,7 @@ Nothing stands between the trigger and the number, which is the rule an author w
 
 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: `canon/context/development/gates.md` 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 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 81 rules` at every width, and reached `the toolkit authors 81 rules` only at a width admitting the indirect-noun shape below. The two words reach both at 75 sentences and no false positive.
 

package/docs/agents/index.md

@@ -31,16 +31,20 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+- [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
-- [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Records push](records-push.md): Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
+- [Records validate](records-validate.md): Validating the session records and the standards corpus, the per-kind checks, which root each kind defaults to, the exit codes, and the refusal reasons
+- [Records](records.md): The two roots a record folder resolves at, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation and the private-remote backup are described
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Review classification](review-classification.md): Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Rule citations](rule-citations.md): Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the three forms a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
-- [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and moving a session to another machine with export and import
+- [Sessions transfer](sessions-transfer.md): Moving a session to another machine, the export bundle and its manifest, placing it with import, the refusal reasons, and what a resume on the target depends on
+- [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
@@ -48,6 +52,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, deriving the branch a dispatch and a worker both take, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
-- [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions, the refusal reasons, and why every write here runs through a verb
+- [Teach authoring](teach-authoring.md): Resolving what the next lesson needs before it is written, rendering a lesson body's blocks to HTML, and rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions
+- [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
 - [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

package/docs/agents/install-and-sync.md

@@ -19,10 +19,13 @@ removes a stale `.claude/GOV.md` from the retired build. Use
 
 Everything under `.claude/rules/canon/` belongs to the toolkit, so a rule
 there that the toolkit no longer ships is deleted on sync, edited or not. That
-is how a retired or renamed rule stops loading in a target. The sync lists each
-deletion by path before it applies, and the target's git diff is the record
-afterwards. `canon sync --check` lists the same file as `retired` before any
-sync runs. A project's own rules belong under `.claude/rules/project/`, where
+is how a retired rule stops loading in a target. A renamed or renumbered rule
+the toolkit declares in `governance/renames.toml` moves instead: the sync
+installs the rule under its new name and deletes the old file, whether or not
+the target's stamp records a stack. Local edits to the old file are not
+carried, and the sync says so. The sync lists each change by path before it
+applies, and the target's git diff is the record afterwards. `canon sync
+--check` lists the same file as `retired` or `renamed` before any sync runs. A project's own rules belong under `.claude/rules/project/`, where
 `canon standards rule` reserves `900-999` for them, and a rule placed under
 `canon/` instead is lost on the next sync.
 
@@ -164,9 +167,11 @@ matches what the toolkit installed, `customized` when the project edited it,
 `stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
 when the project authored it, or `drifted` when no stamp covers it. Governance
 also reports `missing`, for a rule the target's recorded stack lists that its
-tree does not hold at all, and `retired`, for a rule under
+tree does not hold at all, `retired`, for a rule under
 `.claude/rules/canon/` the toolkit no longer ships, which the next sync
-deletes. A `retired` file counts toward `--exit-code`, since one sync clears it.
+deletes, and `renamed`, for one the toolkit ships under a new name, which the
+next sync moves. A `retired` or `renamed` file counts toward `--exit-code`,
+since one sync clears it.
 
 Use `--json` for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
 and missing files are both excluded from that exit code: a project-authored

package/docs/agents/pr-evidence.md

@@ -122,14 +122,30 @@ already holds, the same way the preview address is carried. That is what keeps
 already ticked, since `git-pr` deletes the handoff once the first post reports
 success and no later call has a file to pass.
 
-The option does not decide `no-evidence`. A branch with a checklist and no
-changed evidence image still reports `no-evidence`, and the caller posts the
-checklist on its own, which is what it did before this option existed. A path
+The option does not decide `no-evidence` alone. A branch with a checklist and
+no changed evidence image still reports `no-evidence`, and the caller posts the
+checklist on its own, which is what it did before this option existed. A
+checklist passed together with `--local` is the exception, covered below. A path
 that cannot be read, or one holding nothing, refuses as
 `unreadable-checklist` rather than rendering without it: the caller deletes the
 handoff once a post succeeds, so a silently dropped checklist is the only copy
 gone.
 
+## The local preview line
+
+`--local <url>` adds `**Local preview:** <url>` to the opening block: under the
+hosted `**Preview:**` line when there is one, and as the first line when there
+is not. The hosted line always keeps the first position, since that is the one
+line the carry-forward reads for it. A run without the option carries forward
+the local address the marked comment already holds, the same as the other two.
+
+The option does not turn `no-evidence` into `ok` on its own. A branch with a
+dev server running and no rendered change would otherwise get a comment holding
+a link and nothing else. Together with `--checklist` it does, so the link and
+the checklist land in one comment rather than the checklist going out alone.
+`canon docs pr-local` covers where the address comes from and how the line is
+removed at close.
+
 ## What a collapsed comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed

package/docs/agents/pr-local.md

@@ -0,0 +1,102 @@
+---
+title: The pull request local preview
+description: How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
+---
+
+# The pull request local preview
+
+`canon pr local` reports the `localhost` address of the dev server the current
+worktree is running. `git-pr` calls it ahead of the evidence comparison and
+passes the address through `canon pr evidence --local`, so a reviewer on the
+same machine gets the running branch to click into beside the screenshots and
+the checklist. A workflow on the pull request's `closed` event calls it again
+with `--remove`, which replaces the line with a note.
+
+```bash
+canon pr local --json
+canon pr local 1341 --remove --json
+```
+
+## How it finds the server
+
+The verb reads every TCP socket in `LISTEN` with the process that owns it. It
+keeps a socket when that process's working directory sits inside the
+worktree's toplevel, including a subfolder, since some tools change into one
+before they listen. It then requests `/` on each kept port and reports the
+lowest one serving an HTML page.
+
+The HTML test is there because a working tree often holds more than one
+listener. A test runner's own server, or a dev server's reload socket, answers
+HTTP too, and a reviewer opening either gets a bare 404 rather than the branch.
+
+Sockets are read through `lsof` where it is installed. A Linux machine without
+it falls back to `/proc/net/tcp` and `/proc/net/tcp6`, matched against each
+process's `fd` table. A machine with neither refuses as `no-listener-reader`.
+
+The port is never derived from the worktree. A port helper needs a per-stack
+base port the toolkit cannot know, and a server started by hand or by an
+earlier session would not match it anyway.
+
+## Why another worktree's server is never reported
+
+A server running in a different worktree shows a different branch, and a link
+to it on this pull request would show a reviewer the wrong code.
+
+- A sibling linked worktree sits outside this one's toplevel, so its process
+  never matches.
+- The main checkout's server, read from a linked worktree, sits outside the
+  linked worktree's toplevel for the same reason.
+- A linked worktree's server, read from the main checkout, sits inside the main
+  toplevel. The verb excludes everything under `.claude/worktrees/` for that
+  case alone.
+
+## What the record carries
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason               | What it means                                                         |
+| -------------------- | --------------------------------------------------------------------- |
+| `ok`                 | A server answered. `url` carries the address and `port` the port.     |
+| `no-server`          | Nothing inside this worktree served an HTML page.                     |
+| `no-listener-reader` | Neither `lsof` nor `/proc` is available, so no socket could be read.  |
+| `removed`            | `--remove` replaced the local line on the evidence comment.           |
+| `no-comment`         | `--remove` found no comment carrying the evidence marker.             |
+| `no-line`            | `--remove` found the comment but no local line on it.                 |
+| `gh-missing`         | `--remove` needs `gh` and it is not on the path.                      |
+| `gh-failed`          | `--remove` could not read the comments or could not edit the comment. |
+
+The exit is 0 on `ok` and on every `--remove` outcome that finished, including
+the two no-ops, and 1 on every refusal. A caller on an older binary gets an
+unknown-subcommand error instead of a record, which `git-pr` reads as a skip.
+
+## Removing the link at close
+
+The link goes dead once the branch's server stops, and nothing on the pull
+request says so. `--remove` runs on the pull request's `closed` event, merged or
+abandoned, from a workflow seeded into every target:
+
+```yaml
+on:
+  pull_request:
+    types: [closed]
+```
+
+It reads the comment carrying the `pr-evidence` marker, replaces the
+`**Local preview:**` line with the `--note` text, and edits the comment itself
+through `gh api`. The verb writes here rather than handing a body back, because
+its caller is a workflow with no session to post one. Every other byte of the
+comment stays as it was, which keeps the marker, the checklist delimiters, and
+any ticked box intact. A second run finds no line and reports `no-line`.
+
+A fork pull request gets a read-only token, so the workflow skips the edit with
+a notice rather than failing the close.
+
+## What this does not cover
+
+The link can still go dead while the pull request is open, such as when the
+session holding the server retires. Only the close is covered, and a re-render
+after a push carries the line forward whether the server still answers or not.
+
+The hosted `**Preview:**` line from `canon pr preview` stays on the comment
+after close, even though its deployments are deleted then. `canon docs
+pr-preview` covers that path.

package/docs/agents/pr-preview.md

@@ -100,5 +100,5 @@ request never deploys.
 ## What this does not cover
 
 The verb builds only the deployed-and-public case. A private repository whose
-previews need access protection, and a project with no deploy at all where a
-local server would stand in, both wait for a project that needs them.
+previews need access protection waits for a project that needs it. A local
+server stands in where there is no deploy, through `canon docs pr-local`.

package/docs/agents/records-push.md

@@ -0,0 +1,61 @@
+---
+title: Records push
+description: Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
+---
+
+# Records push
+
+`canon records push` commits the backed record folders to a private remote and pushes them. `canon records pull` fetches the other direction and writes them back. Both take `--json` and `--root` the way `validate` does, and both exit `0` on agreement and `1` on a refusal.
+
+```bash
+canon records push
+canon records push --json
+canon records pull
+```
+
+At the `.canon` root, the backed folders are every top-level directory less three: `tmp`, which is deletable without loss, `ordinal-locks`, whose entries are transient per claim and would race the claim they guard, and `.records.git`, which is the history the rest are pushed into. Nothing bounds the set from outside, since the claude manifest ships one `.canon/` root entry and names no folder, so a record folder added later enters the payload on its own rather than waiting on a name written here. A push names each folder in scope that the records index has never tracked before, so a folder that picked up a name by mistake, such as a misrouted scratch write, is visible in the report rather than entering the payload silently. The report also lists every file new to the history under `added`, since a stray file inside a folder already tracked is visible only by name.
+
+The three excluded names bound the records index as well as the disk. A name an older binary committed, such as `tmp`, is removed from the history once and reported under `dropped`, and no later push stages it again. That removes it from the tip going forward and purges nothing from earlier commits the remote already holds. A project's own drafts folder needs no config to be backed: moved to `.canon/<name>/`, it is a top-level directory like any other and enters the payload on the next push. The legacy `.claude` root keeps a fixed allowlist instead, since that root also holds tracked `skills/`, `rules/`, and `hooks/` a push must never carry, and an exclusion set there would stage all three. Each name is a top-level record folder and every archive sits inside the one it archives, so the set stays at one entry per surface however many archives appear, and it deliberately does not match the six record kinds `validate` hardcodes.
+
+Records are gitignored by design, so the history lives in a second git directory at `.records.git` inside the record root, with that root as its work tree. Both resolve off the root together rather than folder by folder, since a history opened at one root beside a work tree at the other would stage the deletion of every folder a move relocated. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the backed folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
+
+## Setup
+
+A person creates the records repository once per machine, and the verbs refuse with the commands when it is absent:
+
+```bash
+git --git-dir=.canon/.records.git init
+git --git-dir=.canon/.records.git remote add origin <private-repo-url>
+printf '.canon/\n' >> .gitignore
+```
+
+The ignore line is repeated here rather than left to the install, because the person running these commands is the one who creates the directory and the rule is worth reading beside the command that needs it. The claude manifest ships `.canon/` too, so a project that ran `canon tooling sync` already carries it and this line is a no-op there. One root entry covers the history and every record beside it, which is what makes the rule worth stating once rather than per folder.
+
+Point it at a private repository, and at one that is not a remote of the project. Records carry the memory pen, the review reports, and the groundwork trails, so a public project publishes all of it to anyone who fetches all refs. `push` compares the configured origin against every remote of the project and refuses on a match. A read of that list which fails refuses as well, since an empty list clears the comparison for every origin and a gate that passes on its own failure is no gate.
+
+## Refusals
+
+| Reason              | What fired                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `split-roots`       | Record folders sit under both roots, so the resolved work tree is not the whole set    |
+| `no-repository`     | No `.canon/.records.git`, answered with the two setup commands                         |
+| `no-remote`         | The records history has no `origin`                                                    |
+| `remote-unreadable` | The project's own remotes could not be read, so the shared-origin gate could not run   |
+| `remote-shared`     | The records origin is also a remote of the project                                     |
+| `no-remote-records` | `pull` found no branch on the records origin                                           |
+| `local-changes`     | `pull` found records on disk that the history does not carry                           |
+| `local-ahead`       | `pull` found local commits that never reached the origin                               |
+| `unsafe-payload`    | `push` found a pending file over 25 MB or carrying a credential, named under `blocked` |
+| `git-failed`        | A git call failed, with its stderr in the message                                      |
+
+`split-roots` runs ahead of every gate below it and fires on a half-migrated tree, which is what a `canon migrate records` run that failed partway leaves. `recordRoot` answers for the whole tree on the first root that exists, so a folder left at the old root is absent from the work tree while the records index still names it, and an unguarded `add -A` would stage its deletion and drop it from the remote on the next push. Finish the move, or put the stranded folders back beside the others.
+
+`unsafe-payload` runs before anything is staged, so a refusal leaves the index, the log, and the object store as it found them. It reads every new or changed file the push would stage and blocks one over 25 MB, which is read off the file's size without opening it, or one carrying a value `canon secrets scan` would report, through the same patterns and the same `canon-allow-secret` marker. It refuses the whole push rather than skipping the file, and `--json` lists each path with its cause and a detail that names the credential's kind and line, never its value. Move the file out of the record folders, such as into `.canon/tmp/`, or remove the credential, then push again. The guard reads only what this push would add, so a credential committed before it existed stays in the history unreported.
+
+A push the remote rejects undoes the commit that run made and leaves the records on disk, so the next run does not send a payload the remote already refused. A history an older binary committed and left unpushed is outside that undo, and the guard never reads it either, so every push sends the same blob again. Reset it by hand from the project root to the last commit the origin holds, `git --git-dir=.canon/.records.git --work-tree=.canon reset <commit>`, and push again. The `--work-tree` is required, since the setup `init` marks the history bare and git refuses that reset on a bare repository.
+
+The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding no backed folders has nothing to lose, so a restore onto a fresh checkout runs straight through.
+
+## When it runs
+
+`.husky/post-merge` runs `push` after the task archiving loop, on every merge rather than only on one that archived a task. A review report and a memory entry both land on runs that close nothing. The call sits inside an `if` and last in the file, so an unreachable remote neither aborts the hook nor delays the archiving above it, and a checkout that never ran the setup reports nothing. Anything the hook misses is covered by running the verb by hand.

package/docs/agents/records-validate.md

@@ -0,0 +1,73 @@
+---
+title: Records validate
+description: Validating the session records and the standards corpus, the per-kind checks, which root each kind defaults to, the exit codes, and the refusal reasons
+---
+
+# Records validate
+
+`canon records validate <kind>` reports where a file and the standard governing it disagree. Five kinds are gitignored folders under the record root, resolved at `.canon/` first: `plans`, `groundwork`, `intake`, `memory`, and `teach`. The sixth is `standards`, the authoring corpus, which is tracked and installed rather than scratch.
+
+```bash
+canon records validate plans
+canon records validate memory
+canon records validate standards
+canon records validate intake --json
+```
+
+| Option          | Behavior                                                            |
+| --------------- | ------------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout                             |
+| `--root <path>` | Project root, defaulting to the main worktree except on `standards` |
+
+It reads and never writes, and the reason splits by kind. A session record is per-machine scratch with no history behind it, so a repair that guessed wrong could not be undone. A standard installs into every target and is cited by bare filename, so a rename the verb performed would reach further than the file it moved, which is why a finding naming one says so.
+
+`standards` reads the authoring root at `standards/` where it exists and a copy at `.claude/standards/` otherwise. The authoring root wins because it is the only tree anyone authors in and the only one the resolver answers from, so a finding fixed anywhere else is fixed where nothing reads it. No repository generates the second candidate any more, which leaves it as a floor under a target holding a copy an older toolkit installed. The walk stays flat, matching the catalog.
+
+Nothing fires it automatically. The five record folders are gitignored, so the standards-audit hook exits early on them and any check reading changed files from git never lists one. The corpus is tracked and still unreached, since the markdown audit reads content across the files git lists and rules on no filename. The verb runs at the moment a session claims the record is finished, which is the same placement `canon tasks validate` takes over the board.
+
+The two record roots every kind resolves at are in `records.md`.
+
+## What each kind checks
+
+| Kind         | What it reports                                                                                                                                                                                                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, a question carrying no suggestion or no answer slot, and a batch still staged with a `**Batch N**` sub-heading inside the one file rather than split into its own plan |
+| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                                                             |
+| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                                                        |
+| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part                                                                                                                   |
+| `standards`  | A standard missing `title` or `description`, an absent `## Scope` section, a scope section carrying no `Does not govern:` list, a statement anchoring nothing, and a filename naming no part of the path the statement governs                                                                                                                    |
+| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal                                  |
+
+The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
+
+The item check skips `00-overview.md` and `99-next-session.md`, since neither holds items and running it over the handoff would report every heading it carries. The memory walk skips `index.md` for the same reason, since the catalog is generated from its siblings rather than authored as an entry.
+
+A memory `category` is compared against the sentence-case form of the filename prefix rather than checked field by field, so one finding covers a prefix outside the four types, a field disagreeing with the prefix, and a casing drift that would open a second group in the catalog. The body check runs on `feedback` and `project` entries alone, because a `user` or `reference` entry is a single sentence by design and has no rule to apply.
+
+The standards filename check derives a word from the governed path rather than counting words in the name. Every member of the corpus is named for the artifact its scope statement governs, and one word is what that produces rather than the rule itself, so a check keyed on word count would pass a conforming single word naming the wrong artifact. Each path segment offers its own word, a dotted container segment offers none, a hyphenated segment offers its parts, and the singular and the plural both match.
+
+The scope statement is read exactly as `scripts/standards/list.sh` reads it for the catalog's `appliesTo` field: backticked spans in the first sentence alone, with an attribute standard resolving where that sentence backticks nothing and the statement says it governs an attribute. One sentence read two ways would let a standard pass the check while publishing a different jurisdiction to every consumer of the catalog. An attribute standard is exempt from the filename derivation because it governs no path to derive from, and a statement that anchors nothing and claims no attribute is reported as `scope-unanchored` rather than passed, since silence there would let the backticks be removed to disable the check.
+
+An absent `## Scope` section suppresses the filename finding. The name derives from the statement, so a missing section leaves nothing to derive against, and reporting both would name one defect twice and point the fix at the wrong file. The walk skips `index.md`, which is generated from its siblings rather than authored.
+
+A plan section opens as a bold label or as an H2 and the check counts both, naming the standard's spelling when it reports one missing. The corpus splits roughly four to one between the two forms, so failing the variant would report nearly every plan on a rule that costs a reader nothing.
+
+A section runs to the next marker-shaped line whatever it names, so a plan carrying a label of its own closes the section above it rather than collecting into it. Fenced blocks are dropped before any of this, since a plan showing the shape it writes puts real-looking bullets and headings inside a fence.
+
+## Exit codes and refusals
+
+Exit codes: `0` every check passed, `1` refused, `2` at least one record carries a finding. A `reason` field carries which gate fired: `no-folder` when none of the kind's directories exist, and `unknown-kind` when the argument names no published kind. A `no-folder` message names every candidate, so a record kind's refusal names both record roots and the `standards` refusal names the authoring root and the installed copy.
+
+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` array and its `reason` rather than the exit when a skill consumes this.
+
+The four record folders are shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree validates the same records every other session reads.
+
+`standards` takes the other default, the root of the checkout the caller stands in. The corpus is tracked, so a linked worktree holds its own edited copy, and resolving the main root there would report on a tree the session never touched while saying nothing about which one it read. A session that adds or renames a standard inside a worktree is the case, and it is the one the check exists for.
+
+Skills branch on the findings rather than on the exit code:
+
+```bash
+canon records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)"'
+```
+
+For the shapes each check enforces, see `standards/plan.md`, `standards/groundwork.md`, `standards/intake.md`, `standards/memory.md`, and `standards/standard.md`.