@erclx/canon 5.68.0 → 5.70.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [5.70.0](https://github.com/erclx/canon/compare/v5.69.0...v5.70.0) (2026-10-27)
+
+
+### Features
+
+* **app-drive:** give each drive log finding a heading and fields ([#2791](https://github.com/erclx/canon/issues/2791)) ([f853659](https://github.com/erclx/canon/commit/f853659f5d7793c1af820fcbf55d56fd2f71b981))
+* **brand:** replace the ledger with the ink c and vermilion pip mark ([#2775](https://github.com/erclx/canon/issues/2775)) ([2b7d71e](https://github.com/erclx/canon/commit/2b7d71e329dbaa2ca828dba749ec8c236dc6676b))
+* **design:** land board frames in canon/design through a design sync ([#2792](https://github.com/erclx/canon/issues/2792)) ([b635a33](https://github.com/erclx/canon/commit/b635a33f722a51606b51e1d8539e322233206e39))
+* **design:** land the brand mark sheet as the foundations reference ([#2796](https://github.com/erclx/canon/issues/2796)) ([116caec](https://github.com/erclx/canon/commit/116caec1b233ae58dec8060ada8020381c9722b8))
+* **readme:** open on the mark, claim, launch loop, and install ([#2783](https://github.com/erclx/canon/issues/2783)) ([c86fa26](https://github.com/erclx/canon/commit/c86fa264421cada9ad58c90dd46cf39224330c0f))
+* **sandbox:** read the runner cap from the envelope subtype ([#2794](https://github.com/erclx/canon/issues/2794)) ([4fc750e](https://github.com/erclx/canon/commit/4fc750edc03c302fbfd098c4bf237d745d3124d1))
+* **take:** film drags, key presses, double clicks, and modified clicks ([#2795](https://github.com/erclx/canon/issues/2795)) ([52926e3](https://github.com/erclx/canon/commit/52926e3714a07e13d2efb535c2b8771ea204548d))
+* **take:** name the fallback on a refused beat and add camera controls ([#2789](https://github.com/erclx/canon/issues/2789)) ([6ce5be6](https://github.com/erclx/canon/commit/6ce5be646601274c4b7203527bd6b6cd5e005be8))
+* **ui-craft:** bar the trailing period on every short rendered string ([#2788](https://github.com/erclx/canon/issues/2788)) ([1fc3b4b](https://github.com/erclx/canon/commit/1fc3b4bdd1921a39c21bee225905a138d7422cc5))
+* **ui-film:** add footage guidance for composing takes ([#2793](https://github.com/erclx/canon/issues/2793)) ([dc98a98](https://github.com/erclx/canon/commit/dc98a981bae97921d796e1412a36fb89844e3bba))
+* **web:** rebuild the landing page around one change, plan to merge ([#2787](https://github.com/erclx/canon/issues/2787)) ([c6fdf16](https://github.com/erclx/canon/commit/c6fdf160f7e5140a8066f9370a5703d6d021c2e1))
+
+## [5.69.0](https://github.com/erclx/canon/compare/v5.68.0...v5.69.0) (2026-10-26)
+
+
+### Features
+
+* **app-drive:** keep pasted images as evidence and cite them in plans ([#2757](https://github.com/erclx/canon/issues/2757)) ([89939db](https://github.com/erclx/canon/commit/89939db9be70811f96613a294947efcac2c0ed91))
+* **claude:** retire the plan-ready skill ([#2760](https://github.com/erclx/canon/issues/2760)) ([808806d](https://github.com/erclx/canon/commit/808806d494dee9ae93ef348b1a48e5b50f777871))
+* **governance:** run slow commands in the background by default ([#2762](https://github.com/erclx/canon/issues/2762)) ([ffb86f3](https://github.com/erclx/canon/commit/ffb86f334d9cbd829a329d2576095416f45f0e8f))
+* **gov:** record why each core rule bullet exists in a ledger ([#2769](https://github.com/erclx/canon/issues/2769)) ([f8d4058](https://github.com/erclx/canon/commit/f8d40585f244a58afba0c34a576d52b39e2b93e0))
+* **skills:** draft pick rounds in the board record folder by default ([#2768](https://github.com/erclx/canon/issues/2768)) ([a3cc12a](https://github.com/erclx/canon/commit/a3cc12a80d6a6da60e205be5842f346f81dbe72f))
+* **skills:** draft pick rounds on the design board the project names ([#2759](https://github.com/erclx/canon/issues/2759)) ([6eff8ce](https://github.com/erclx/canon/commit/6eff8ce998e3007e5a2847934c6af4a6b49fba89))
+* **skills:** let a drive session plan the rows its intake produced ([#2758](https://github.com/erclx/canon/issues/2758)) ([0dd775d](https://github.com/erclx/canon/commit/0dd775d3507b094bad9f0c808516b3c288b4b500))
+* **tasks:** wait in the background for a row to become launchable ([#2764](https://github.com/erclx/canon/issues/2764)) ([b45a23a](https://github.com/erclx/canon/commit/b45a23af5301fadd8598afb4d8559c06d7b91354))
+
+
+### Bug Fixes
+
+* **take:** let a take request raise its stepped frame stall limit ([#2771](https://github.com/erclx/canon/issues/2771)) ([140aec3](https://github.com/erclx/canon/commit/140aec340b3e43c12bc67bd74fc96155661bd92b))
+
 ## [5.68.0](https://github.com/erclx/canon/compare/v5.67.0...v5.68.0) (2026-10-26)
 
 

package/README.md

@@ -1,193 +1,67 @@
 <div align="center">
 
 <picture>
- <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-accent.svg">
- <img src="assets/brand/mark-accent-light.svg" alt="canon" width="56" height="56">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-color.svg">
+ <img src="assets/brand/mark-color-light.svg" alt="canon" width="56" height="56">
 </picture>
 
 # canon
 
+A CLI and Claude Code plugin that runs your agent's work from plan to merge, holds it to established engineering practice, and installs the same setup in every repo.
+
 [![npm version](https://img.shields.io/npm/v/@erclx/canon)](https://www.npmjs.com/package/@erclx/canon)
 [![CI status](https://img.shields.io/github/actions/workflow/status/erclx/canon/verify.yml?branch=main)](https://github.com/erclx/canon/actions/workflows/verify.yml)
 [![License MIT](https://img.shields.io/npm/l/@erclx/canon)](LICENSE)
 
-canon is a CLI and Claude Code plugin that runs your agent's work from plan to merge, holds it to the practices that make code worth keeping, and installs the same setup in every repository.
-**[See it run at canon.erclx.dev](https://canon.erclx.dev)**
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="assets/loops/launch.gif">
+ <img src="assets/loops/launch-light.gif" alt="One change running through canon, from the groundwork that measured it through its plan, dispatch, build, and review to the merge" width="960">
+</picture>
 
 </div>
 
-That page is one real session the toolkit ran on itself, and every count on it is read from this repository when the page builds.
-
-## Why
-
-If an agent writes code for you in more than one repository, this is for you. canon runs that work from plan to merge. A planner writes the plan, a worker builds it on its own branch, and a separate session reviews the pull request.
-
-It holds the work to a practice, with rules that load when a matching path is edited and checks that fail when a rule is ignored. Both run on one setup, installed the same way in every repository you keep.
-
-### The shared setup
-
-That shared setup is what the rest of this page describes, and it drifts without a source. Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
-
-Three design choices shape the toolkit.
-
-- Agent-first: every command has a non-interactive path and a JSON catalog. If a Claude Code skill or any other agent cannot drive the CLI without prompts, the design is wrong.
-- Text-native: conventions, rules, and prompts are authored as markdown that you and your agents read the same way. No hidden behavior, no compiled state.
-- One source, many consumers: this repo is the authoritative copy. Your projects install and sync on demand, never author in place.
-
-Two limits worth knowing before you install. Claude Code is the only agent runtime the plugin targets, and the CLI needs Bun on your path.
-
-## Install
-
-Add the marketplace, then install the Claude Code plugin.
+## Quick start
 
 ```bash
 claude plugin marketplace add https://github.com/erclx/canon
 claude plugin install canon@canon
-```
-
-<picture>
- <source media="(prefers-color-scheme: dark)" srcset="assets/frames/install.png">
- <img src="assets/frames/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
-</picture>
-
-The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
-
-Several skills call the `canon` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.
-
-```bash
 bun install --global @erclx/canon
 ```
 
-[Bun](https://bun.sh) is the CLI runtime and has to be on your path first. Confirm the install by resolving `canon --help`.
-
-## What is inside
-
-Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
-
-### Domain catalog
-
-| Domain         | What it is                                                                                            | How it reaches you                                              |
-| -------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain             | Loaded live from the plugin, never copied                       |
-| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited             | Installed per project by `canon gov install`, refreshed by sync |
-| Tooling stacks | Golden configs, seeds, and a reference per framework                                                  | Laid down by `canon init`, reconciled by `canon tooling sync`   |
-| Design system  | Ships a `DESIGN.md` intent format pointing at your stylesheet for values, and a skill that drafts one | `canon:design-record` drafts it in your repo                    |
-| Transcripts    | A YouTube transcript with metadata frontmatter                                                        | `canon transcripts <url>` writes it into any repo               |
-| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow            | `canon sandbox`                                                 |
-
-The design board lives outside canon in [Frameboard](https://www.npmjs.com/package/frameboard), which `canon:pick-by-eye` drives for each round of candidates.
-
-### How domains reach you
-
-Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A plugin skill and the references it carries are never copied, so there is no copy in your repo to drift from this one.
-
-Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
-
-## It runs on itself
-
-The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
-
-<picture>
- <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view/demo.gif">
- <img src="demos/agent-view-light/demo.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
-</picture>
-
-That recording is the landing page's own `dispatch` and `workers` sections, driven through a browser against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
-
-## Documentation
-
-Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
-
-Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at your project root first, then whichever rules under `.claude/rules/` match the paths it edits. Run `canon docs agents` for the command catalog with flags, exit codes, and JSON shapes.
-
-- [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
-- [Skill map](docs/workflow/skill-map.md): plugin skills grouped by the moment a project meets them
-- [Skill map on request](docs/workflow/skill-map-on-request.md): plugin skills that serve a request rather than a moment
-- [Visual design workflow](docs/workflow/visual-design-workflow.md): how canon plans, builds, and reviews a UI
-- [Target projects](docs/target/projects.md): scaffold, add a domain later, sync upstream drift
-- [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
-- [Docs index](docs/index.md): every reference doc in this repo
-
-## Update
-
-Nothing refreshes on its own. Claude Code ships auto-update off for third-party marketplaces, so an installed copy serves whatever version it was installed at until you refresh it.
-
-```bash
-claude plugin marketplace update canon
-claude plugin update canon@canon
-canon upgrade
-```
-
-The first two update the skills, the third updates the CLI, and they move independently. Restart Claude Code, or run `/reload-plugins`, to pick the skills up.
+The skills land as `/canon:<name>`, and the CLI needs Bun on your path. canon runs on Linux and macOS.
 
-`canon upgrade` reads the package manager off its own install path and reinstalls with that one, so you don't have to remember which put it there. It names what it detected before it runs anything, and it refuses a source checkout rather than reinstalling over your clone.
+Set up a repository with `canon init`, which lays down its rules, seeds, and configs.
 
-### Checking for drift
+## How a change runs
 
-You don't have to wait until something breaks to find out you're behind. `canon sync --check` and `canon claude skills drift` both report the installed version against the newest published one, and neither changes its exit code over it, so an offline machine reads unknown rather than red.
+| 1. Plan                                                  | 2. Build                                                | 3. Review                                                   | 4. Merge                      |
+| -------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------- |
+| A planner reads the code and writes one plan you approve | A worker builds it on its own branch, held to the rules | A fresh session reviews the pull request and posts findings | You read the review and merge |
 
-To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `canon --version` and `claude plugin list`.
+Each session works in its own worktree, so several changes run at once.
 
-## Development
+## What lands in your repo
 
-Working on the toolkit starts from a clone. Running the CLI doesn't, since it installs from the registry. Skip this section unless you're changing the toolkit itself.
+| Part              | How it reaches you                                                             |
+| ----------------- | ------------------------------------------------------------------------------ |
+| Skills            | Loaded live from the plugin, so there is no copy to drift                      |
+| Rules             | Files under `.claude/rules/` that load when you edit a matching path           |
+| Configs and seeds | Real files you own, laid down by `canon init` and kept current by `canon sync` |
 
-### Prerequisites
+## For your agent
 
-Bun, Git, and a shell are required, and the GitHub CLI is optional.
+- Every command runs without a prompt, and data on stdout pipes clean
+- `canon <command> --help` prints each command's flags, exit codes, and examples
+- Rules load by path, so the agent gets the rule for the file it is editing
 
-- [Bun](https://bun.sh) for the CLI runtime and scripts
-- [Git](https://git-scm.com) with worktree support
-- [GitHub CLI](https://cli.github.com) (optional) for ship flows
-- Shell: `zsh`, since bootstrap appends its aliases to `~/.zshrc`.
+## Docs
 
-Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and appends a marked block of Claude Code shell aliases to your `~/.zshrc`.
-
-```bash
-git clone https://github.com/erclx/canon.git
-cd canon
-bun install
-bun run bootstrap
-```
-
-The script is idempotent, so re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `canon --help` on the last step.
-
-- It leaves an alias block you already have alone rather than refreshing it, so an alias added upstream needs the block deleted and the script re-run.
-- [Zshrc aliases](docs/workflow/zshrc-aliases.md) covers what each alias does, how to pick up a new one, and how to opt out of the block.
-
-With the CLI linked, scaffold a fresh project.
-
-```bash
-mkdir ~/my-project && cd ~/my-project
-git init
-canon init
-```
-
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass.
-
-- Governance defaults to the `base` stack, so a bare init lands the workflow and doc-authoring rules in `.claude/rules/`.
-- Each rule names the skill it loads, so no corpus is copied into your project.
-- Pass `--stack <name>` for a language stack such as `node` or `python`, or `--skip governance` to leave rules out.
-- Run `canon tooling list --json` to see the catalog.
-
-For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/projects.md).
-
-### Internal narrative
-
-Each domain carries an entry written for someone maintaining the toolkit rather than installing it. These paths resolve in a clone only. The published package ships `docs` and not `.claude`, so an installed copy does not carry them.
-
-- [Claude Code plugin](canon/context/surfaces/plugin.md)
-- [Governance rules](canon/context/surfaces/governance.md)
-- [Tooling stacks](canon/context/surfaces/tooling.md)
-- [Design system](canon/context/features/design.md)
-- [Transcripts](canon/context/features/transcripts.md)
-- [Sandbox](canon/context/development/sandbox.md)
+- [AI workflow](docs/workflow/ai-workflow.md): the loop a feature runs
+- [Operating model](docs/workflow/operating-model.md): planners, workers, and reviewers in parallel
+- [Skill map](docs/workflow/skill-map.md): every skill by the moment you reach for it
+- [Agents](docs/agents/index.md): flags, exit codes, and output shapes
+- [Docs index](docs/index.md): every reference doc, updating canon among them
 
 ## Contributing
 
-Portfolio project. Issues are welcome. Pull requests are accepted by invitation only, so open an issue rather than a branch. Read the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention before you file anything.
-
-## License
-
-[MIT](LICENSE)
+Issues are welcome. Pull requests are by invitation, so read the [contributing guide](CONTRIBUTING.md) before you open one. Released under the [MIT license](LICENSE).

package/assets/brand/mark.svg

@@ -1,10 +1,18 @@
-<!-- A bound ledger: two pages fanned open around a spine, drawn as three
-     solid masses rather than thin strokes, so the shape survives being
-     rendered at favicon size instead of averaging into grey. The 10-unit
-     gap between each page and the spine, against an 80-unit frame, is what
-     keeps the split a visible channel at 16px; a first draft at half that
-     gap closed into an unreadable blob at the same size. -->
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
-  <path d="M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z" fill="currentColor" />
-  <rect x="44" y="15" width="12" height="70" rx="2" fill="currentColor" />
+<!-- A squarish bold c with one pip just past its mouth, in a 100 unit grid.
+     The body is a 76 square at (8, 12) with corner radius 30, stroked 20, so
+     the counter is a 36 square at (28, 32) with corner radius 10. The mouth is
+     cut from x 46 to the right edge level with the counter, so the inside runs
+     straight out of its curve, and the arm ends fall where that cut meets the
+     outer corners. The pip is one stroke wide, a 20 square at (81.3, 40) with
+     corner radius 3.8, on the center line. The view is centered on the bounds
+     so the pip does not clip.
+
+     The c is one outline rather than a masked square, and nothing carries an
+     id, since the nav, the hero, and the card inline this file and two inlined
+     copies sharing an id collide. The c fills currentColor so an inlining
+     surface hands it the text ink, and the pip carries its own fill under a
+     class a CSS rule overrides with the brand pair. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-0.35 -5 110 110">
+  <path d="M82.28,32 A30,30 0 0 0 54,12 H38 A30,30 0 0 0 8,42 V58 A30,30 0 0 0 38,88 H54 A30,30 0 0 0 82.28,68 H38 A10,10 0 0 1 28,58 V42 A10,10 0 0 1 38,32 Z" fill="currentColor" />
+  <rect class="pip" x="81.3" y="40" width="20" height="20" rx="3.8" fill="#c2380e" />
 </svg>

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.68.0",
+  "version": "5.70.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/app-drive/REQUIREMENT.md

@@ -15,8 +15,8 @@ Nothing ties the drive to what the app is for, so a goal goes untried and nobody
 
 - The drive runs from a copy outside the project, and the copy is gone when the drive closes
 - Every requirements goal is driven per persona, or marked not driven with its reason
-- Every finding names its source and its severity, and carries its evidence inside the intake folder
-- The drive files one intake folder, each finding sorted as a bug, a requirements conflict, or a taste call
+- Every finding names its source and its severity, and carries its evidence inside the intake folder, as does every image the operator pastes during the drive
+- The drive files one intake folder, each finding sorted as a bug, a requirements conflict, or a taste call, and a session staying to plan its rows answers it before any row is promoted
 - `canon intake drive-check` fails a drive that skipped a goal, touched the checkout, or left evidence outside the folder
 
 ## Must not
@@ -28,8 +28,8 @@ Nothing ties the drive to what the app is for, so a goal goes untried and nobody
 
 ## Out of scope
 
-- Reading source for roughness, which `ux-audit` owns
+- Reading source for roughness, which `ui-audit` owns
 - Driving one pull request's checklist, which `review-ui` owns
-- Measuring paint and layout cost, which `ux-measure` owns
-- Picking between a now frame and a fix frame, which `pick-by-eye` owns
+- Measuring paint and layout cost, which `ui-measure` owns
+- Picking between a now frame and a fix frame, which `design-pick` owns
 - Messaging the controller and ending the session, which `role-planner` owns

package/claude/skills/app-drive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-drive
-description: Drives a throwaway copy of a built app with the operator, tries every requirements goal per persona, re-checks the last drive's findings, measures each operator ask, sorts each finding as a bug, a requirements conflict, or a taste call, and files the lot as an intake folder that `canon intake drive-check` holds. Use when asked to "drive the app", "kick the tires", "run an app drive", or "drive the build with me", typically after a release or a wave and before planning the next. Do NOT use to read source for UI roughness, which is `ux-audit`, to drive one pull request's checklist, which is `review-ui`, to measure paint or layout cost, which is `ux-measure`, or to fix anything the drive finds.
+description: Drives a throwaway copy of a built app with the operator, tries every requirements goal per persona, re-checks the last drive's findings, measures each operator ask, sorts each finding as a bug, a requirements conflict, or a taste call, and files the lot as an intake folder that `canon intake drive-check` holds. Use when asked to "drive the app", "kick the tires", "run an app drive", or "drive the build with me", typically after a release or a wave and before planning the next. Do NOT use to read source for UI roughness, which is `ui-audit`, to drive one pull request's checklist, which is `review-ui`, to measure paint or layout cost, which is `ui-measure`, or to fix anything the drive finds.
 metadata:
   family: check
 ---
@@ -32,11 +32,11 @@ Read `${CLAUDE_SKILL_DIR}/references/config.md` for `canon/config/app-drive.toml
 1. Derive `<slug>` from the build being driven, such as `app-drive-0-12-0` for a tag. Claim the folder with `canon records ordinal intake <slug> --claim`.
 2. Record the baseline with `canon intake drive-check <slug> --baseline --json` from the main root, before the first build step. Stop on any `reason` other than `recorded`.
 3. Make the throwaway worktree, build it, and serve it per `${CLAUDE_SKILL_DIR}/references/isolate.md`, which also carries the close and the recovery after a crash.
-4. Confirm the address with `canon pr local --root <worktree> --json` and hand it to the operator before driving.
+4. Confirm the address with `canon pr local --root <worktree> --json`, write it as the drive log's `Address` row, and hand it to the operator before driving.
 
 ## Step 2: drive
 
-Read `${CLAUDE_SKILL_DIR}/references/drive-record.md` before the first finding, for the log line, the severity scale, and the record the check reads.
+Read `${CLAUDE_SKILL_DIR}/references/drive-record.md` before the first finding, for the drive log's shape, the severity scale, and the record the check reads.
 
 Work through three sources in this order, and name the source on every finding:
 
@@ -61,7 +61,9 @@ A drive reaches the app the way its personas do, through the page or through the
 Append each finding to the drive log as it happens, never batched at the end, since a compaction drops what chat alone holds.
 
 - Move each frame a finding cites from scratch into the intake folder's `evidence/`, and cite it by that path
+- Copy each image the operator pastes into `evidence/` in the turn its message arrives, under its finding's number, or under a `ref-` prefix when no finding cites it yet
 - Keep the measured number beside the claim in the log, never only in chat
+- Write an operator's decision under the finding it settles, even when later findings already sit below it, since it is the one edit above the end of the log
 - Write `drive.json` into the intake folder in the shape `drive-record.md` sets, with one entry per goal
 
 ## Step 4: sort
@@ -70,7 +72,7 @@ Give every finding one kind, and keep the severity it was logged with.
 
 - **Bug.** The app breaks a goal or its own contract. It becomes an item whose fix a worker can build, with the repro and the evidence path. `systematic-debugging` owns finding its cause.
 - **Requirements conflict.** The app does what the record says and the operator wants otherwise, or the record contradicts itself. The item carries the drafted diff as text, and the operator decides.
-- **Taste.** The call is settled by looking. The item carries a now frame and a fix frame for a `pick-by-eye` pass, written to the config's `proposals` folder.
+- **Taste.** The call is settled by looking. The item carries a now frame and a fix frame for a `design-pick` pass, written to the config's `proposals` folder.
 
 ## Step 5: file
 
@@ -90,6 +92,15 @@ Close only on the operator's word, while the app stays up for as long as they ke
 4. Run `canon records validate intake <slug>` and fix each `structure` entry it names.
 5. Hand the operator the text of `canon/config/app-drive.toml` built from Step 1's answers, when the project carried none. Never write it, since a tracked file is the operator's or a worker's.
 
+### Planning the drive's rows
+
+Run this tail only when the operator, staying after the close, asks this session to plan the drive's rows. The session holds measurements and calls the intake records only as outcomes, so a drive the operator leaves at the close ends there.
+
+1. Answer the intake's `You:` slots with `plan-intake-answer` before any row is promoted from it.
+2. Send the controller the ready list, naming no item whose `You:` slot is still open, and say this session is planning those rows, so it holds a cold planner for each.
+3. Wait for the controller to file the rows and name each back. Plan only a row named to this session, and write no task file.
+4. Plan each named row under `plan-feature`, then link it with `canon tasks plan-link` and announce it per `role-planner` before starting the next.
+
 ## Output
 
 Emit the full relative path of every file written, the drive-check `reason`, and the routing counts.
@@ -100,7 +111,7 @@ Emit the full relative path of every file written, the drive-check `reason`, and
 **Drive:** <N> goals across <P> personas, <F> findings (<B> bugs, <R> requirements conflicts, <T> taste)
 **Check:** drive-check clean, worktree removed
 
-Next: /plan-intake-answer to answer the You: slots from here, then /task-board to promote what is ready
+Next: /plan-intake-answer to answer the You: slots from here, then /task-board to promote what is ready, or ask this session to plan the rows per Planning the drive's rows
 ```
 
 ## What this delegates
@@ -108,5 +119,5 @@ Next: /plan-intake-answer to answer the You: slots from here, then /task-board t
 - The controller messages, the talk clause, and the session's end: `role-planner`
 - The intake folder's shape and its routing test: `plan-intake`
 - The cause of a bug: `systematic-debugging`
-- The pick between a now frame and a fix frame: `pick-by-eye`
+- The pick between a now frame and a fix frame: `design-pick`
 - The voice of every recorded passage: `write-human`

package/claude/skills/app-drive/references/drive-record.md

@@ -1,6 +1,6 @@
 ---
 title: Drive record
-description: The drive log line, the severity scale, the finding sources, and the drive.json shape that canon intake drive-check reads
+description: The drive log, the severity scale, the finding sources, and the drive.json shape that canon intake drive-check reads
 ---
 
 # Drive record
@@ -9,16 +9,69 @@ Read before the first finding of `app-drive`. A drive leaves two records in its
 
 ## The drive log
 
-Write the log to `evidence/drive-log.md` inside the intake folder, one line per finding, appended as the finding happens.
+Write the log to `evidence/drive-log.md` inside the intake folder. It opens on a setup table, then takes one heading per finding, appended as the finding happens.
 
-```plaintext
-- <nn>. [<severity>] [<source>] <persona>: did <action>, saw <result>. Evidence: evidence/<nn>-<name>.png
+```markdown
+# Drive log
+
+| Setup     | Value                                             |
+| --------- | ------------------------------------------------- |
+| Commit    | `v0.13.138`                                       |
+| Copy      | `/tmp/tmp.Xy12/app`                               |
+| Launch    | `bun install && bun run build && bun run preview` |
+| Address   | `http://127.0.0.1:4530`                           |
+| In flight | `feat/landing-page` holds `web/`                  |
+
+## 02. Layers click leaves a half-hidden frame in place
+
+`minor` · operator · developer
+
+- **Did:** clicked the frame in Layers
+- **Saw:** the view stayed put, with 64% of the frame under the panel edge
+- **Cause:** from code, the reveal acts only when the box is wholly outside the view
+- **Evidence:** `evidence/02-partial-no-pan.png`
+- **Decision (operator):** center the frame unless it is wholly visible
 ```
 
 - `<nn>` numbers findings in the order they were found, and the frame carries the same number
-- `<source>` is `goal`, `last-drive`, or `operator`. A finding naming none sorts as taste.
-- `<result>` carries the number read off the page or the app when the claim has one, such as `scrollWidth 436 against clientWidth 320`
-- A goal tried and passed takes a line too, as `[pass] [goal]`, so the next drive can tell a goal checked from one skipped
+- The title names what the persona met, in sentence case with no trailing period
+- The meta line holds the severity, the source, and the persona, in that order. The source is `goal`, `last-drive`, or `operator`, and a finding naming none sorts as taste.
+- A `last-drive` finding adds `fixed`, `still open`, or `changed` to its meta line
+
+### Setup rows
+
+The setup table is written once, before the first finding, and every row stays even when its value is empty.
+
+- `Commit`, `Copy`, and `Launch` come from making the copy, per `isolate.md`
+- `Address` is the `url` that `canon pr local --root <worktree> --json` confirmed in Step 1
+- `In flight` names each open branch or live plan holding a path the drive covers, as `canon:role-planner` reads what is in flight, and reads `none` when nothing is
+
+### Fields
+
+The fields under the meta line carry the drive itself, one fact to a line.
+
+- `Saw` carries the number read off the page or the app when the claim has one, such as `scrollWidth 436 against clientWidth 320`
+- `Cause` is optional, and says whether it was measured or read from code
+- Write the operator's call as `Decision (operator)` under the finding it settles, even when it arrives after later findings
+- A decision settling two findings sits under the first, and the second carries `Decision (operator):` naming that finding's number, such as `see 02`
+- Keep each field to one line. A field that runs long splits into a second field rather than growing.
+
+### Passed goals
+
+A goal tried and passed takes a heading too, so the next drive can tell a goal checked from one skipped. Its meta line reads `pass` · goal · persona, and it carries `Did` and `Evidence` alone.
+
+### Operator images
+
+Operator images count as evidence on arrival. One showing a finding takes that finding's number and is cited from its `Evidence` field. One no finding cites yet is a reference shot with a heading of its own.
+
+```markdown
+## ref-01. The operator's Figma typography panel
+
+- **Evidence:** `evidence/ref-01-figma-typography.png`
+```
+
+- `ref-<nn>` numbers reference shots apart from findings, so a later finding citing one keeps the path it already has
+- Keep the pasted file's own extension when it is not a PNG
 
 ## Severity
 
@@ -52,7 +105,7 @@ Write it to the intake folder root before the close. `canon intake drive-check`
 
 - `goals` holds one entry per `## Goals` bullet, with the bullet's text. A bold label and a trailing period may stay or go, since the check strips both.
 - `status` is `driven` or `not-driven`, and a `not-driven` entry carries the `reason` the goal could not be reached
-- `evidence` lists every frame a finding cites, each a path under `evidence/` relative to the intake folder
+- `evidence` lists every frame a finding cites and every image the operator pasted, reference shots included, each a path under `evidence/` relative to the intake folder
 - `worktree` is the throwaway worktree's path, which the check fails on while it still exists
 
 ### What the check fails

package/claude/skills/app-drive/references/isolate.md

@@ -13,7 +13,7 @@ Run each command from the main worktree root.
 
 1. Run `git worktree prune` first, which drops the registration a crashed drive left behind once its folder is gone.
 2. Make a folder with `mktemp -d`, outside the repository, and add the worktree with `git worktree add --detach <dir>/app <commit>`. The commit is the tag or sha the operator names, or the trunk's tip.
-3. Record the commit, the folder, and the launch command as the first lines of the drive log.
+3. Record the commit, the folder, and the launch command as rows of the drive log's setup table, in the shape `drive-record.md` sets.
 4. Put the worktree's path in `drive.json` as `worktree`, so the check fails a drive whose close never removed it.
 
 A folder under the repository is the wrong home. The parent repository becomes the app's repository root, and a walk-up search for config or a lockfile finds the project instead of the copy.

package/claude/skills/canon-cli/SKILL.md

@@ -48,9 +48,9 @@ Each verb here has a skill that owns the job. Load the skill rather than driving
 | Render an HTML source to a PNG               | `canon capture`     | `canon:design-identity`     |
 | Serve a directory and print the link         | `canon serve`       | none                        |
 | Report one computed property across routes   | `canon inventory`   | `canon:target-check`        |
-| Walk a page through interactions and measure | `canon drive`       | `canon:ux-measure`          |
+| Walk a page through interactions and measure | `canon drive`       | `canon:ui-measure`          |
 | Drive the pinned agent browser               | `canon browser`     | `canon:review-ui`           |
-| Film a web app with a click log and camera   | `canon take`        | `canon:ui-record`           |
+| Film a web app with a click log and camera   | `canon take`        | `canon:ui-film`             |
 | Fetch a YouTube transcript                   | `canon transcripts` | `canon:youtube-transcripts` |
 
 The design board is Frameboard, a separate CLI outside canon, so a board job runs a `frameboard` verb rather than a `canon` one.

package/claude/skills/canon-feedback/REQUIREMENT.md

@@ -29,6 +29,6 @@ Asked to report, a session also starts diagnosing, which spends the context the
 ## Out of scope
 
 - Fixing the defect, which happens in the toolkit repository against its own source
-- Draining the queue this fills, which `canon-feedback-triage` owns
+- Draining the queue this fills, which the toolkit's maintainers do in its own repository
 - Filing an issue against the current project, which `git-issue` owns
 - Complaints about tooling the toolkit does not own

package/claude/skills/canon-feedback/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Canon feedback
 
-Format a `## Toolkit feedback` block from the current session, then open it as a GitHub issue on the toolkit repo, labeled `feedback` plus the domain label its surface type names. `canon-feedback-triage` reads that queue.
+Format a `## Toolkit feedback` block from the current session, then open it as a GitHub issue on the toolkit repo, labeled `feedback` plus the domain label its surface type names. The toolkit's maintainers triage that queue.
 
 ## Guards
 

package/claude/skills/design-identity/REQUIREMENT.md

@@ -15,7 +15,7 @@ A session building this alone restates the render-and-pick loop from scratch, wh
 
 - The icon size sequence and the write folder come from the project's own head, manifest, or static-asset convention before a stated default, and the run names which one decided
 - Every arm is drafted inside the card frame, so one pick settles the mark's shape and its composition together
-- The render, hand-off, pick, and loop follow `pick-by-eye` rather than a copy of it
+- The render, hand-off, pick, and loop follow `design-pick` rather than a copy of it
 - The final mark lands as its own SVG source, not only baked into a raster
 - Every final size and the card render in one capture call, each landing at its literal target size
 
@@ -23,12 +23,12 @@ A session building this alone restates the render-and-pick loop from scratch, wh
 
 - Draft a mark the operator did not ask for, or mutate an existing logo file, which is a plain edit
 - Add a logo section to the design document's fixed section set, which its parser reads as a fixed key set
-- Modify `pick-by-eye` or `canon capture`, which this skill composes
+- Modify `design-pick` or `canon capture`, which this skill composes
 - Be taken as reached by more than an operator typing its name, which a later review reads back rather than assumes
 
 ## Out of scope
 
-- The render, hand-off, pick, and loop mechanics, which `pick-by-eye` owns
+- The render, hand-off, pick, and loop mechanics, which `design-pick` owns
 - Carrying a picked direction into the design document, which `design-record` owns
-- Auditing an implemented UI against its tokens, which `ux-audit` owns
+- Auditing an implemented UI against its tokens, which `ui-audit` owns
 - Wiring the produced files into the project's head or manifest, which the operator owns