@erclx/canon 5.33.0 → 5.34.0

package/claude/skills/target-setup/references/detect.md

@@ -80,7 +80,8 @@ root.
 - **Stack:** pick the closest governance stack by matching the repository root's detected runtime or framework against stack names in the catalog. If the root matched nothing, `base` is the stack, including when subfolders matched, since no subfolder owns the repository and picking one by order would state a preference nobody gave. Mark it `fallback` in the preview only when no root matched anywhere.
 - **Tooling stack:** for each language root, pick the closest tooling stack from `canon tooling list --json` (e.g. `vite-react`, `astro`, `nextjs`). Distinct from the governance stack. Fall back to `base` for a root with no framework or language match, and carry that fallback into its preview row.
 - **Next.js:** map `next` in a root's `package.json` dependencies, or a `next.config.ts`/`.js`/`.mjs` file in that root, to the `nextjs` governance stack and the `nextjs` tooling stack. The dependency name does not match either stack name by itself.
-- **Extras:** identify technologies not already covered by the picked governance stack, across every language root. A subfolder that matched a governance stack of its own contributes that stack's rules, read from `canon gov list --json`, and every root contributes its language rule. For each technology, find a rule whose `description` or `paths` points at it and pass it via `--add`. Dedupe against the picked stack's own rules. Do not add a rule the stack already pulls in.
+- **Extras:** run `canon gov detect <target> --stack <stack> --json` from the target and take its `proposals` array as the candidate extras. Each proposal names a `rule` and the `evidence` that matched it across every language root to depth two. The verb already leaves out every rule the picked stack resolves, so do not dedupe again, and do not match a rule's `description` or `paths` by hand.
+- **Subfolder language rules:** a language root below the repository root whose language the picked stack does not carry contributes its language rule by name, read from `canon gov list --json`. The verb proposes no language rule, since a stack reaches each one.
 - **Subfolder tooling:** a language root below the repository root takes its own `canon tooling sync <stack> <path> --skip base`, since `canon init` already lands `base` once at the root. Leave a root whose stack resolves to `base` out of the commands, since that sync would land nothing. A repository-root `package.json` hosting only formatters and hooks is that case, and it adds no row.
 - **Skip (`--skip`):** `wiki` installs by default. Add `--skip wiki` only when the user explicitly wants it left out.
 
@@ -112,7 +113,7 @@ Before executing, output:
 - **Detected:** each technology with its evidence file, path included, so a subfolder marker reads as one
 - **Stack:** picked governance stack and resolved rule count. Mark it `fallback` when no detected runtime or framework matched a catalog name.
 - **Tooling stack:** one row per language root, each carrying its path, its picked tooling stack, a `fallback` mark on the same test, and its own command. On the repository root's row, name what `base` lands: configs, seeds, and gitignore entries in every case, plus the JavaScript development dependencies, scripts, and hook activation wherever a `package.json` exists to carry them. A project outside that ecosystem runs none of the second group and keeps the first. Omit these rows entirely on the `gov` phase, which syncs no tooling.
-- **Extras:** each `--add` rule with a one-line reason, listed in full. A second matched stack reaches the install only through this list, since `canon init --stack` takes one stack, so a shortened list reads as that stack dropped.
+- **Extras:** each proposal with the evidence the verb returned, plus each subfolder language rule, listed in full as the list the operator confirms. A second matched stack reaches the install only through this list, since `canon init --stack` takes one stack, so a shortened list reads as that stack dropped.
 - **Skip:** any `--skip` entries with reason
 - **Target:** resolved target path
 - **Commands:** the full chain that will run
@@ -120,3 +121,19 @@ Before executing, output:
 A resolved name and a fallback read alike once written, so mark the fallback
 here rather than in the report. The preview is the last point before the first
 write, and the report runs after the files have landed.
+
+### Confirm the extras
+
+The extras are the one part of the preview the operator confirms before the
+install runs, since a proposal is evidence that a project might want a rule
+rather than proof that it does. Put the list through the structured question
+surface with three options: take every proposal, which is the recommended
+first option, take none, or name a subset, which the operator types as a
+comma-separated list. Pass what they kept to `--add` and drop the flag when
+they kept nothing.
+
+An `--extras` argument answers ahead of time and skips the question.
+`--extras <a>,<b>` takes the named rules, and `--extras none` takes none. With
+neither and no one to answer, take every proposal and list each in the report,
+since a proposed rule costs one file to delete and stopping would break every
+headless setup.

package/claude/skills/test-craft/REQUIREMENT.md

@@ -15,7 +15,7 @@ The failure is measured on a real target. A single-page portfolio site carried 2
 
 A stated rule is also one a session can talk itself out of. Each test in that suite sat where it did for a reason that sounded fine at the time, such as the end to end spec already being open or a pause quieting a run that flaked under load, and nothing in front of the session answered the reason.
 
-Moving the guidance into a path-scoped rule does not reach the session that needs it. A path-scoped rule loads when a session reads a matching file and not when it creates one, measured in three headless runs, so a rule scoped to test files is silent on the first test of every feature.
+Moving the guidance into a path-scoped rule does not reach the session that needs it. A path-scoped rule loads when a session reads or writes a matching file, and it is absent from the write that creates the first one, measured in three headless runs, so a rule scoped to test files is silent on the first test of every feature.
 
 ## Must
 
@@ -23,6 +23,7 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 - Open every test with the question of which production change makes it fail and whether that change is a bug or a decision, since a test with no answer proves nothing
 - State the end to end budget in words: journeys and what only a real browser renders, never a state a component test reaches
 - Carry a final filter the session runs over its own tests, each item a shape it can check: mirror assertion, change detector, assertion on a mock, framework behavior, fixed pause, and the mutation check
+- Own the structure floors every test carries, being arrange, act, assert, one behavior per test, no branching or loops in a body, no testing of private functions or internal state, no coverage targets, nesting at most two levels deep, independent tests that clean up, factories for test data, every async call awaited, and no snapshot verification. The testing rule only points here, so a later trim keeps them.
 - Hold in the body what every test decision pays for, and defer each layer's specifics to a reference loaded only when a test at that layer is being written
 - Promise a middle layer for behavior a simulated DOM cannot render, naming the real-browser component runners, so a static site is not left choosing between a simulated DOM that computes no layout and a whole-site run
 - Repeat in the end to end reference the two floors a session writing its first spec never loads through the path-scoped rule, being the `scrollend` settle and motion reduced by default
@@ -34,7 +35,6 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 
 - Name a framework or runner in the body. Runner specifics live in the references and in the language testing rules, so the body holds across stacks.
 - Carry a numeric mix across layers. A codebase-wide ratio is a target a session writing one test cannot act on.
-- Restate the structure floors the testing rule already carries, such as arrange, act, assert, one behavior per test, isolation, and no snapshots
 - Restate the settle, guard, and run-scope rules the end to end rules carry, beyond the two floors named above
 - Run the red, green, refactor procedure or decide its order, which `test-first` owns
 - Import an external skill's tone, such as a law stated as absolute, or an excuse row rebutting an objection no session has raised
@@ -49,7 +49,6 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 
 - The red, green, refactor loop and the order it runs in: `test-first`, which loads this skill at its first step
 - Reproducing a failure with no known cause: `systematic-debugging`
-- Structure floors for every test: the core testing rule
 - Runner choice, file suffix, placement, and query conventions: the TypeScript and Python testing rules
 - Settle, guard, and run-scope rules inside an end to end file: the end to end reliability and test scope rules
 - Writing a UI change's visual checklist, and naming the behaviors it ships untested for this skill to place: `ui-checklist`

package/claude/skills/test-craft/SKILL.md

@@ -45,10 +45,23 @@ Size a test by what it touches rather than by what it covers. Pick the first row
 
 ## Keep test code readable over clever
 
-- Prefer a descriptive, repeated arrange over a shared helper a reader has to open. A test is read when it fails, by someone who did not write it.
-- Assert through the public surface a caller uses. A test reaching into internals breaks on every refactor and catches nothing a caller sees.
+- Prefer a descriptive, repeated arrange over a shared helper a reader has to open. A test is read when it fails, by someone who did not write it. Build test data through a factory or builder rather than an inline object literal repeated across tests.
+- Assert through the public surface a caller uses, never on a private function or internal state directly. A test reaching into internals breaks on every refactor and catches nothing a caller sees.
 - Prefer a real collaborator, then a fake, then a stub, and a mock last. A mock asserts how the code is built rather than what it does.
 
+## Hold the structure floors
+
+Every test carries these, at any layer and in any runner:
+
+- Structure each test as arrange, act, assert.
+- Verify one behavior per test.
+- Keep conditional logic and loops out of a test body. A table of cases is one test per row, never a branch inside one.
+- Set no coverage percentage as a target. Cover the behaviors and their edges.
+- Group related tests with the framework's nesting mechanism, and keep it to two levels deep.
+- Keep tests independent with no shared side effects. Clean up and restore state after each one.
+- Await every async operation. Never leave a promise fire-and-forget in a test.
+- Verify with assertions, never with a snapshot.
+
 ## Read the reference for the layer
 
 Read the one reference matching the layer the table picked, before writing the first test at it. Skip the other two.
@@ -92,6 +105,5 @@ Run the final filter over every test written this session, checking each line. A
 
 - The red, green, refactor procedure and its order: `test-first`, which loads this skill at its first step
 - Reproducing a failure with no known cause: `systematic-debugging`
-- Test structure floors such as arrange, act, assert, one behavior per test, isolation, and no snapshots: `010-testing`
 - Runner, file suffix, placement, and query conventions per language: `300-testing-ts`, `330-testing-py`, `335-testing-go`, and `336-testing-php`
 - Settle, guard, and run-scope rules inside an end to end file: `305-e2e-reliability` and `306-test-scope`

package/docs/agents/canvas.md

@@ -1,6 +1,6 @@
 ---
 title: Canvas
-description: The canvas server, its content format, and the verbs that list, arrange, select, edit, mark, and capture frames
+description: The canvas server, its content format, and the verbs that list, arrange, fit, select, edit, mark, and capture frames
 ---
 
 # Canvas
@@ -29,6 +29,10 @@ The write routes the shell posts to also refuse a request carrying an `Origin` o
 
 `frame resize <page> <name> --width <px> --height <px>` rewrites one frame's whole box in one write, and `--x` and `--y` move it at the same time. An omitted flag keeps the frame's current value. It refuses a width or height that is not a positive number as `invalid-size`, a position that is not a number as `invalid-position`, and a missing frame, a missing page, or a layout that does not parse as `frame move` does.
 
+`canvas arrange <page>` re-lays a page's frames. It keeps the rows they already sit in, where boxes whose vertical spans overlap share a row, orders each row left to right by `x`, places the boxes on the 80px frame gap from the page's leftmost edge, and stacks the rows on their tallest box plus the gap from the page's top edge. It also drops every layout entry whose frame file is gone. `--check` writes nothing. `--json` emits `{ ok, page, written, moved, dropped }`, where `moved` lists each frame with its `from` and `to` position and `dropped` lists the entries with no file. Sizes never change. Under `--check` it exits 2 when a frame would move or an entry would drop, and it refuses a missing page as `no-page` and a layout that does not parse as `malformed-layout`.
+
+`canvas fit <page>/<frame>` and `canvas fit <page>` set each frame's height to its content. The content is measured in the capture browser at the frame's box width, through the served address, after fonts and the load event settle, and the height is that measure rounded up with no margin. The write goes through the same writer as `frame resize`. `--check` writes nothing. `--json` emits `{ ok, written, frames }`, one row per frame carrying `height`, `fitted`, `wide`, `font`, `viewport`, `family`, and `owed`. `wide` is true when the content is wider than the box, which fit reports and never widens, since the width is the frame's declared render width. `font` is true when the first family of the body text is not one the served sheet declares a face for, being the toolkit faces `Geist Variable`, `Noto Sans Mono`, and the hand-drawn pair, plus any face the project declares, because a height fitted against a machine family may not hold in another browser. `viewport` is true when the frame's height depends on the viewport, as a height in `vh` does. The lowest element edge is read with the viewport at the box height and at twice it, and an edge that moved means the content measure is not the height a viewer draws, so its height is kept and nothing is written for it. Under `--check` it exits 2 when any row is owed, and it refuses as `no-page`, `no-frame`, `no-server`, or `capture-failed` the way `canvas capture` does. Rows below a frame that grew do not move, so run `canvas arrange` after a fit.
+
 The shell writes through the same writer when the operator drags a frame or one of its corner handles. Both take a lock file beside the layout, read it, merge their change, and replace it, so a drag released while a verb writes loses neither position. A writer that cannot get the lock within two seconds refuses with reason `busy`.
 
 `canvas selection --json` emits `{ ok, selection }` with the page, frame, file, box, and path of the frame the operator selected, or `selection: null` when nothing is selected or the selected frame has since been removed. Read it when the operator says "this one".

package/docs/agents/commands.md

@@ -103,7 +103,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `sessions`, in `sessions.md`: `list`, `export`, `import`
 - `worktrees`, in `worktrees.md`: `list`, `reclaim`
 - `hooks`, in `hooks.md`: `post-merge`
-- `pr`, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`, `frames`
+- `pr`, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`, `frames`, `lift` (in `pr-lift.md`)
 - `audits`, in `audits.md`: `run`, `list`
 - `gate`, in `gate.md`: `run`
 - `secrets`, in `state-scoped-risk.md`: `scan`

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,8 +35,10 @@ 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

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

@@ -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.

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/scripting.md

@@ -15,7 +15,8 @@ Use these to discover what's available instead of hardcoding names.
 | --------------------------------- | ---------------------------------------------------------------- |
 | `canon tooling list --json`       | Stacks, extends chain, dep and script counts                     |
 | `canon standards list --json`     | Standards docs and the paths each governs                        |
-| `canon gov list --json`           | Governance stacks, rule sets, and unreferenced rules             |
+| `canon gov list --json`           | Governance stacks, rule sets, evidence, and unreferenced rules   |
+| `canon gov detect --json`         | Opt-in rules a target's dependencies and paths propose           |
 | `canon claude seeds list --json`  | Seed doc sources with content                                    |
 | `canon claude skills list --json` | Plugin skills, descriptions, requirement flag, family vocabulary |
 | `canon docs list --json`          | Consumer docs plus per-domain context                            |

package/docs/target/projects.md

@@ -51,7 +51,7 @@ claude --plugin-dir <toolkit>/claude
 Two steps, in order:
 
 1. Run the framework's own scaffold if the project needs one, such as `bun init`, `npm create vite`, or `npm create astro`. The toolkit does not wrap framework scaffolding.
-2. Invoke `canon:target-setup` in Claude Code. The skill detects the stack, resolves flags, previews the full chain, and runs it end-to-end.
+2. Invoke `canon:target-setup` in Claude Code. The skill detects the stack, asks `canon gov detect` which opt-in rules the project's evidence proposes, previews the full chain with those proposals for you to confirm, and runs it end-to-end.
 
 The chain is:
 
@@ -88,7 +88,7 @@ Escalate only for real web apps. The `target-setup` skill reads `package.json` a
 
 In a monorepo the skill reads each folder holding a `package.json`, `pyproject.toml`, `go.mod`, `composer.json`, or `Cargo.toml` to depth two, skipping what git ignores. Each of those folders gets its own tooling stack and a `canon tooling sync <stack> <folder> --skip base` in the preview. Governance still installs once at the root, since a rule's `paths:` globs reach every subfolder, so a subfolder's language rules join the root install through `--add`.
 
-`node-server` is named rather than detected. It carries the server-side security and persistence rules for a project writing request handlers or a persistence layer in TypeScript, and the detect step matches a runtime or a framework against stack names, so nothing there marks a project as a backend. Pass it deliberately with `canon init --stack node-server` or `canon gov install node-server <target>`.
+`node-server` is named rather than detected. It carries the server-side security and persistence rules for a project writing request handlers or a persistence layer in TypeScript, and the detect step matches a runtime or a framework against stack names, so the stack never resolves on its own. `canon gov detect` proposes its two rules from a server framework or database client in the manifest, which you confirm in the preview. Pass the stack deliberately with `canon init --stack node-server` or `canon gov install node-server <target>`.
 
 Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
 
@@ -113,7 +113,7 @@ The plugin corpus carries runtime behavior rather than reference prose alone, be
 
 When a new need appears after scaffold, install the one domain without re-running `canon init`.
 
-- Governance rule for a newly adopted library: invoke `canon:target-setup gov`, or run `canon gov install <stack> --add <rule> <path>`
+- Governance rule for a newly adopted library: run `canon gov detect <path> --json` to see what the project's evidence proposes, then `canon gov install --add <rule> <path>`, which installs the rule with no stack
 - Project-specific rule the toolkit does not ship: invoke `canon:create-rule`. It scaffolds a rule into `.claude/rules/project/` with a non-colliding number, and `canon gov sync` leaves it untouched. A rule placed under `.claude/rules/canon/` instead is deleted on the next sync, since that folder belongs to the toolkit.
 - Index.md system for a markdown-heavy folder that emerged: invoke `canon:target-setup indexes`