@erclx/canon 5.69.0 → 5.70.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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)
 
 

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.70.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/ui-craft/references/copy.md

@@ -3,7 +3,10 @@
 ## Punctuation
 
 - Write no em dash (`—`) or semicolon in rendered copy. Use a comma or a period, or restructure the sentence.
-- Add no trailing punctuation to a button label or a short action string.
+- Add no trailing period, colon, or exclamation mark to a heading, label, link, button, nav item, caption, status, or one-sentence tagline. Keep the question mark a question needs.
+- Rewrite a two-sentence tagline as one sentence rather than keeping a period inside it.
+- End a one-sentence error or validation message with no period, such as `Enter an email address`.
+- Keep end punctuation on body copy, multi-sentence messages, and quoted text, which a reader reads as prose.
 
 ## Button copy
 

package/claude/skills/ui-film/REQUIREMENT.md

@@ -19,13 +19,15 @@ A session that does reach `canon take` writes the plan from its own reading of t
 - The session looks at a still of each take before handing it off or posting it as a pull request reel, and names a beat that fell back to the real-time route
 - HyperFrames receives the takes with what it needs to apply the camera and draw the cursor
 
-One video keeps its plan, takes, and composition in one workspace the operator can find, backed up without its media.
+One video keeps its plan, takes, and composition in one workspace the operator can find, backed up without its media. A README there records how to re-film the takes, and the composing session adds how to re-render.
+
+A session composing the takes finds the footage guidance HyperFrames lacks, being captions over app UI, other shapes, a README loop, and sped-up clips.
 
 ## Must not
 
 - Film before the operator approves, or with nobody there to approve, unless `pr-evidence` named pull request mode, whose still check stands in for the approval
 - Write a tracked file, the config included
-- Compose, caption, or render the video
+- Run the composition or render the video, or write any composition file
 - Trigger on anything but a request to record or film the app
 - Stay when no caller besides the operator reaches it, such as a pull request clip through `pr-evidence`, which a review checks
 

package/claude/skills/ui-film/SKILL.md

@@ -71,12 +71,15 @@ canon take <url> .canon/video/<slug>/plan.json --out .canon/video/<slug>/takes -
 
 Branch on the record's `reason`, never on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
-| Record               | Route                                                                                   |
-| -------------------- | --------------------------------------------------------------------------------------- |
-| No `reason`          | Continue to the stills                                                                  |
-| `target-missing`     | Find the target the record's `beat` names on the page, fix the plan, and film once more |
-| `server-unreachable` | Restart the server from Step 1 and film once more                                       |
-| Any other `reason`   | Report the `reason` and `message` to the operator and stop, since each is a setup step  |
+| Record                           | Route                                                                                                              |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| No `reason`                      | Continue to the stills                                                                                             |
+| `target-missing` with `fallback` | Check the access before the selector, per the note below the table                                                 |
+| `target-missing`                 | Open the record's `still`, find the target the record's `beat` names on the page, fix the plan, and film once more |
+| `server-unreachable`             | Restart the server from Step 1 and film once more                                                                  |
+| Any other `reason`               | Report the `reason` and `message` to the operator and stop, since each is a setup step                             |
+
+A refusal carrying `fallback` means the screencast opened the address a second time, so a single-use link was spent before the step ran. Read `${CLAUDE_SKILL_DIR}/references/config.md` for the access the take opens with, and fix that before touching the target.
 
 A second refusal of the same kind stops the run and reports both records.
 
@@ -85,30 +88,40 @@ A second refusal of the same kind stops the run and reports both records.
 Open each beat's `takes/<dir>/still.jpg` before handing off, since a clip can film the wrong state cleanly. The verb writes it from the clip's closing frame, where the action's result shows.
 
 - Say what each still shows beside the beat it belongs to
-- Report a beat the record marks with `fallback` as filmed in real time at 1080p, which goes soft under a zoom, and offer to re-film it with the beat's input simplified
+- Report a beat the record marks with `fallback` as filmed in real time at 1080p, whose zoom stops near 1.35x rather than 1.8x, and offer to re-film it with the beat's input simplified
 
 ## Step 5: hand off
 
-Read `${CLAUDE_SKILL_DIR}/references/handoff.md` on reaching this step. It sets what HyperFrames receives and how a composition applies the camera track and draws the cursor.
+Read `${CLAUDE_SKILL_DIR}/references/handoff.md` on reaching this step, for what HyperFrames receives, where each composition lives, and how one applies the camera track and draws the cursor. Read `${CLAUDE_SKILL_DIR}/references/compose-craft.md` beside it, for the footage rules the HyperFrames skills lack.
 
 Close the throwaway copy per `isolate.md` when Step 1 built one, after the stills are read.
 
+### Write the workspace README
+
+Write the filming half of `.canon/video/<slug>/README.md`, so a later session can re-film without this one. The composing session adds the re-render half under its own heading, as `compose-craft.md` states.
+
+- Name what was filmed, beat by beat, and how to re-film each one with `canon take`
+- Say where each folder came from, being the plan, the takes, and the config keys the take read, with `access` described rather than copied when it carries a token
+- Write the file whole through the main-root route when none exists, with the filming half under a `## Filming` heading
+- Add a `## Filming` section when a README is already there, reading the file and writing it back whole, and never overwrite what another session wrote
+- Replace an existing `## Filming` section in place on a re-film, since the commands in it changed
+
 ## Output
 
 Emit the takes folder, one line per beat, and the next step.
 
 ```plaintext
-🎬 Filmed .canon/video/<slug>/takes/
+🎬 Filmed .canon/video/<slug>/takes/, re-film notes in .canon/video/<slug>/README.md
 
 01-open-the-kit  step  4.2 s  the board's first page with its frames filled in
 02-search-for-color  screencast (fallback)  3.8 s  the page list narrowed to two results
 
-Next: load hyperframes to compose, reading takes/take.json and the handoff notes
+Next: load hyperframes to compose, reading takes/take.json, handoff.md, and compose-craft.md
 ```
 
 ## What this delegates
 
 - `app-drive`'s `isolate.md` owns the throwaway copy and its close
 - `hyperframes-creative`'s story spine owns what a beat says to a viewer
-- `hyperframes` and its sibling skills own composing, captioning, and rendering the video
+- `hyperframes` and its sibling skills own composing, captioning, and rendering the video, and `compose-craft.md` adds only what app footage changes about their advice
 - `review-ui` owns driving a pull request's checklist

package/claude/skills/ui-film/references/compose-craft.md

@@ -0,0 +1,81 @@
+---
+title: Compose craft
+description: The footage rules a session composing ui-film takes follows where the HyperFrames skills say nothing, being captions over app UI, other shapes, the README loop, sped-up clips, storyboard headings, and the workspace README
+---
+
+# Compose craft
+
+Read at Step 5 of `ui-film`, and by the session that composes the takes, which the handoff's next line points here. HyperFrames owns composing, captioning, and rendering, so this file carries only what app footage changes about its advice and restates none of it.
+
+Each rule states the principle. Where a number appears, it is the case measured on one app's launch film, not a law for the next app.
+
+## Contents
+
+- [Captions over app footage](#captions-over-app-footage)
+- [Other shapes](#other-shapes)
+- [The README loop](#the-readme-loop)
+- [Sped-up clips](#sped-up-clips)
+- [Storyboard headings](#storyboard-headings)
+- [The workspace README](#the-workspace-readme)
+- [Sources](#sources)
+
+## Captions over app footage
+
+HyperFrames' caption guide places a landscape caption 80 to 120 px from the bottom and keeps it off a speaker's face. App footage has no speaker, and its bottom edge is often a toolbar where the beat's click lands.
+
+- Pick one caption position for the whole film, clear of the app's chrome where actions land, and keep every caption there, since a caption that moves between beats makes the viewer hunt for it
+- Back a caption over bright UI with the scrim HyperFrames' caption guide sizes to the text
+- Snapshot each caption's moment, and move a caption only when it covers its own beat's action
+- Write caption text by the interface copy rules in `ui-craft`'s `copy.md`, so a caption ends with no period
+
+## Other shapes
+
+Cut a square or vertical version only when the operator asks for one. A film with one shape needs nothing from this section, and the vertical caption band and safe boxes stay with HyperFrames' frame presets.
+
+- Start each shape as its own HyperFrames project, as `hyperframes-studio` states for a different aspect, in the workspace folder `handoff.md` names for it
+- Frame the shape by cropping a window of the page at 1x, never by scaling the 16:9 frame into it, since a page shrunk into a square leaves the action too small to read
+- Pan the window along the camera track's view center, so it follows the action the zoom would have aimed at. Frameboard's square cut used a 1080x1080 window.
+- Expect a screencast take to hold at 1x from a softer 1080p source, while a stepped take gives the same window two clip pixels per page pixel
+
+## The README loop
+
+Cut a README loop only when the operator asks for one. A README hero plays inline and silently, so it is a short loop rather than a cut of the film.
+
+- Cut it from the raw take showing the app's core action, rather than from a render, in the workspace folder `handoff.md` names for it
+- Crop it to the canvas, so no browser margin or page chrome outside the app shows
+- End it on the finished state, held long enough to read before the loop restarts
+- Export an animated WebP under about 2 MB, since a README renders one inline where a video needs a player. Frameboard's loop played inline at 1.72 MB.
+
+## Sped-up clips
+
+A clip the edit plays faster runs its zoom faster too, so a push that settled in real time pumps several times a beat.
+
+- Rebuild the beat's track for the playback rate with `canon take camera <dir>/log.json --rate <n> --out <file>`, and drive the wrapper from that file rather than from `camera.json`
+- Never scale `camera.json`'s times by hand, since the rebuilt track also keeps each push inside the 1 s ceiling at the new speed
+- Keep a typing beat at a rate where each word still reads, since a viewer cannot read a fill that finishes in a few frames
+
+## Storyboard headings
+
+- Write each frame heading as `## Frame N: title`, since the dash form in HyperFrames' `storyboard-format.md` example fails the markdown audit
+- Treat the parser's read of the colon form as assumed, since its lenient parse was not confirmed against its source
+- Title each frame as the beat the operator approved, so the frame, the take's folder, and the caption share one name a reader can follow across all three
+
+## The workspace README
+
+Step 5 writes the filming half of `.canon/video/<slug>/README.md`. The composing session adds its own half under its own heading.
+
+- Add how to re-render each project the workspace holds, naming its folder and the render command it runs
+- Name any track rebuilt with `--rate`, with the command that rebuilt it, since a re-film overwrites `camera.json` and leaves a rebuilt track stale
+- Leave the filming half as Step 5 wrote it, so the next session can re-film without reading the composition
+
+## Sources
+
+| Rule                        | Source                                                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Caption placement and scrim | HyperFrames' `captions.md`, adjusted for footage with chrome along its bottom edge                       |
+| A new project per shape     | `hyperframes-studio`'s brief step, which starts a new project for a different aspect                     |
+| The 1080x1080 window        | Frameboard's launch film, cut square from stepped takes                                                  |
+| The 2 MB WebP loop          | Frameboard's README hero, an animated WebP cut from a raw take, which played inline at 1.72 MB           |
+| Rebuilding a sped-up track  | `canon take camera --help`, whose `--rate` divides every time in the log                                 |
+| Storyboard heading form     | HyperFrames' `storyboard-format.md` and the markdown audit's character bans, with the colon read assumed |
+| The README's two halves     | Frameboard's workspace, whose README recorded how to re-film and re-render after a session ended         |