@erclx/canon 5.32.0 → 5.34.0

package/docs/agents/gov-detect.md

@@ -0,0 +1,47 @@
+---
+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": "200-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/index.md

@@ -9,7 +9,7 @@ category: Agent surface
 CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
-- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, select, edit, mark, and capture frames
+- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, fit, select, edit, mark, and capture frames
 - [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report
@@ -23,27 +23,30 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Drift surfaces](drift-surfaces.md): 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
 - [Driver](driver.md): 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
 - [Merge gate](gate.md): 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
+- [Rule detection](gov-detect.md): 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
 - [Hooks](hooks.md): 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
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen and canon indexes list, plus when regen auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Intake](intake.md): 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
-- [Key Changes bijection](key-changes.md): Comparing the files a pull request body's Key Changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
+- [Key changes bijection](key-changes.md): Comparing the files a pull request body's Key changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 - [Label coverage](label-coverage.md): Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
 - [Markdown audit weight](markdown-audit-weight.md): The structural half of the markdown audit, being bullet and paragraph weight, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and why none of them gates
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Migrate](migrate.md): What each canon migrate verb moves and rewrites, what it refuses, the markers that keep an old spelling, and the idempotence check a second run gives
 - [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 layout](pr-evidence-layout.md): How canon pr evidence groups screenshots into one block per view with a row per width and a column per theme, when a base column appears, where a name outside the form lands, how the commit line links, and when the blocks open
 - [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, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
 - [The pull request frame store](pr-frames.md): How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
+- [The pull request draft lift](pr-lift.md): How canon pr lift removes the draft mark once the reviews, evidence, standing, and CI all read clear at the head, the gate order and what each reads, the wait on a pending run, the re-read before the write, the refusal reasons it names, and what --check reports
 - [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 drops the address line with --remove
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, refuses a branch its push filter does not serve, 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
 - [The pull request checklist tick](pr-tick.md): How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
 - [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 stale](records-stale.md): Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, counting the releases since the requirements record was last reviewed, and the exit codes and refusals
+- [Records stale](records-stale.md): Counting the releases since the requirements record was last reviewed, where the review date is read from, and the exit codes and refusals
 - [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, the memory review queue, and the private-remote backup are described
+- [Records](records.md): The two roots a record folder resolves at, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation, the canonical review count, 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 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
 - [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

package/docs/agents/indexes.md

@@ -5,7 +5,7 @@ description: Flags, exit codes, and JSON shape for canon indexes regen and canon
 
 # Indexes
 
-`canon indexes regen` rewrites `index.md` files from sibling frontmatter. With no positional paths, it walks the current directory. With paths, each resolves by walking up to the nearest indexed ancestor, bounded by `--root`.
+`canon indexes regen` rewrites `index.md` files from sibling frontmatter, so a hand edit to a generated index is lost on the next run. With no positional paths, it walks the current directory. With paths, each resolves by walking up to the nearest indexed ancestor, bounded by `--root`.
 
 Duplicates dedupe. The whole-repo walk prunes `.git`, `node_modules`, and anything `.gitignore` covers via `git check-ignore`.
 

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

@@ -28,11 +28,11 @@ 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 rule that only routed a path to a standard ships under that standard's name,
-but the tasks and plan rules are hand-written at `canon/tasks.md` and
-`canon/plan.md`. A held `standards/tasks.md` or `standards/plan.md` syncs in
-place by basename, and the groundwork, intake, and session copies are deleted
-as retired. The markdown rule is hand-written at `writing/markdown.md`, and a
-target holding `standards/markdown.md` keeps it there as `800-prose` retires.
+but the tasks, plan, context, and skill rules are hand-written at `canon/` and
+`claude/skill.md`. A held copy of each syncs in place, and the groundwork,
+intake, session, design, readme, and rule copies are deleted as retired. The
+markdown rule is hand-written at `writing/markdown.md`, and a target holding
+`standards/markdown.md` keeps it there as `800-prose` retires.
 
 A project's own rules belong under `.claude/rules/project/`, where
 `canon standards rule` reserves `900-999` for them, and a rule placed under
@@ -112,6 +112,10 @@ Every documented agent path already passes the argument, including
 `canon init`. The confirm-then-apply prompt after it still resolves to `Yes`
 headlessly, so a call that names its stack is unchanged.
 
+`--add` with no stack installs the named rules into the one positional, or the
+current directory, and keeps the recorded chain. Pass `./node` to force a target
+named like a stack. [Rule detection](gov-detect.md) proposes the names.
+
 `canon gov install` also refuses the toolkit root as a target. It resolves the
 target before anything else, so a path that does not exist fails rather than
 being scaffolded.
@@ -146,12 +150,7 @@ runs the verb again for that name.
 
 `canon gov regen` is the one governance verb that runs against the toolkit root,
 because the `.claude/rules/` it writes there is produced output rather than an
-operator's working copy. It first writes `governance/rules/standards/`, one rule
-per standard under `standards/` whose frontmatter carries `paths:`, clearing the
-folder so a standard that drops the field loses its rule. A standard named like
-a band folder or an authored rule, or a `paths:` or `rule:` that is not a list
-of strings, refuses the whole run before anything is written. It then reads the
-stack recorded in `internal/governance.toml`
+operator's working copy. It reads the stack recorded in `internal/governance.toml`
 into `.claude/rules/canon/`, installs anything under `internal/rules/` into a
 separate `.claude/rules/internal/`, and clears both destinations first so a
 rule the record stopped naming disappears. `internal/` is what this repository

package/docs/agents/key-changes.md

@@ -1,11 +1,11 @@
 ---
-title: Key Changes bijection
-description: Comparing the files a pull request body's Key Changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
+title: Key changes bijection
+description: Comparing the files a pull request body's Key changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 ---
 
-# Key Changes bijection
+# Key changes bijection
 
-`canon pr key-changes` reads the `## Key Changes` section of a pull request body, lifts the paths its bullets claim, and compares that set against the files the pull request actually changed. This repository squash-merges, so the body becomes the commit message and the record on the trunk once the branch is gone.
+`canon pr key-changes` reads the `## Key changes` section of a pull request body, lifts the paths its bullets claim, and compares that set against the files the pull request actually changed. This repository squash-merges, so the body becomes the commit message and the record on the trunk once the branch is gone.
 
 ```bash
 canon pr key-changes
@@ -45,7 +45,7 @@ A generated asset and a regenerated index belong in the incidental class and are
 
 ## What counts as a claim
 
-Only `## Key Changes` is read. `## Technical Context` legitimately names files a branch never touched, such as an install stamp inside a target, so widening the read manufactures a finding out of every argument an author made for the change.
+Only `## Key changes` is read. `## Technical context` legitimately names files a branch never touched, such as an install stamp inside a target, so widening the read manufactures a finding out of every argument an author made for the change.
 
 Inside the section, every backticked span in a bullet is read, and the bullet's first comma outside a span divides the ones that can accuse from the ones that can only credit. That one lever was chosen by measurement. Over the 23 merged pull requests in this repository carrying the section, reading whole bullets reported 16 paths as claimed-but-untouched and every one was a file the body named for context. Cutting at the comma left 110 claims of the original 149 and took the false reports to 2. A list of sixteen clause-opening words tried beside it removed nothing the comma had not already removed, because this corpus punctuates every one of them.
 

package/docs/agents/label-coverage.md

@@ -70,6 +70,17 @@ It reports and never gates. Whether an uncovered surface deserves a label is a j
 
 A project declaring no map refuses with `no-map`, which is an answer rather than a fault. Such a project is labelled silently by design, and treating the absence as a break would make the map mandatory for every target. `canon audits run` reads that one reason as an expected absence and every other refusal as a measure that did not run.
 
+## Applying the set
+
+`canon labels apply <number>` reads the same earned set and adds each label the open pull request lacks, so a pull request opened outside `git-pr` takes one command to label.
+
+```bash
+canon labels apply 123 --json
+canon labels apply 123 --check
+```
+
+It binds to the pull request before anything is read or written, and refuses with `head-mismatch` unless the head is the current branch and the state is open, under `--check` as well. It adds and never removes, so a label a person applied stays. A label the remote does not carry lands in `missingOnRemote` and is never created. `--check` writes nothing and exits 2 when labels are owed. A project declaring no map adds nothing and exits 0.
+
 ## What it does not measure
 
 A prefix reaching no path is invisible here. A row left behind by a deleted folder stays in the map forever, and this verb has nothing to say about it. That is the map going stale from the other side and a second measure rather than this one.

package/docs/agents/migrate.md

@@ -9,7 +9,7 @@ description: What each canon migrate verb moves and rewrites, what it refuses, t
 
 `migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
 
-`migrate skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It carries two plain renames as well, where a skill carried no prefix and changed its name because the old one described a job it no longer does, landing on `ui-checklist` and `context-fold`, and one merge, where the five per-kind document drafters land on `draft-doc`. It leaves the pointer answering under the fold skill's old name in place. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then.
+`migrate skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It carries two plain renames as well, where a skill carried no prefix and changed its name because the old one described a job it no longer does, landing on `ui-checklist` and `context-fold`, and one merge, where the five per-kind document drafters land on `draft-doc`. It carries one namespaced-only rename, `canvas` to `canvas-board`, keyed on `canon:canvas` and `skills/canvas` because a bare `canvas` key would rewrite the verb, its source folder, and its record folder. It leaves the pointer answering under the fold skill's old name in place. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then. <!-- canon-keep-retired -->
 
 `migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
 

package/docs/agents/pr-evidence-layout.md

@@ -0,0 +1,70 @@
+---
+title: The pull request evidence layout
+description: How canon pr evidence groups screenshots into one block per view with a row per width and a column per theme, when a base column appears, where a name outside the form lands, how the commit line links, and when the blocks open
+---
+
+# The pull request evidence layout
+
+`canon pr evidence` renders the screenshots of a pull request as blocks a
+reviewer reads by view. The record behind them, and the reasons a run can
+refuse, are in `canon docs pr-evidence`.
+
+## One block per view
+
+A case name that ends in `-dark-<width>` or `-light-<width>` belongs to the
+view named by everything before that suffix, so `menu-open-light-1440` is the
+`menu-open` view. The name is split from the right because a view may carry
+hyphens of its own.
+
+Each view is one `<details>` block. Its summary carries the view and its case
+count, a row holds one width in ascending number order, and a column holds one
+theme:
+
+```markdown
+| Width | Dark | Light |
+```
+
+A view with any case already at the base takes a base and a head column per
+theme, and a case the pull request added shows `*(new)*` in its base cell:
+
+```markdown
+| Width | Dark base | Dark head | Light base | Light head |
+```
+
+A cell with no case in it stays empty. A theme no case of the view carries has
+no column. A state under a named directory titles its blocks
+`<state> / <view>`, so two states holding one view never repeat a name.
+
+## Names outside the form
+
+A case name that does not split into a view, a theme, and a width lands in a
+flat `Case | Base | Head` block for its state, or `Case | Head` when every case
+in it is new. Nothing is dropped, so `board.png` or a name with no width still
+shows.
+
+## The commit line
+
+Under `## Evidence`, the Base and Head line names each commit as a short sha
+that links to the full commit:
+
+```markdown
+**Base:** [`<base>`](https://github.com/<repo>/commit/<base-sha>) · **Head:** [`<head>`](https://github.com/<repo>/commit/<head-sha>)
+```
+
+A reader opens what the screenshots were taken against in one click. The base
+is the merge base the compare endpoint returns, not trunk's tip.
+
+## When the blocks open
+
+Every block opens while the comment carries six images or fewer, counting one
+per case for the head plus one per case that is not new. Past that every block
+closes, so the whole comment is open or closed together.
+
+## What reads the body back
+
+The case count that `would-empty` compares is the number of head images in the
+body. It holds for the grouped rows, where one row carries up to two cases, and
+for every layout posted before, so a comment rendered under an older shape
+still counts. The bold `**Base:**` label and the `<details>` blocks are
+unchanged, which keeps the address reader and the review skills working on both
+layouts. An older comment keeps its shape until the next run edits it in place.

package/docs/agents/pr-evidence.md

@@ -41,8 +41,9 @@ The record groups every evidence path by state, the remainder of its
 directory under the `evidence/` segment, and within a state by filename stem,
 so a `before/hero.png` and an `after/hero.png` naming the same case group as
 one entry, not two files. Each entry carries whether it existed at the base
-commit, so the comment shows a base image or marks it new. All-new states drop
-the Base column and each `<img>` takes its PNG width, at most 1000.
+commit, so the comment shows a base image or marks it new. Each `<img>` takes
+its PNG width, at most 1000. `canon docs pr-evidence-layout` covers how the body
+groups those entries by view.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
@@ -152,7 +153,7 @@ whichever previews apply, joined by a middle dot:
 
 **Preview:** <url> · **Local preview:** <url>
 
-**Base:** `<base>` · **Head:** `<head>`
+**Base:** [`<base>`](<base-commit-url>) · **Head:** [`<head>`](<head-commit-url>)
 ```
 
 The Base and Head line follows only when the comment carries screenshots.
@@ -258,12 +259,10 @@ the caller, and lifts only on `settled`, so a refusal holds it the same as
 
 ## When the comment opens
 
-The comment opens every state while it carries six images or fewer, counting one
-per row for the head plus one per row that is not new, and closes every state
-past that, so the whole comment is open or closed together. A line under
-`## Evidence` names the compared base and head as short shas, which tells a
-reader whether the images match the latest push. The base is the merge base the
-compare endpoint returns, not trunk's tip.
+The comment opens every block while it carries six images or fewer and closes
+every block past that. A line under `## Evidence` names the compared base and
+head as linked short shas, which tells a reader whether the images match the
+latest push. `canon docs pr-evidence-layout` covers the count and the blocks.
 
 ## What the comment still leaves to GitHub
 

package/docs/agents/pr-frames.md

@@ -12,6 +12,7 @@ the `canon-frames` branch and returns a link to its path there.
 
 ```bash
 canon pr frames 1341 --add frames/3.png --box 3 --head <sha> --pass 20261002T154450Z --json
+canon pr frames 1341 --add frames/3-dark.png --box 3 --theme dark --head <sha> --pass 20261002T154450Z --json
 canon pr frames 1341 --drop --json
 canon pr frames --prune 30 --json
 ```
@@ -23,7 +24,10 @@ through the GitHub git data API, being blobs, trees, commits, and that one ref,
 so nothing is checked out, no worktree is entered, and neither `main` nor any
 branch a pull request holds is touched. The branch never merges.
 
-A frame lands at `pr-<number>/<short-head>/<pass>/box-<n>.png`. `--head` names
+A frame lands at `pr-<number>/<short-head>/<pass>/box-<n>.png`, or at
+`box-<n>-<theme>.png` when `--theme` names `dark` or `light`, so two shots of
+one box in one pass never take the same path. A frame without `--theme` keeps
+the plain form. `--head` names
 the commit the pass drove, 7 to 40 lowercase hex characters, and defaults to
 the head the pull request object reports. `--pass` is the instant the pass
 started, in compact UTC as `date -u +%Y%m%dT%H%M%SZ` prints it, which
@@ -59,6 +63,7 @@ be published with it.
 | `bad-box`          | `--add` carried no positive `--box`.                                             |
 | `bad-head`         | `--head`, or the head the pull request reported, is not a 7 to 40 character sha. |
 | `bad-pass`         | `--add` carried no `--pass` stamp in compact UTC.                                |
+| `bad-theme`        | `--theme` is neither `dark` nor `light`, or came without `--add`.                |
 | `bad-days`         | `--prune` carried no positive number of days.                                    |
 | `unreadable-frame` | The `--add` file is missing, empty, or not a PNG. Nothing is called.             |
 | `read-only`        | GitHub refused a write with 403 or 404, which is what a fork's token gets.       |
@@ -69,7 +74,7 @@ be published with it.
 | `gh-missing`       | `gh` is not on the path.                                                         |
 | `gh-failed`        | `gh` could not name the repository or read the pull request.                     |
 
-An add's `ok` record carries `link`, `commit`, `path`, `box`, `head`, `pass`,
+An add's `ok` record carries `link`, `commit`, `path`, `box`, `theme` when one was passed, `head`, `pass`,
 and `created`, which is true when the add made the branch. A drop's carries
 `removed`, the pull requests whose folders went, plus `commit` for the rewrite
 or `deleted` when it emptied the branch. A prune adds `kept` and `unread`.

package/docs/agents/pr-lift.md

@@ -0,0 +1,132 @@
+---
+title: The pull request draft lift
+description: How canon pr lift removes the draft mark once the reviews, evidence, standing, and CI all read clear at the head, the gate order and what each reads, the wait on a pending run, the re-read before the write, the refusal reasons it names, and what --check reports
+---
+
+# The pull request draft lift
+
+`canon pr lift` takes a pull request out of draft. It reads the gate itself, so
+any session that closes a review can run it, and nobody has to judge whether a
+message asking for the lift came from someone entitled to ask.
+
+```bash
+canon pr lift 1341 --json
+canon pr lift 1341 --check --json
+```
+
+With no number it resolves the one open pull request on the checked-out branch.
+The ship chain marks every pull request a draft, and this is the verb that
+undoes it.
+
+## What it reads
+
+Five gates, read in this order. The first four need no wait, so they all run
+before the check runs are read.
+
+| Gate       | Clear when                                                                                    |
+| ---------- | --------------------------------------------------------------------------------------------- |
+| `review`   | The newest `## Review` pass is closed, and its marker names the head.                         |
+| `ui`       | The newest `## UI review` verdict is closed at the head. Binds only where a checklist exists. |
+| `evidence` | `canon pr evidence --check` reads `settled`, meaning no post-pull-request step is owed.       |
+| `standing` | The head merges into the freshly fetched base, and the base moved no path the branch writes.  |
+| `ci`       | Every check run on the branch tip concluded and none failed.                                  |
+
+The head is the branch tip read from the remote, not the pull request object's
+head, which trails a push by up to a minute. A review marker names the commit
+the reviewer read, and it covers the head when it is that commit or a prefix of
+it.
+
+The UI gate binds only when `canon pr evidence --check --json` carries a
+`checklist` field. The verb branches on that field and not on the exit, so a
+branch with no rendered surface owes no UI review.
+
+A review pass with no read-time marker refuses as `review-unmarked`. Its covered
+commit would be the stamp GitHub wrote at submission, which the marker exists to
+replace, and lifting on it reintroduces the defect `canon pr review-state`
+documents.
+
+## The wait
+
+A pending CI run is waited on rather than refused. `--wait <seconds>` bounds it,
+defaulting to 1200, and the check runs are read every 30 seconds until one of
+four things happens:
+
+- every run passed, and the verb goes on to the write
+- a run failed, which refuses `ci-failing` at once
+- the branch conflicts with its base, which refuses `ci-conflicted` at once,
+  since no run starts for a conflicted branch and the wait could not end
+- the deadline passed, which refuses `ci-timeout`
+
+A refusal on any of the first four gates comes before the wait starts. A code
+reviewer whose UI partner is still driving refuses `ui-open` immediately
+instead of holding a turn through a CI run.
+
+## The re-read
+
+A push during the wait moves the head off the commit every earlier gate
+cleared. After the wait, and immediately before the write, the verb reads the
+pull request, the branch tip, and the reviews again. A tip that moved refuses
+`head-moved`, and a review that opened refuses with its own reason. The
+standing is read again as well, so a sibling merging during the wait refuses
+`standing-stale` instead of lifting a branch that read fresh before it. A pull
+request already out of draft by then reports `already-ready`.
+
+Two reviewers closing within seconds of each other can each read the other's
+review as still open and both refuse. The re-read narrows that window and does
+not close it, so a draft whose reviews both read closed is the controlling
+session's to lift.
+
+## The write
+
+The lift is the `markPullRequestReadyForReview` GraphQL mutation, because the
+REST pull request update carries no draft field. It is the one GraphQL call the
+verb makes, and every read stays on REST. The verb reads `isDraft` back from the
+mutation's answer, and a response that does not say `false` refuses `gh-failed`
+rather than reporting a lift.
+
+A cloud session's proxy refuses GraphQL, so a reviewer running there reaches
+`gh-failed` on the write and hands the lift to the controlling session.
+
+## What it reports
+
+`reason` on the record is what a caller branches on. Exit 0 covers `lifted` and
+`already-ready`, so the second of two reviewers to close owes nobody a message.
+Every other reason exits 1.
+
+| Reason              | What it means                                                          |
+| ------------------- | ---------------------------------------------------------------------- |
+| `lifted`            | The mark came off.                                                     |
+| `already-ready`     | The pull request was not a draft. Nothing is written.                  |
+| `clear`             | Under `--check`, every gate reads clear.                               |
+| `pull-closed`       | The pull request is closed.                                            |
+| `review-missing`    | The thread carries no code review.                                     |
+| `review-open`       | The newest code review is open.                                        |
+| `review-unmarked`   | The newest code review carries no marker.                              |
+| `review-behind`     | The newest code review closed on an earlier commit than the head.      |
+| `ui-missing`        | A checklist exists and no UI review has been posted.                   |
+| `ui-open`           | The newest UI review is open.                                          |
+| `ui-unmarked`       | The newest UI review carries no head marker.                           |
+| `ui-behind`         | The newest UI review closed on an earlier commit than the head.        |
+| `evidence-owed`     | The evidence check reads `owed`.                                       |
+| `standing-stale`    | The base moved under a path the branch writes.                         |
+| `standing-conflict` | The head does not merge cleanly into the base.                         |
+| `standing-unknown`  | The head or base did not resolve, which a fork or deleted head leaves. |
+| `ci-pending`        | Under `--check`, a run has yet to conclude.                            |
+| `ci-failing`        | A check run failed.                                                    |
+| `ci-conflicted`     | The branch conflicts, so no run will start.                            |
+| `ci-timeout`        | A run was still pending when `--wait` ran out.                         |
+| `head-moved`        | A push landed during the wait.                                         |
+| `gh-failed`         | A read or the write was refused, so nothing is reported as lifted.     |
+
+`standing-unknown` waits on a person, matching the orchestrator poll's own rule
+for a head it cannot resolve.
+
+## `--check`
+
+`--check` reports every gate and writes nothing. It reads the check runs once
+and does not wait, so a pending run reports `ci-pending`. The record carries a
+`gates` array with each gate's name, whether it is clear, and its reason, so a
+caller sees every gate that blocks and not the first alone.
+
+The orchestrator's poll and a session deciding whether to run the verb read the
+same answer this way, rather than each restating the gate.

package/docs/agents/records-push.md

@@ -31,7 +31,7 @@ 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.
+Point it at a private repository, and at one that is not a remote of the project. Records carry the plans, 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
 
@@ -58,4 +58,4 @@ The two `pull` refusals exist because the directions are not symmetric. A push o
 
 ## When it runs
 
-`canon hooks post-merge`, which `.husky/post-merge` calls, runs `push` after the task archiving, 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 verb exits zero whatever the push answers, so an unreachable remote neither aborts the hook nor delays the archiving before it, and a checkout that never ran the setup reports nothing. `hooks.md` covers the verb. Anything the hook misses is covered by running the verb by hand.
+`canon hooks post-merge`, which `.husky/post-merge` calls, runs `push` after the task archiving, on every merge rather than only on one that archived a task. A review report and a plan edit both land on runs that close nothing. The verb exits zero whatever the push answers, so an unreachable remote neither aborts the hook nor delays the archiving before it, and a checkout that never ran the setup reports nothing. `hooks.md` covers the verb. Anything the hook misses is covered by running the verb by hand.

package/docs/agents/records-stale.md

@@ -1,64 +1,31 @@
 ---
 title: Records stale
-description: Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, counting the releases since the requirements record was last reviewed, and the exit codes and refusals
+description: Counting the releases since the requirements record was last reviewed, where the review date is read from, and the exit codes and refusals
 ---
 
 # Records stale
 
-`canon records stale memory` reports each memory entry's review state and every backticked path it cites that the project no longer holds. It answers what a review of the pen should read next, so a skill takes the queue from the verb rather than re-deriving it by grep. `canon records stale canonical` reports when the requirements record was last reviewed and how many releases have shipped since.
+`canon records stale canonical` reports when the requirements record was last reviewed and how many releases have shipped since. A skill takes the count from the verb rather than re-deriving it from the tag list.
 
 ```bash
-canon records stale memory
-canon records stale memory --json
-canon records stale memory --days 60 --json
+canon records stale canonical
 canon records stale canonical --json
 ```
 
-| Option          | Behavior                                                                                            |
-| --------------- | --------------------------------------------------------------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout                                                             |
-| `--days <n>`    | Days after a review before a memory entry is due again (default 30)                                 |
-| `--root <path>` | Project root, defaulting to the main worktree for `memory` and the current worktree for `canonical` |
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout                           |
+| `--root <path>` | Project root, defaulting to the current worktree rather than main |
 
-`memory` and `canonical` are the two kinds it reads, since each is a record carrying a review date. Any other argument refuses as `unknown-kind`.
+`canonical` is the one kind it reads. Any other argument refuses as `unknown-kind`, including `memory`, which the verb read until the memory pen retired.
 
-It reports and never writes. It moves, archives, and rewrites no entry, matching `validate` and `size`.
-
-## What makes an entry due
-
-An entry is due when its frontmatter carries no `reviewed` date, or one older than `--days`. The field is optional, and a review that keeps an entry is what writes it. A `reviewed` value that is not a `YYYY-MM-DD` calendar date reads as never reviewed, and the record carries the raw value as `invalidReviewed` so a review can see it rather than the verb throwing over one hand edit.
-
-The field is read off the raw frontmatter block rather than a parsed value, since a YAML parser resolves a bare date to a date object on one schema and a string on another.
-
-## Cited paths
-
-A cited path is a backticked token holding a `/` and ending in a file extension. A trailing `:12`, `:12-20`, or `#heading` anchor is stripped before the test, since otherwise every line citation reads as missing. The path resolves against the project root and never against the entry's own folder, because an entry cites the tree it was written about.
-
-Tokens that look like paths and cite nothing in the tree are never reported:
-
-- Anything under `.canon/`, the scratch folder, or `.claude/worktrees/`, which no tree commits
-- A placeholder or glob holding `<`, `*`, or `{`, a variable holding `$`, and a path elided with `...`
-- A URL, an absolute path, a home path, and a path opening with `../`
-
-A missing path is a proxy for an entry the tree has moved under, not a verdict. It misses a rule the tree now contradicts in prose, and in a target project it flags a toolkit path the target never held. The review judges each one rather than retiring on the flag alone.
-
-## Order
-
-The pen is read at its top level alone. `review/` holds receipts, `archive/` holds retirements, and `index.md` is the generated catalog, so none is an entry a review would queue.
-
-Entries come back due first. Among the due entries, one citing a missing path leads, then the longest unreviewed, with a never-reviewed entry ahead of any dated one, then by name so two runs over one pen agree. A caller takes the first N as a batch:
-
-```bash
-canon records stale memory --json | jq -r '[.entries[] | select(.due)][0:20][] | .name'
-```
-
-The record carries `total`, `due`, `days`, the `folder` read relative to the root, and one `entries` row per entry with `name`, `category`, `reviewed`, `due`, and `unresolved`.
+It reports and never writes, matching `validate` and `size`.
 
 ## Canonical records
 
 `canonical` reads `REQUIREMENTS.md` at whichever surface root carries it, `canon/` ahead of `.claude/`, and omits it when the project does not hold one. It is tracked, so `--root` defaults to the worktree the caller stands in rather than the main one, and a stamp a branch just wrote reads back from that branch.
 
-The review point is an optional `reviewed: YYYY-MM-DD` frontmatter field, set by whoever finishes a review, per `canon standards requirements`. It is a date rather than a commit, since a commit written on a feature branch never reaches a trunk that squash-merges. The field is read the way the memory field is, so a value that is not a calendar date comes back as `invalidReviewed`.
+The review point is an optional `reviewed: YYYY-MM-DD` frontmatter field, set by whoever finishes a review, per `canon standards requirements`. It is a date rather than a commit, since a commit written on a feature branch never reaches a trunk that squash-merges. The field is read off the raw frontmatter block rather than a parsed value, since a YAML parser resolves a bare date to a date object on one schema and a string on another. A value that is not a calendar date reads as never reviewed, and the record carries the raw value as `invalidReviewed` so a review can see it rather than the verb throwing over one hand edit.
 
 The count is every release tag merged into `HEAD` whose creator date falls after the reviewed day. A release tag ends in a dotted version, bare as `v5.25.0` or behind a component prefix as `canon-v2.1.0`, so an eval, deploy, or snapshot tag on the trunk never inflates it. A lightweight tag's creator date is its commit's date and an annotated tag's is the tagging date, so a project mixing both counts by two clocks.
 
@@ -68,8 +35,6 @@ It gates nothing, and no hook, gate stage, or workflow runs it. `canon:document-
 
 ## Exit codes and refusals
 
-Exit codes: `0` the reading completed, whatever it found, and `1` refused. A due entry is a queue position rather than a failure, so nothing here gates.
-
-A `reason` field carries which gate fired: `no-folder` when the project holds no memory folder at either record root, `unknown-kind` for any kind but `memory` or `canonical`, `bad-days` when `--days` is not a positive whole number or is passed to `canonical`, and `unreadable-tags` when `canonical` cannot read the tags. An empty pen is not a refusal. It reports an empty list and exits `0`.
+Exit codes: `0` the reading completed, whatever it found, and `1` refused. A release count is a prompt for the review to judge rather than a failure, so nothing here gates.
 
-The pen is shared scratch at the main worktree root, so `--root` defaults there, the same default `validate memory` takes. A pen at the legacy `.claude/memory/` root resolves the way every record verb resolves it, per `records.md`. <!-- canon-keep-record-root -->
+A `reason` field carries which gate fired: `unknown-kind` for any kind but `canonical`, and `unreadable-tags` when the tags cannot be read.