@erclx/canon 5.69.0 → 5.71.0

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

@@ -29,6 +29,7 @@ Governs the task files under `.canon/tasks/`: folder layout, filenames, frontmat
 Does not govern:
 
 - **`tasks-decline.md`**: the declined folder, the `Declined:` line, and what declining does to a plan and a board row
+- **`tasks-record-lines.md`**: the `Pull request:`, `Pending branch:`, and `Sessions:` lines a verb writes below the origin lines
 - **`board.md`**: execution order, readiness groups, the backlog, and the generated index beside the tasks
 - **`plan.md`**: the plan file a task cites, its sections, and its answer contract
 - **`versioning.md`**: phase-label format and which surfaces a label may appear on
@@ -112,6 +113,7 @@ Groundwork: [<slug>](../groundwork/<slug>/)
 Intake: [<slug>](../intake/<slug>/)
 Issue: #NNN
 Pull request: #NNN
+Sessions: <name> (<sessionId>)
 
 Why this task exists and what it depends on.
 
@@ -165,15 +167,9 @@ Three rules cover the line itself:
 - Use `Intake:` rather than `Groundwork:` for an intake pass, so the line records which kind of pass produced the task
 - `Intake:` names the folder rather than an item, and item numbers belong in the task's `## Findings`
 
-### The `Pull request:` line
+### The lines a verb writes
 
-`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
+`Pull request:` and `Sessions:` are not origins, so a task without them is well-formed. A verb writes each, and `${CLAUDE_SKILL_DIR}/references/tasks-record-lines.md` fixes what they mean and who calls the verb.
 
 ## What goes in
 

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         |

package/claude/skills/ui-film/references/config.md

@@ -28,7 +28,12 @@ access = "/write?token=demo"
 - An absent `access` opens the served root
 - `personas` and `proposals` belong to `app-drive`, and a take reads neither
 
-Every beat opens the address fresh in its own browser, so a link the app honors once, such as a single-use edit ticket, serves one beat alone. Mint a fresh link and run `canon take` once per beat for such an app, or a later beat opens the page without the access the first one spent.
+### Single-use access
+
+Every beat opens the address fresh in its own browser, so a link the app honors once, such as a single-use edit ticket, serves one beat alone. A beat that falls back to the screencast opens the address a second time, so the fallback spends the link too, even within one beat.
+
+- Point `access` at a local redirect minting a fresh link per request, so each open gets its own, the one pattern that held across beats and fallbacks alike
+- Run `canon take` once per beat with a freshly minted link only where no redirect can be served, with `"route": "screencast"` on each so no fallback reopens it
 
 ## When the file is absent
 

package/claude/skills/ui-film/references/handoff.md

@@ -14,7 +14,7 @@ Read at Step 5 of `ui-film`. Canon stops at the clip, and a HyperFrames composit
 | File          | Holds                                                                        |
 | ------------- | ---------------------------------------------------------------------------- |
 | `clip.mp4`    | H.264 at 60 fps, 3840x2160 when frame stepped, 1920x1080 when screencast     |
-| `log.json`    | Every move, click, typing burst, and scroll, with each target's box          |
+| `log.json`    | Every move, click, drag, key press, typing burst, and scroll, with its boxes |
 | `camera.json` | One camera per frame of the clip, with the cursor and the click ring         |
 | `still.jpg`   | The clip's closing frame, the check on each take, which no composition needs |
 
@@ -24,10 +24,10 @@ Every coordinate in the log and the track is in CSS pixels of a 1920x1080 page,
 
 Each frame carries `scale`, the view's top-left `x` and `y`, the `cursor`, and `ring`.
 
-- `scale` is 1 for the whole page and 1.8 at the deepest zoom
+- `scale` is 1 for the whole page and 1.8 at the deepest zoom, or about 1.35 on a screencast beat, and holds at 1 on a beat whose plan set `push: false`
 - `x` and `y` place the view's corner on the page, so the view spans `1920 / scale` by `1080 / scale` from there
 - `cursor` is the pointer's position on the page
-- `ring` runs from 0 to 1 across the 450 ms after a click and is `null` otherwise
+- `ring` runs from 0 to 1 across the 450 ms after a click and is `null` otherwise. On a drag it grows to 0.3, holds there from press to release, and runs on to 1 from the release.
 
 The track is final. It already carries the easing, the spring, and the hold, so a composition sets each frame's values and never tweens between them.
 
@@ -45,6 +45,14 @@ bunx -y hyperframes init .canon/video/<slug>/composition
 - Leave renders in the project's `renders/` folder, which `canon records push` skips along with `takes/`, `snapshots/`, `node_modules/`, and any video file
 - An image the composition adds under `assets/`, such as a logo, is backed up with the project's source
 
+A cut in another shape and the README loop are each a project of their own beside `composition/`, so one shape's edit never reflows another's. Each reads the takes from `../takes/` the same way.
+
+| Project                | Holds                                            |
+| ---------------------- | ------------------------------------------------ |
+| `composition/`         | The main cut, in the takes' 16:9 shape           |
+| `composition-<shape>/` | One other shape, such as `composition-square/`   |
+| `readme-loop/`         | The short silent loop a README plays as its hero |
+
 Compose from a session started at the main worktree root. From a linked worktree or an isolated background session, `Write` and `Edit` refuse every file in `composition/` and redirect to a worktree copy no later session reads, so never take that redirect.
 
 Where composing from the main root is not possible, write each file whole through the route `${CLAUDE_SKILL_DIR}/../session-worktree/references/main-root-writes.md` states.
@@ -62,6 +70,8 @@ The cursor stays outside the wrapper because a cursor inside it would scale with
 
 ## What the composition still owns
 
+Read `${CLAUDE_SKILL_DIR}/references/compose-craft.md` for the captions, the other shapes, the loop, and a sped-up clip, where app footage changes what HyperFrames advises.
+
 - The order and the cuts between takes, the captions, and any music or voice
 - Whether a take plays whole or trimmed. A trim keeps the track aligned only when it shifts the track by the same frames.
 - Motion blur stays off, by the operator's call on these takes

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

@@ -15,6 +15,7 @@ Read at Step 3 of `ui-film`, before writing the first beat. `canon take --help`
 - [Targets](#targets)
 - [The pointer](#the-pointer)
 - [The zoom](#the-zoom)
+- [The harness route](#the-harness-route)
 - [Sources](#sources)
 
 ## The plan
@@ -44,6 +45,13 @@ A plan holds the approved beats in order. Each beat names its setup, which runs
 - Reach the beat's start state through `setup`, since every beat opens the page fresh and nothing a setup step does is filmed
 - Write the beat's `name` as the operator approved it, since it names the clip's folder
 
+### Server state
+
+Every beat reloads the page, never the server. An app holding its state in server memory keeps a change one beat made, so the next beat opens on it.
+
+- Undo the change in the next beat's `setup`, or order the beats so each one's result is the next one's start
+- Restart the server between beats only when neither works, since a restart costs the served address its warm start
+
 ## Frame-stepping limits
 
 A step beat runs the page on a virtual clock, one frame per step. Most pages film this way, and some inputs are known to stall it.
@@ -52,10 +60,11 @@ A step beat runs the page on a virtual clock, one frame per step. Most pages fil
 - A scroll has not been proven under frame stepping, and a smooth scroll can jump. Give a scroll its own beat so a fallback costs that beat alone.
 - An animated GIF can freeze, so expect one to hold its first frame
 - Set `"route": "screencast"` on a beat known to stall, rather than paying for the stall before the fallback
+- Set a top-level `"route": "screencast"` on a plan whose page stalls on every beat, and a beat naming its own `route` keeps it
 
 A fallback films the beat again from a fresh load, replaying its setup and the steps the stepper already ran. A beat whose steps persist in the app, such as a fill that renames something, would then start from the changed state, so set `"route": "screencast"` on it when it risks a stall.
 
-A screencast beat films in real time at 1920x1080, which goes soft at the 1.8x zoom. Tell the operator which beats ran that way.
+A screencast beat films in real time at 1920x1080, so its camera zooms only to about 1.35x before it would go soft. Tell the operator which beats ran that way.
 
 ### Reading a take back
 
@@ -68,6 +77,7 @@ Two rules hold once a beat is filmed.
 
 - Prefer a stable attribute, such as an `aria-label`, a `data-testid`, or an `id`, over a position like `:nth-child`
 - Use `text=<words>` for a control whose only stable handle is its label
+- Target a control with no visible text, such as an icon button, by its `aria-label`, since `text=` finds nothing on it
 - Use a `move` to a point only for a target the page reveals on hover, and follow it with the click
 - Read each target off the served page before writing it. The verb refuses `target-missing` rather than filming a guess, and a refusal costs a reload.
 
@@ -86,6 +96,22 @@ The camera track already carries the zoom, so these rules decide what to film fo
 - Expect a target filling most of the view to get less zoom, and one filling the page to get none
 - The push reaches 90% of its depth in about 633 ms, inside the 1 s ceiling a push onto an action keeps
 
+### Depth, opt-out, and speed
+
+Three controls change the push itself.
+
+- Expect a screencast beat's zoom to stop near 1.35x, since its clip has one pixel per page pixel, and a stepped beat's to reach 1.8x
+- Set `"push": false` on a beat the edit holds wide, such as one showing a whole layout change. Its track keeps the cursor and the click ring and drops the zoom.
+- Rebuild a beat's track with `canon take camera <dir>/log.json --rate <n> --out <file>` for a clip the edit plays `n` times faster, so the zoom settles on the clock a viewer sees
+
+## The harness route
+
+A beat driven from outside the page, such as a drag between two windows or an input the step kinds lack, cannot run as `canon take` steps. Until the verb can run an outside script itself, film it through a harness.
+
+- Drive the beat from a Playwright script that records the page and writes a log in the shape of a take's `log.json`
+- Build its camera track from that log with `canon take camera <log> --out <file>`, so the composition applies it like any other take
+- Tell the operator which beats ran this way, since their clips carry the harness's resolution rather than the stepper's
+
 ## Sources
 
 | Rule                       | Source                                                                                                                                                   |

package/docs/index.md

@@ -8,5 +8,6 @@ subtitle: One-line reference for each doc in this folder.
 One-line reference for each doc in this folder.
 
 - [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.
+- [Target migrations](migrations/index.md): One-time moves a project scaffolded under an older toolkit makes before its next sync, split by whether a canon migrate verb runs them or a person makes them by hand.
 - [Target](target/index.md): Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
 - [Workflow](workflow/index.md): How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.

package/docs/migrations/by-hand.md

@@ -0,0 +1,107 @@
+---
+title: Target migrations by hand
+description: One-time moves and keep-or-delete calls a person makes by hand, which no canon migrate verb runs or detects
+category: Agent surface
+---
+
+# Target migrations by hand
+
+Each section is a move a project scaffolded before the change it names makes by hand, since no `canon migrate` verb runs it and `canon migrate status` never lists it. The moves a verb runs, and the order to run them in, are in [target migrations by verb](by-verb.md).
+
+## Back records up off this machine, once
+
+Run `canon records push` once a private repository exists. It prints the one-time setup command when it finds none, and `canon init` prints the same reminder.
+
+## Rename the pull request template headings, once
+
+The template headings are now `## Key changes` and `## Technical context`, and `canon labels scan` compares case exactly. Rename them in `.github/pull_request_template.md`, or delete it and run `canon tooling sync base . --write`.
+
+## Delete the retired snippets, once
+
+A project scaffolded while snippets installed may hold `.claude/snippets/` or a root `snippets/`.
+
+```bash
+canon sync --check . --json | jq '.reverse'
+```
+
+- `dropped` is the toolkit's copy, unchanged, so delete it
+- `unattributed` is often an edited copy, so read what changed first
+- `project` is the project's own content, so leave it
+
+From the registry the walk reports `historyUnavailable`, so check both paths by hand.
+
+## Stop calling the standards verb, once
+
+`canon standards <name>` is gone, and a call now fails with a too-many-arguments error. Replace each call with the skill that owns the standard, at `references/<name>.md`. <!-- canon-allow-reference: verb retired -->
+
+| Skill             | Standards                                                     |
+| ----------------- | ------------------------------------------------------------- |
+| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
+| `context-fold`    | `context`                                                     |
+| `canvas-board`    | `canvas`, `design` <!-- canon-keep-retired -->                |
+| `docs-sync`       | `docs`, `readme`                                              |
+| `draw-figure`     | `figures`, `mermaid`                                          |
+| `create-rule`     | `rule`                                                        |
+| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
+| `git-branch`      | `branch`, `slug`                                              |
+| `git-commit`      | `commit`, `versioning`                                        |
+| `git-pr`          | `pr`, `publish`                                               |
+| `markdown-craft`  | `markdown`                                                    |
+| `teach-workspace` | `glossary`, `teach` <!-- canon-keep-retired -->               |
+| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
+| `plan-intake`     | `intake`                                                      |
+| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
+| `plan-ready`      | `ready` <!-- canon-keep-retired -->                           |
+| `write-doc`       | `requirements`, `wiki`                                        |
+| `session-map`     | `session`                                                     |
+
+The `standard` name became `skill-reference.md` in `create-skill`.
+
+## Keep or delete the wireframes folder, your call
+
+The wireframes record is retired, and nothing deletes what a project holds.
+
+- `canon/wireframes/` stays yours and unaudited. Keep it as notes or delete it.
+- Delete the `@canon/wireframes/index.md` line in your `CLAUDE.md` with the folder. `canon claude sync` does not rewrite it.
+- `canon gov sync` removes `.claude/rules/canon/standards/wireframes.md`
+
+## Keep or delete the retired product files, your call
+
+The learning workspace, deck renderer, app recorder, canvas, and design install are retired with their verbs, and nothing deletes what a project holds.
+
+- `.canon/teach/` holds HTML that opens as it is <!-- canon-keep-retired -->
+- `.canon/slides/` and a `demos/` folder hold sources nothing renders any more, so delete them once nothing cites them <!-- canon-keep-retired -->
+- Move the `.claude/design/project/` values, `fonts/`, and `fonts.css` to the stylesheet your `canon/DESIGN.md` lead names, then delete `.claude/design/`
+
+A reference to a retired skill takes a hand edit.
+
+- Replace a `canon:teach-workspace` reference with `canon:teach-craft` by hand, since `canon migrate skill-names` does not rewrite it <!-- canon-keep-retired -->
+- Delete a `canon:make-deck`, `canon:script-screencast`, `canon:record-screencast`, `canon:read-frames`, or `canon:video-craft` reference, since none has a successor <!-- canon-keep-retired -->
+- Delete a `canon:canvas-board` reference too. Frameboard, which `canon:design-pick` drives, reads each `.canon/canvas/` folder as a project, so move a kept page under one <!-- canon-keep-retired -->
+
+## Move decisions out of a held architecture record, once
+
+The toolkit no longer seeds `canon/ARCHITECTURE.md`, and a held file and its `CLAUDE.md` import stay. Move a trap a session would hit into that domain's `## Gotchas`, then delete the file and its `@canon/ARCHITECTURE.md` line.
+
+## Move the capture cases out of the harness, once
+
+A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. A harness you edited is held on `--write`, so the new one lands only once you pass `--replace e2e/screenshot.ts`.
+
+- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts`, then sync with `--replace e2e/screenshot.ts`.
+- Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
+- A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
+
+## Fold the ui rules onto one pointer, once
+
+Eleven ui rules moved unchanged into the `ui-craft` skill, being `a11y`, `keyboard`, `pointer`, `forms`, `motion`, `ux-controls`, `ux-completeness`, `surface-capture`, `copy`, `interface-casing`, and `link-behavior`. Update the plugin, then sync, which folds each one you hold and `design-taste.md` onto one `craft.md` pointer without local edits.
+
+```bash
+canon gov sync .
+```
+
+## Group a long paths section in `CLAUDE.md`, once
+
+The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
+
+- Regroup the section by hand under H3s, each opening on a one-sentence lead.
+- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.

package/docs/migrations/by-verb.md

@@ -0,0 +1,118 @@
+---
+title: Target migrations by verb
+description: One-time moves a canon migrate verb runs, for a project scaffolded under an older toolkit, in the order canon migrate status lists them
+category: Agent surface
+---
+
+# Target migrations by verb
+
+Each section is a move a `canon migrate` verb runs once, for a project scaffolded before the change it names. Run `canon upgrade` first, then `canon migrate status --json` to list the moves still pending in the order to run them. A pending verb with no section here, such as `scratch-evidence` or `rename`, is in [migrate](../agents/migrate.md).
+
+`canon:target-update` is the guided path through both, running the moves in that order once you approve its preview. The moves no verb runs are in [target migrations by hand](by-hand.md), and the recurring sync that follows is in [target sync](../target/sync.md).
+
+## Move the records first, once
+
+Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.
+
+```bash
+canon tooling sync claude . --write
+canon migrate records --json
+canon migrate records --write --json
+```
+
+The first line takes the `.canon/` ignore entry. The second reports and the third applies, repointing files that cite a moved folder and deleting a `.gitignore` line `.canon/` covers, as `dropped`. A line naming an old path keeps it via `canon-keep-record-root` on that line or the nearest non-blank one above.
+
+Then sweep the citations inside the records, which the verb above never reaches.
+
+```bash
+canon migrate record-tree --json
+canon migrate record-tree --write --json
+```
+
+It covers `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. Read the report before `--write`. The record tree is untracked, and a wrong rewrite has no undo.
+
+## Move the design board to `board/`, once
+
+A pick round with no board named now drafts in `.canon/board/`, the folder Frameboard reads, rather than `.canon/canvas/`. Stop any `frameboard serve` on the old folder first.
+
+```bash
+canon migrate record-layout --json
+canon migrate record-layout --write --json
+```
+
+A project holding both folders gets a collision, and neither moves. A `board` key in `design.toml` naming `.canon/canvas` stays as written, so update it by hand.
+
+## Move rules off the flat layout, once
+
+Installed rules moved from `.claude/rules/<subdir>/` to `.claude/rules/canon/<subdir>/`. On the flat layout `canon gov sync` exits 0 reporting `No governance surfaces found in target`, and `canon gov install` lands a second copy.
+
+```bash
+canon migrate rule-layout --json
+canon migrate rule-layout --write --json
+```
+
+Run it once, ahead of `canon gov sync` or `canon gov install`.
+
+## Rename the skill citations, once
+
+Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` is now `canon:context-fold`. Five drafters merged into `write-doc`, seven `draft-` skills took verb-first names, and four joined their family. No old name keeps a pointer, and `canon migrate skill-names --write` moves a project. <!-- canon-keep-retired -->
+
+| Old name           | New name                                        |
+| ------------------ | ----------------------------------------------- |
+| `draft-doc`        | `write-doc` <!-- canon-keep-retired -->         |
+| `draft-figure`     | `draw-figure` <!-- canon-keep-retired -->       |
+| `draft-identity`   | `design-identity` <!-- canon-keep-retired -->   |
+| `draft-slides`     | `make-deck` <!-- canon-keep-retired -->         |
+| `draft-and-pick`   | `design-pick` <!-- canon-keep-retired -->       |
+| `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
+| `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
+| `pick-by-eye`      | `design-pick` <!-- canon-keep-retired -->       |
+| `ui-record`        | `ui-film` <!-- canon-keep-retired -->           |
+| `ux-audit`         | `ui-audit` <!-- canon-keep-retired -->          |
+| `ux-measure`       | `ui-measure` <!-- canon-keep-retired -->        |
+
+Replace a citation of a skill with no successor by hand, or delete the sentence.
+
+- `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare mention by hand. <!-- canon-keep-retired -->
+- `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request, so replace a bare mention by hand. <!-- canon-keep-retired -->
+- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
+- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, and `canon-feedback-triage` have no successor <!-- canon-keep-retired -->
+- `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, `ux-walkthrough`, and `plan-ready` have no successor <!-- canon-keep-retired -->
+
+The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
+
+- `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
+- `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
+
+Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack, naming a held hook with `--replace`.
+
+```bash
+canon gov sync
+canon tooling sync <stack> . --write
+canon migrate skill-names --json
+canon migrate skill-names --write --json
+```
+
+## Move the surfaces off `.claude/`, once
+
+`context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, now `canon/config/`, moved under `canon/`. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them.
+
+```bash
+canon migrate surface-roots --json
+canon migrate surface-roots --write --json
+```
+
+It moves each surface with `git mv` and repoints every tracked citation. No other command notices a surface left at `.claude/`.
+
+## Deny subagents and merges, and turn auto memory off, once
+
+The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
+
+```bash
+canon migrate session-defaults --json
+canon migrate session-defaults --write --json
+```
+
+The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
+
+The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.

package/docs/migrations/index.md

@@ -0,0 +1,14 @@
+---
+title: Target migrations
+subtitle: One-time moves a project scaffolded under an older toolkit makes before its next sync, split by whether a canon migrate verb runs them or a person makes them by hand.
+category: Agent surface
+---
+
+# Target migrations
+
+One-time moves a project scaffolded under an older toolkit makes before its next sync, split by whether a canon migrate verb runs them or a person makes them by hand.
+
+## Agent surface
+
+- [Target migrations by hand](by-hand.md): One-time moves and keep-or-delete calls a person makes by hand, which no canon migrate verb runs or detects
+- [Target migrations by verb](by-verb.md): One-time moves a canon migrate verb runs, for a project scaffolded under an older toolkit, in the order canon migrate status lists them

package/docs/target/index.md

@@ -10,7 +10,6 @@ Scaffold, sync, and migrate a toolkit-managed project, with worked setups for th
 
 ## Agent surface
 
-- [Target migrations](migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
 - [Target projects](projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 - [Target scenarios](scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
-- [Target sync](sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once
+- [Target sync](sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once, and update canon itself

package/docs/target/projects.md

@@ -84,11 +84,11 @@ Install one domain without re-running `canon init`.
 - A project-specific rule: invoke `canon:create-rule`, which writes into `.claude/rules/project/`. A rule under `.claude/rules/canon/` is deleted on the next sync.
 - An `index.md` system for a markdown-heavy folder: invoke `canon:target-setup indexes`
 
-For a leftover `.claude/snippets/` see [target migrations](migrations.md).
+For a leftover `.claude/snippets/` see [target migrations by hand](../migrations/by-hand.md).
 
 ## Sync upstream drift
 
-A project scaffolded before a layout move runs the one-time moves in [target migrations](migrations.md) first. [Target sync](sync.md) covers reading drift and running a sync. [Target scenarios](scenarios.md) walks three worked setups.
+A project scaffolded before a layout move runs the one-time moves in [target migrations](../migrations/index.md) first. [Target sync](sync.md) covers reading drift and running a sync. [Target scenarios](scenarios.md) walks three worked setups.
 
 ## Related