@erclx/canon 5.69.0 → 5.71.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [5.71.0](https://github.com/erclx/canon/compare/v5.70.0...v5.71.0) (2026-10-27)
+
+
+### Features
+
+* **markdown:** read colon lists as labels ([#2797](https://github.com/erclx/canon/issues/2797)) ([f733a5f](https://github.com/erclx/canon/commit/f733a5f8d74e63cf5e257557a4d227b3478ca04a))
+* **tasks:** name the sessions behind a task on a Sessions line ([#2799](https://github.com/erclx/canon/issues/2799)) ([acf80c4](https://github.com/erclx/canon/commit/acf80c4ce9d2c1adbc3e1ea2dfde433a08d46b4e))
+
+## [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)
 
 

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:design-pick` 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.69.0",
+  "version": "5.71.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -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:
 
@@ -63,6 +63,7 @@ Append each finding to the drive log as it happens, never batched at the end, si
 - 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

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,23 +9,65 @@ 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 that finding's line, while one no finding cites yet is a reference shot with a log line of its own.
+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
 
-```plaintext
-- ref-<nn>. [operator] <what the image shows>. Evidence: evidence/ref-<nn>-<name>.png
+- **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

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/design-pick/SKILL.md

@@ -48,6 +48,7 @@ Each frame carries its own label and follows the board theme, so the set reads a
 - Label each arm inside its frame with its id and its cost, since the composite capture draws no captions
 - Theme every arm off the `data-theme` attribute the board sets on each frame's root, so the theme toggle sets the whole set at once. A set spanning both themes cannot be compared.
 - Give no arm a script that stores a theme and reapplies it on load. It overwrites the toggle, and a fresh browser profile hides the fault.
+- Write each frame's headings, labels, and captions by `${CLAUDE_SKILL_DIR}/../ui-craft/references/copy.md`, since a candidate's copy is often the first draft of the shipped page's
 
 ### Default path and live app
 

package/claude/skills/git-pr/references/task-number.md

@@ -29,6 +29,19 @@ The verb resolves the board at the main worktree root in-process, the root `sess
 - A line already reading as a list of `#NNN` entries takes the new number appended, reported as `appended`, so a task shipped in slices keeps every pull request
 - The same write drops this branch from the `Pending branch:` line `canon tasks outcome` wrote, which lets the merge-time archive close the task
 
+## Record the session
+
+Beside the number, name this session on the same task's `Sessions:` line. It is the one record that covers a hand-launched worker, which no dispatcher saw start. Read the id from the roster's own row for the caller, then hand it to the verb under the same plan:
+
+```bash
+id=$(canon sessions list --self --json | jq -r '.sessions[0].sessionId // empty')
+[ -n "$id" ] && canon tasks session "$id" --plan feature-<slug> --json
+```
+
+- A dispatched worker is already listed, since its dispatcher recorded it at launch, and the verb reports `unchanged` rather than writing it twice
+- An empty `id` means the roster could not name the caller, so skip the write and report that no session was recorded
+- Skip the same three refusals as the number below, and report `bad-input` or `no-name`, since either is a defect in this call
+
 ## Refusals
 
 Skip silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`, meaning no board, no task naming the plan, or more than one. A guessed write would compound each, since a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.

package/claude/skills/markdown-craft/references/markdown.md

@@ -134,6 +134,7 @@ A bullet's punctuation follows its sentence count, and a list opens unannounced.
 
 - Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them. A colon or a comma standing where the dash was is the same sentence, so split it or rewrite it.
 - Do not use a colon to join two clauses in the middle of a sentence. A colon belongs after a label or at the end of a line introducing a list.
+- The check misses a clause colon in a list of colon items, but it is wrong.
 - Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
 
 ## Language

package/claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md

@@ -86,6 +86,7 @@ The readout is the text `Created cloud session: <title>`, unanchored since a ter
 - On a failed create, report the typescript's last lines and fall back to the human-launch line in `orchestrator-dispatch.md`
 - The wrapper is a stopgap any change to the interactive create screen breaks, which is why the readout fails loudly instead of guessing
 - Record `session` beside the row's branch in this pass's launched record, since that and the pull request list are the only readings that know it exists
+- Name it on the row's task with `canon tasks session "$session" <task> --name cloud-<project>-<slug> --json`, since a cloud worker has no board and the roster never lists it
 - Report the dispatch as the local shape does, naming the row, the plan, the repository, and the session id in place of a session name
 
 ## Recognize the pull request

package/claude/skills/role-orchestrator/references/orchestrator-launch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator launch runbook
-description: The launch every dispatch kind shares, being the build, cloud build, review-address, planning, and talk templates, the session name and controller id each carries, why the command sits at position zero, and what the brief may carry
+description: The launch every dispatch kind shares, being the build, cloud build, review-address, and planning templates with a pointer to the talk variant, the session name and controller id each carries, why the command sits at position zero, and what the brief may carry
 ---
 
 Run this once `orchestrator-dispatch.md` has cleared a row, or from its planning or review-address shape below when that runbook's checks do not bind. The model each template names comes from `## Pick the model` in that runbook.
@@ -79,6 +79,10 @@ The prompt carries pointers and standing context, and stops there. The branch an
 
 Report the dispatch as loudly as the human-launch line it replaces, naming the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
+### Record the worker on its task
+
+Once a build or review-address launch returns, run `canon tasks session <worker-id> <task> --json` with the sessionId the launch output carries. On `no-name`, the worker already exited, so rerun with `--name` and the name passed to `-n`.
+
 ## Dispatch to a cloud worker
 
 Read `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` when `orchestrator-dispatch.md` picked cloud for the row. It holds the prompt that carries the plan as text and announces over GitHub, the create under `script`, and the readout that refuses to record a missing session id.
@@ -137,25 +141,7 @@ Hold all planning of a row any talk session has said by message it is planning,
 
 ## Dispatch a talk session
 
-A planner or worker the operator will talk with takes the same launch as its cold shape above, with a `-talk` suffix on its name and one sentence added to its brief. A cold session works alone and reports back, and a talk session stays open after its plan or pull request lands so the operator can keep shaping the row.
-
-```bash
-claude --bg --model <model> -n "planner-<project>-<slug>-talk" "Run /canon:role-planner, then /canon:plan-feature <task>. This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
-claude --bg --model <model> -n "worker-<project>-<slug>-talk" "/canon:auto-ship <plan>
-This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
-```
-
-The ellipsis stands for the rest of the cold template's message clauses, unchanged. The build variant keeps `/canon:auto-ship <plan>` at position zero with nothing before it, per the rule above.
-
-- Keep the role prefix and add the suffix, since `orchestrator-handoff.md` separates dispatched sessions by `worker-` and `planner-` and a new prefix reads as a hand launch
-- A talk session is retired only on the operator's word, stated once in `orchestrator-handoff.md`, so do not restate it in a launch report
-- Reviewers get no talk shape, since a reviewer's pass holds no operator dialogue
-
-### Recording the talk session
-
-Read the session's `sessionId` off the launch output, carry it in this session's own context, and write it into the map's `## Talk sessions held open` at the next handoff. The client can rename a session and drop the suffix, so the id is the durable marker and the suffix is only for display.
-
-The map exists only once the handoff writes it, so this session's own launches, read with the prior map, are what the first wind-down reads talk sessions from.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-talk-launch.md` when the operator will talk with a planner or worker rather than leave it to report back. It states the `-talk` name suffix, the one sentence the brief adds, and where the session's id is kept for the handoff.
 
 ## Hand launch
 

package/claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md

@@ -21,6 +21,16 @@ claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-re
 - Append the cross-branch facts after the controller clause, per `### What the brief may carry` in `orchestrator-launch.md`
 - Check `canon sessions list --json` for a live `reviewer-<project>-<number>` before launching, and message it instead when one holds the pull request
 
+### Record the reviewer on the task
+
+A reviewer writes no task file, so this session names it on the task the pull request closes, through the sessionId the launch output carries:
+
+```bash
+canon tasks session <reviewer-id> <task> --json
+```
+
+Record the UI reviewer below the same way after its launch. A `no-name` refusal means the reviewer exited before the read, so rerun with `--name` and the name the launch passed to `-n`.
+
 ### The channel clauses
 
 The channel clauses restate what `role-reviewer` holds, so a reviewer whose plugin cache predates that body still sends the dispatch itself. The worker reads the reviewer's sessionId off that message and sends its re-review request back to it, since a reviewer holds the trunk branch and no branch lookup finds it.

package/claude/skills/role-orchestrator/references/orchestrator-talk-launch.md

@@ -0,0 +1,30 @@
+---
+title: Orchestrator talk launch
+description: The talk variant of the planning and build launches, being the name suffix, the one added brief sentence, and where the talk session's id is recorded for the handoff
+---
+
+Run this when the operator wants to talk with a planner or worker rather than leave it to report back. The rules every launch shares stay in `orchestrator-launch.md`.
+
+# Talk launch
+
+## The launch
+
+A planner or worker the operator will talk with takes the same launch as its cold shape in `orchestrator-launch.md`, with a `-talk` suffix on its name and one sentence added to its brief. A cold session works alone and reports back, and a talk session stays open after its plan or pull request lands so the operator can keep shaping the row.
+
+```bash
+claude --bg --model <model> -n "planner-<project>-<slug>-talk" "Run /canon:role-planner, then /canon:plan-feature <task>. This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
+claude --bg --model <model> -n "worker-<project>-<slug>-talk" "/canon:auto-ship <plan>
+This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
+```
+
+The ellipsis stands for the rest of the cold template's message clauses, unchanged. The build variant keeps `/canon:auto-ship <plan>` at position zero with nothing before it, per `### Position zero` in `orchestrator-launch.md`.
+
+- Keep the role prefix and add the suffix, since `orchestrator-handoff.md` separates dispatched sessions by `worker-` and `planner-` and a new prefix reads as a hand launch
+- A talk session is retired only on the operator's word, stated once in `orchestrator-handoff.md`, so do not restate it in a launch report
+- Reviewers get no talk shape, since a reviewer's pass holds no operator dialogue
+
+## Recording the talk session
+
+Read the session's `sessionId` off the launch output, carry it in this session's own context, and write it into the map's `## Talk sessions held open` at the next handoff. The client can rename a session and drop the suffix, so the id is the durable marker and the suffix is only for display.
+
+The map exists only once the handoff writes it, so this session's own launches, read with the prior map, are what the first wind-down reads talk sessions from.

package/claude/skills/task-board/references/tasks-record-lines.md

@@ -0,0 +1,40 @@
+---
+title: Task record lines reference
+description: The lines a verb writes on a task below its origin lines, being the Pull request line that lets a merge close its task, the Pending branch marker that holds that merge back, and the Sessions line naming who worked it
+---
+
+# Task record lines reference
+
+Applies to the lines a task carries under its origin lines that no session writes by hand. Each one has a `canon tasks` verb as its writer, and this file fixes what each line means and who calls that verb.
+
+This is an attribute standard. It governs lines inside a task file rather than a file of its own, so it carries no template.
+
+## Scope
+
+Governs the `Pull request:`, `Pending branch:`, and `Sessions:` lines.
+
+Does not govern:
+
+- The task file's layout, filename, format, origin lines, and archiving: `tasks.md`
+- The `Declined:` line: `tasks-decline.md`
+
+## The `Pull request:` line
+
+`Pull request:` lists every pull request that shipped part of the task as bare numbers, oldest first and comma-separated, as in `Pull request: #NNN, #NNN`. It is not an origin, so a task without one is well-formed, and `git-pr` appends to it when a pull request opens.
+
+The line lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any listed number and archives it only on the last.
+
+- One pull request, one task. Two tasks naming the same number refuse to archive rather than both moving.
+- `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number
+- `canon tasks outcome` writes that line, skipping it when the branch's pull request is already listed, and `canon tasks pull-request` clears it
+
+## The `Sessions:` line
+
+`Sessions:` names each session that built or reviewed the task, by roster name and full sessionId, as in `Sessions: <name> (<sessionId>), <name> (<sessionId>)`. A retro or a regression hunt reaches each transcript through `canon sessions export <sessionId>`, which takes the full id alone. It is not an origin either.
+
+- `canon tasks session <sessionId> <task>` writes it, or `--plan <slug>` in place of the stem, so it is never hand-edited
+- The verb reads the name off the live roster. A session that already exited takes `--name`, and so does a cloud session's `session_` id, since the roster never lists one.
+- The id is the key. A repeat call for a listed id keeps the name first recorded, so two callers recording one worker write it once.
+- The dispatcher records each worker and reviewer it launches, and `git-pr` records the session opening the pull request, which covers a hand launch
+
+The line sits below the origin, `Pull request:`, and `Pending branch:` lines. `canon tasks validate` reports a line that does not parse as name and id pairs as `sessions-misshapen`.