@erclx/canon 5.33.0 → 5.35.0

package/docs/agents/drift-surfaces.md

@@ -50,23 +50,19 @@ seed tree rather than from a fixed set of filenames, so a folder added later is
 covered without a code change. Only an exact stem matches, which leaves a
 suffixed variant such as `TASKS-ARCHIVE.md` unreported.
 
-No skill splits the file. The standard governing `replacedBy` is the one the
-`appliesTo` the standards catalog declares, and `canon standards <name>` reads
-its destination shape, so the split is the project's own to make.
+No skill splits the file. The destination's shape lives in the skill that owns
+it, so the split is the project's own to make.
 
 `unmigrated` names a domain sitting at the root layout an older toolkit installed
 to, with nothing at the path the current one reads. It carries `rootPath`,
-`installPath`, and a file count. Without it a project holding `standards/` at its
+`installPath`, and a file count. Without it a project holding an older layout at its
 root reports zero entries for that domain and reads as clean, which is the most
 misleading state the report can produce.
 
-The field currently names no domain. Standards and snippets are the two the
-toolkit ever installed at a project root. Standards closed its install channel
-and snippets retired outright, so a project still holding a root `standards/`
-folder is carrying its own authoring surface rather than an unfinished install.
-Nothing proposes moving it, and no command relocates the content. Move it
-yourself. A leftover `snippets/` folder reports under the reverse walk instead,
-where `docs/target/sync.md` says what to do with it.
+The field currently names no domain. Snippets was the one the toolkit ever
+installed at a project root, and it retired outright. A leftover `snippets/`
+folder reports under the reverse walk instead, where `docs/target/sync.md` says
+what to do with it.
 
 `unmovedSurfaces` names a tracked surface the target still holds at its `.claude/`
 spelling with nothing at the `canon/` one, such as `.claude/REQUIREMENTS.md` or
@@ -123,14 +119,14 @@ that is not a full clone as unmeasured rather than clean. This gap does not
 reach the chain-based read above, since it consults no anchor at all.
 
 In the fallback, entitlement is filtered, because a stack does not receive
-every rule. The base stack takes four folders whole, the code stacks add `code`, and
-every other stack extends them with individually named rules, so an unfiltered
-list would tell a base consumer about rules it can never receive and train the
-reader to skip the section.
-
-The filter accepts a band on either of two grounds. A folder the base stack takes
-whole is entitled to every target, read from the stack file so a folder added to
-base later needs no code change. Every other band is read off the folders the
+every rule. The base stack names ten rules, the language stacks add `code` and
+their own language and testing rules, and every other rule is opt-in, so an
+unfiltered list would tell a base consumer about rules it can never receive and
+train the reader to skip the section.
+
+The filter accepts a band on either of two grounds. A folder holding a rule the
+base stack resolves to is entitled to every target, read through the stack file so
+a rule added to base later needs no code change. Every other band is read off the folders the
 target already carries, which is the fallback's only evidence of what a target
 was entitled to before it recorded a chain. One band can be reached by more than
 one stack, so the test over-reports inside a folder the target holds, which

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,6 +23,7 @@ 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
@@ -34,19 +35,21 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [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): 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 validate](records-validate.md): Validating the session records, the per-kind checks, which root they default to, the exit codes, and the refusal reasons
 - [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
+- [Rule citations](rule-citations.md): Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the two 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 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
@@ -54,7 +57,6 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Skill audit](skills-audit.md): Measuring both skill corpora against the skill standards, 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
 - [Slides](slides.md): Where a deck folder lives and what it holds, what it declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
-- [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
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [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

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

@@ -27,15 +27,15 @@ 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 rule that only routed a path to a standard ships under that standard's name,
-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 rule that only routed a path to a standard now names the skill that owns
+the guidance. 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 names
+the `markdown-craft` skill, and `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
+the `create-rule` skill's reference reserves `900-999` for them, and a rule placed under
 `canon/` instead is lost on the next sync.
 
 A sync never deletes a rule that a newer canon release installed. The stamp
@@ -86,12 +86,6 @@ from an anchor a later sync could advance past the rule's own commit. A
 target whose install predates the recorded chain falls back to the same
 band-inference `newRules` uses in `canon sync --check`.
 
-There is no `canon standards sync` and no `canon standards install`. The corpus
-installs into no project, so the domain has nothing in a target to reconcile.
-`canon standards <name>` prints one, resolving `standards/` at the working root
-and then the corpus inside the package, and `canon standards list --json` carries
-the catalog, each entry labeled by the root it was read from.
-
 ## Tooling diff and sync
 
 `canon tooling diff <stack> [target]` is the read-only comparison, and a session asking what differs reaches for it by default. It writes nothing and exits 1 when anything differs and 0 when nothing does, so it gates CI. `--json` adds the scan record on stdout with `ok: true`, and the frame goes to stderr. A refusal such as an unknown stack, an excluded stack, or a toolkit-root target still exits 1 and answers `{ ok: false, reason, message }`, so a caller branches on the record and reads a typo'd stack name as a refusal rather than as drift.
@@ -112,6 +106,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.
@@ -125,23 +123,6 @@ Claude Code loads both copies of an edited rule at session start. Run `canon
 migrate rule-layout` first to move a target off the flat layout, which reports
 what it would move and applies it under `--write`.
 
-## Standards resolution
-
-`canon standards <name>` writes the document to stdout and the root it answered
-from to stderr, so a caller capturing with `$(...)` receives the document alone.
-A name resolves with or without its `.md` extension, and one that matches no
-standard exits 1 after listing the catalog on stderr.
-
-Two roots answer, in order: `standards/` at the working directory, then the
-corpus inside the package. A project that authors standards of its own uses the
-first, and this repository's own authoring root is the same path. `.claude/standards/`
-is not among them, and no repository writes one any more. A copy an older
-toolkit installed into a target resolves nothing.
-
-There is no citation closure to compute, since nothing is copied. A standard
-that hands a concern to a sibling names it in `Does not govern:` and a reader
-runs the verb again for that name.
-
 ## Governance regen
 
 `canon gov regen` is the one governance verb that runs against the toolkit root,
@@ -254,7 +235,6 @@ still prompts. `--skip` takes `wiki`, `governance`, and `records`, and warns
 without aborting on any other value. Records has nothing to run non-interactively,
 since the private backup repository does not exist yet at scaffold time, so its
 step only prints the one-time setup reminder and `--skip records` silences it.
-There is no `--standards`, since no run writes that corpus into the target.
 
 ## Unguarded tooling primitives
 

package/docs/agents/markdown-audit.md

@@ -5,14 +5,14 @@ description: Running the audit over any markdown path, where its bans and checkp
 
 # Markdown audit
 
-`canon markdown audit [path...]` reports any markdown file against the attribute standard `markdown.md`. An attribute standard governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/` and `governance/` in reach. Folder-shaped findings stay in `canon context audit`, described in `context-audit.md`.
+`canon markdown audit [path...]` reports any markdown file against the `markdown-craft` skill's `markdown.md` reference. That reference governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/` and `governance/` in reach. Folder-shaped findings stay in `canon context audit`, described in `context-audit.md`.
 
 ```bash
 canon markdown audit
 canon markdown audit --json
 canon markdown audit .claude/rules governance
 canon markdown audit docs/agents/commands.md
-canon markdown audit 'standards/**/*.md'
+canon markdown audit 'docs/**/*.md'
 ```
 
 | Option   | Behavior                                                   |
@@ -27,29 +27,27 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 ## Where the rules come from
 
-The ban set and all ten checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same set whether or not it installed any standards, and no file has to resolve for a run to mean something.
+The ban set and all ten checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same set whether or not it installed the plugin, and no file has to resolve for a run to mean something.
 
 Seven of the ten are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
 
-Reading them out of the standards per run was the original design. It put a parser contract on a document authored for people, and the standard had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
+Reading them out of the reference per run was the original design. It put a parser contract on a document authored for people, and the reference had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
 
 `markdown.md` still states every ban and every checkpoint, and a reader follows it rather than the code. Nothing compares the two, so a number moved in one place and left in the other drifts silently. Move both in the same change.
 
-The set is closed rather than extensible, so a project cannot add a term by editing a file. It holds the two characters alone, since a character is the one class a literal match settles. The set once carried 13 words and 6 British spellings as well. The words moved to the `write-human` skill as guidance, because a word ban catches the token and misses the habit, and `just`, `allows`, and `very` carry honest uses no literal match separates. Spelling went to a project's spell checker, which already reads every word.
+The set is closed rather than extensible, so a project cannot add a term by editing a file. It holds the two characters alone, since a character is the one class a literal match settles. The set once carried 13 words and 6 British spellings as well. The words moved to the `write-human` skill as guidance, because a word ban catches the token and misses the habit, and `just`, `allows`, and `very` carry honest uses no literal match separates. Spelling is left to the author, with American spelling carried as guidance in `markdown-craft`.
 
 A set shipped empty is reported rather than passed. It finds nothing and would exit clean, which reports a corpus nobody checked as a corpus carrying no violation, so the run names the empty set and exits `3`. The set ships with the package, so a defect in the build is the only cause left.
 
-`canon standards <name>` still resolves a standard at the authoring root, then the package corpus, and prints it, so the human catalog reads without a project copy on disk.
-
 ## What each check reports
 
 ### Bans
 
 One closed set reports a hit: the characters `markdown.md` bans under `## Punctuation`.
 
-Frontmatter, fenced blocks, inline code spans, and link destinations are excluded. Without the code-span exclusion each standard would report its own backticked examples, and without the link exclusion a semicolon in a query string would report as prose no rewrite can fix.
+Frontmatter, fenced blocks, inline code spans, and link destinations are excluded. Without the code-span exclusion each reference would report its own backticked examples, and without the link exclusion a semicolon in a query string would report as prose no rewrite can fix.
 
-Word choice stays unmeasured and the report says so on every run. Single words travel in the `write-human` skill as guidance a reader applies. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim are patterns of the multi-word kind by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole standard.
+Word choice stays unmeasured and the report says so on every run. Single words travel in the `write-human` skill as guidance a reader applies. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim are patterns of the multi-word kind by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole reference.
 
 ### Links
 
@@ -103,14 +101,14 @@ Both hooks answer an absent record as well. A completed run always writes the re
 
 A machine with neither runner still blocks no edit, and it says so rather than exiting clean. The push stage holds either way. An edit nobody checked and an edit carrying no violation are one silence to a reader, so the enforcement a machine lacks is reported rather than inferred.
 
-The stage measures the whole corpus rather than the changed files. A `Do not use` bullet added to a standard bans a token retroactively, and no file in the push that adds the bullet was edited.
+The stage measures the whole corpus rather than the changed files. A `Do not use` bullet added to a reference bans a token retroactively, and no file in the push that adds the bullet was edited.
 
 ## What it does not cover
 
-The verb reads the two attribute standards and nothing else. The five standards declaring `appliesTo: ["*"]` also include `publish.md`, `slug.md`, and `versioning.md`, none of which this implements.
+The verb reads the `markdown-craft` skill's reference and the `write-human` cadence numbers and nothing else. The references the `git-pr`, `git-branch`, and `git-commit` skills own, `publish.md`, `slug.md`, and `versioning.md`, govern an attribute of other artifacts, and none of them is implemented here.
 
 `publish.md` describes a scan applying the same punctuation bans to finished text on its way out. No code implemented that scan before this command, so nothing is duplicated, and a later surface should call this verb rather than build a second one.
 
-That standard's cross-reference rule is out of reach rather than merely unimplemented. It resolves by destination, bare where the destination auto-links a pull request or issue number and backticked where it does not, so this verb sees only the half where the backticked form is correct. A check here would report every compliant reference in the tree and reach none of the published text that goes wrong, which is why the rule holds on reading alone.
+That reference's cross-reference rule is out of reach rather than merely unimplemented. It resolves by destination, bare where the destination auto-links a pull request or issue number and backticked where it does not, so this verb sees only the half where the backticked form is correct. A check here would report every compliant reference in the tree and reach none of the published text that goes wrong, which is why the rule holds on reading alone.
 
 The list-density rule at `claude/skills/markdown-craft/references/markdown.md` is out of scope on purpose, since it carries no number and what a density figure should measure is still open.

package/docs/agents/migrate.md

@@ -25,7 +25,7 @@ Every citation in scope is reported with its file, its line number, and the line
 
 `migrate rule-layout` moves a target still on the flat installed-rule layout onto the `canon/`-wrapped one. It classifies each flat file against the target's own recorded stamp: an unchanged hash is clean, a changed one is edited, and a name neither the stamp nor the current rule catalog can vouch for is unclaimed and left in place. Clean and edited files both relocate with their content untouched, since moving a rule is a different decision from re-syncing it. The one renumbered rule reads its destination from a table rather than from its own current name, so it never lands as a second copy under the retired number.
 
-`migrate scratch-evidence` moves a folder out of `.tmp/` for good rather than repointing a citation in place. A promoted folder is one a durable record, live or archived, cites as its evidence, and no source file under `claude/`, `scripts/`, `src/`, `governance/`, or `standards/` names by path, which is what a script still writing into it fails. It walks every `canon records push` folder rather than the live ones alone, since most of what it repoints sits in `tasks/archive/`, `plans/archive/`, and `groundwork/`. A destination already occupied is a refusal, and a second run rewriting nothing is the same idempotence check `migrate record-tree` uses.
+`migrate scratch-evidence` moves a folder out of `.tmp/` for good rather than repointing a citation in place. A promoted folder is one a durable record, live or archived, cites as its evidence, and no source file under `claude/`, `scripts/`, `src/`, or `governance/` names by path, which is what a script still writing into it fails. It walks every `canon records push` folder rather than the live ones alone, since most of what it repoints sits in `tasks/archive/`, `plans/archive/`, and `groundwork/`. A destination already occupied is a refusal, and a second run rewriting nothing is the same idempotence check `migrate record-tree` uses.
 
 A destination that already holds the same bytes marks the flat file a duplicate, which `--write` deletes rather than moves. One holding different bytes is a real collision: neither file is touched, it is reported by name, and every other planned move still applies independently. Run this before `canon gov install` or `canon gov sync` against a target still on the flat layout, since neither bootstrap verb detects or clears it on its own.
 

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-stale.md

@@ -25,7 +25,7 @@ It reports and never writes, matching `validate` and `size`.
 
 `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 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 review point is an optional `reviewed: YYYY-MM-DD` frontmatter field, set by whoever finishes a review, per `claude/skills/draft-doc/references/requirements.md`. 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.