@erclx/canon 5.21.0 → 5.22.0

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

@@ -0,0 +1,76 @@
+---
+title: Orchestrator cloud launch
+description: The cloud build shape, being the launch prompt that carries the plan as text and announces over GitHub, the create under a pseudo-terminal with its trust keys, and the readout that fails loudly on a missing session id
+---
+
+# Orchestrator cloud launch
+
+Run this once `orchestrator-dispatch.md` has cleared a row and picked cloud for it. The worker runs on a Claude Code cloud VM that clones the repository from GitHub, loads no plugin, and cannot see this machine's `.canon/`.
+
+The shape needs a `SessionStart` hook in the repository that, on the VM alone, copies the plugin skills into `.claude/skills/` and puts `canon` on the path. A repository without one cannot take this shape, so fall back to a local worker there. Where the hook exists, the launch prompt calls `/auto-ship` with no `canon:` prefix, since the copied skills list as project skills.
+
+## Check the row is unclaimed
+
+A cloud worker never appears in `canon sessions list` and never pushes the derived branch, since the cloud assigns it a `claude/` branch of its own. So the roster and the refs read clear on a row a cloud worker is already building. Run the local check in `orchestrator-dispatch.md` anyway, since a local worker on the same row still collides, then read the two places a cloud worker does show:
+
+```bash
+prs=$(gh api 'repos/{owner}/{repo}/pulls?state=open&per_page=100' --jq '.[] | select(.head.ref | startswith("claude/")) | .number') || { echo 'unreadable: the open pull request list'; exit 1; }
+found=$(printf '%s\n' "$prs" | while IFS= read -r n; do
+  [ -n "$n" ] || continue
+  bodies=$(gh api "repos/{owner}/{repo}/issues/$n/comments" --jq '.[].body') || { echo "unreadable: the comments on #$n"; exit 1; }
+  if printf '%s\n' "$bodies" | grep -qE '^(ANNOUNCE|QUESTION): plan <slug>([^a-z0-9-]|$)'; then echo "claimed: #$n"; fi
+done) || { printf '%s\n' "$found" | grep '^unreadable'; exit 1; }
+printf '%s\n' "${found:-clear}"
+```
+
+The prompt below has the worker open its `ANNOUNCE:` and `QUESTION:` comments with `plan <slug>`, so the comment is where a cloud pull request names its row. A title or body cannot, since `git-pr` writes both from the diff. Ending the match at a character no slug carries keeps `log` from claiming `log-entry`.
+
+Branch on the line it prints rather than on the exit, which a shell function wrapping a command can flatten to zero:
+
+- `claimed: #<n>`: a cloud worker's pull request names the plan slug. Treat the row as claimed and report each number.
+- `clear`, and this pass's launched record holds no cloud session for the row: the row is clear of cloud workers.
+- `unreadable: <what>`: the list or a comment read failed, so nothing was checked. Treat the candidate as unverified and fall back to the human-launch line, the same as a refused local check in `orchestrator-dispatch.md`. Never read it as clear, since an empty answer from a failed read is the collision this check exists to catch.
+
+The launched record covers the minutes before the pull request opens, when nothing on GitHub names the row yet. It is this session's alone, so a second dispatcher sees only the pull request list, which is the window `orchestrator-dispatch.md` already states for local workers under `## Hold what this pass already launched`.
+
+## The prompt
+
+Write the prompt to `.canon/tmp/cloud-<slug>/prompt.md` at the main worktree root, with the command at position zero, per `### Position zero` in `orchestrator-launch.md`:
+
+```plaintext
+/auto-ship .canon/plans/feature-<slug>.md
+Before Step 1 reads it, write the plan below verbatim to .canon/plans/feature-<slug>.md, creating the folder. That folder is gitignored, so it stays out of every commit. Stay on the branch this session was given, since a cloud session may push only to its own claude/ branch, so skip the worktree entry and the branch rename, and open the pull request from that branch although its name does not follow the branch convention git-pr checks.
+Your controller cannot receive a message from this session. Announce on GitHub instead, naming the repository <owner>/<repo> in every comment. When the pull request opens, comment on it starting with ANNOUNCE: plan <slug>, then the number, the branch, the head sha, the CI state, and every point you departed from the plan on. If the chain stops after the pull request opens, post that comment anyway and name the stop. If you stop on a question before a pull request exists, push what you have, open a draft pull request through the REST create with draft=true, since the draft mark cannot run here, and comment on it starting with QUESTION: plan <slug>.
+Before you finish, read the pull request's live body and delete every line carrying claude.ai/code/session_, since the label scan fails on one.
+<the plan file, verbatim>
+```
+
+The plan travels as text because the VM has no `.canon/` and the orchestrator alone writes the board, so nothing syncs the record across. `auto-ship` Step 1 then reads it at the path the command names, the same as on a local worker.
+
+## The create
+
+`claude --cloud` refuses without a terminal, so the create runs under `script`, which supplies one:
+
+```bash
+dir=.canon/tmp/cloud-<slug>
+timeout 150 script -qec "claude --cloud \"\$(cat $dir/prompt.md)\"" "$dir/create.typescript" < <(sleep 30)
+session=$(grep -A 2 'Created cloud session:' "$dir/create.typescript" | grep -o 'session_[A-Za-z0-9]*' | head -n 1)
+[ -n "$session" ] || { printf 'No cloud session id in %s. Nothing was dispatched.\n' "$dir/create.typescript" >&2; exit 1; }
+printf 'session=%s\n' "$session"
+```
+
+Run it from the main worktree root, since the session targets whichever repository that checkout's `origin` names. That folder is already trusted, so the create screen shows no trust prompt. From a checkout this machine has not trusted, such as a fresh clone of another repository, the screen asks first, and piped keys answer it: replace `<(sleep 30)` with `<(sleep 4; printf '\033[B'; sleep 1; printf '\r'; sleep 30)`. Either way stdin stays open for the create, which is the shape the wrapper was measured in, since an early end of input can reach the terminal before the create screen settles.
+
+The readout is the text `Created cloud session: <title>`, unanchored since a terminal capture can open a line with escape codes, followed by a `View:` address carrying the `session_...` id. Anything else is a failed create, including a run that exits zero. Report the typescript's last lines and fall back to the human-launch line in `orchestrator-dispatch.md` rather than recording a session that does not exist. The wrapper is a stopgap: any change to the interactive create screen breaks it, which is why the readout fails loudly instead of guessing.
+
+Record `session` beside the row's branch in this pass's launched record. A cloud worker never registers in `canon sessions list`, so that record and the pull request list are the only two readings that know it exists. Report the dispatch the way 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
+
+A cloud worker cannot message this session and never appears in the roster `watch.ts` reads, so its pull request and its `ANNOUNCE:` comment are the announcement. Start the poll in `orchestrator-poll.md` when the cloud dispatch goes out, rather than at that runbook's thirty-minute fallback. A pull request on a `claude/` head is this row's when one of its commits carries a `Claude-Session:` trailer naming the session id the create recorded:
+
+```bash
+gh api 'repos/{owner}/{repo}/pulls/<number>/commits' --jq '.[].commit.message' | grep -c 'Claude-Session:.*<session>'
+```
+
+A count above zero matches the row. A count of zero is someone else's pull request, whatever its title says. Once it matches, record the number on the row's task yourself with `canon tasks pull-request <number> <task>`, since `git-pr` on the VM has no task file to write, then review it the way step 5 reviews any worker's pull request.

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

@@ -54,6 +54,10 @@ Reading `claimed` off the record is what keeps this a check rather than a rule a
 
 What the ref read cannot see is a branch pushed from another machine since the last fetch, because it reads the remote-tracking ref rather than the remote. Nobody has hit that, and a `git ls-remote` per dispatch costs 0.438s against 0.001s, so the gap is recorded rather than closed.
 
+### A cloud worker's claim
+
+A cloud worker never appears in the roster and never pushes the derived branch, so run the local check above and then the cloud claim in `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` before a cloud dispatch.
+
 ## Hold what this pass already launched
 
 A worker registers with `branch: main` and the main worktree as its `cwd` until `auto-ship` Step 0 moves it, which took several seconds on both measured runs. Neither the roster nor the refs name the candidate during that window, so a second check inside it reads clear.
@@ -82,9 +86,15 @@ A `claude --bg` session inherits the model of whatever launched it rather than r
 
 Name `<model>` on the launch, and pick it against the task rather than copying whatever this session happens to run. Sizing the model to the row is the dispatcher's call, the same call it already makes on the branch. A mechanical row moving files under a written plan is not the row that needs the largest model, and one whose plan carries an open judgment is.
 
+## Pick local or cloud
+
+Dispatch to a cloud worker only on the operator's explicit pick for that dispatch, until three cloud rows have merged. Whether a cloud session is worth its cost is the operator's account to judge, and the review load a cloud pull request adds is unmeasured, so the pick stays a person's until that count gives a reading.
+
+A row qualifies for that pick when its plan carries no open question and touches no surface needing local state, such as the sandbox, the records remote, or a browser. A cloud worker cannot reach any of the three, and it cannot ask the operator mid-build except through a draft pull request.
+
 ## Dispatch
 
-Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template. It also holds the review-address and planning shapes, which skip the checks above.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template. That runbook also holds the review-address and planning shapes, which skip the checks above. A row the operator picked for cloud launches from `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` instead, since the cloud VM shares neither the plugin nor the board with this machine.
 
 ## Fall back to the human
 

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, review-address, planning, reviewer, and UI reviewer 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, planning, reviewer, and UI reviewer templates, 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, review-address, or reviewer shape below when that runbook's checks do not bind. The model each template names comes from `## Pick the model` in that runbook.
@@ -49,6 +49,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: name the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
+## 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.
+
 ## Dispatch to address a review
 
 `review-address` is a single pass, not a chain, so a launch naming it alone reaches no `role-worker` and takes no role, which owes no message either. Reach the role directly on this launch instead of wrapping a second chain around one skill that has none of its own.

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

@@ -7,7 +7,7 @@ description: Why a session needs a thinking step before an outside search, deriv
 
 ## Gap
 
-Without this skill, a session reaching outside the project runs one generic `WebSearch` and takes what ranks highest. Nothing in the toolkit says how to search, and the two procedures that require an outside source, `plan-groundwork` and `draft-wiki`, give no route to one.
+Without this skill, a session reaching outside the project runs one generic `WebSearch` and takes what ranks highest. Nothing in the toolkit says how to search, and the two procedures that require an outside source, `plan-groundwork` and `draft-doc`'s wiki kind, give no route to one.
 
 The miss is measured. On 2026-10-02 two queries ran twice each with identical text, once open and once with `allowed_domains` set to authorities the session derived itself with no list to consult.
 
@@ -30,7 +30,7 @@ Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit ref
 - Prefer a public API over a fetched and summarized page where one exists, since the API returns the dates, authors, and identifiers a citation needs
 - Carry a dated access note grown only from a failure a session hit, and stop to ask the operator before any paid or logged-in route
 - Close with the practice skill's excuses, red flags, and closing checklist, answering "the model already knows the good sites" and "one search was enough"
-- Be loaded from the sourcing steps of `plan-groundwork` and `draft-wiki`, each reporting when the skill does not resolve
+- Be loaded from the sourcing steps of `plan-groundwork` and `draft-doc`'s wiki kind, each reporting when the skill does not resolve
 
 ## Must not
 
@@ -42,7 +42,7 @@ Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit ref
 ## Out of scope
 
 - The form a citation takes: the procedure or standard writing it
-- A Claude Code subject: the `claude-code-guide` agent, which `draft-wiki` already routes to
+- A Claude Code subject: the `claude-code-guide` agent, which `draft-doc`'s wiki sourcing step already routes to
 - Image generation, which makes a picture rather than finding a source
 - Loading on every web search rather than on a research-shaped request: a hook matching `WebSearch`, planned on its own
 - Whether a session already scopes searches without the skill, which only a run on a fresh research request without it would show
@@ -54,4 +54,4 @@ Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit ref
 - No `Skill` call fired, so the description did not route a plain research request to the body.
 - The run searched four times with no domain filter, naming authors and journals from recall, then fetched the papers' own pages. It never named the field, so the scenario's field pattern failed and the arm went red on one of its assertions.
 
-The arm shows the trigger is the gap rather than the body: a session that never loads the skill cannot follow it. The pointers from `plan-groundwork` and `draft-wiki` reach only those procedures, and the hook matching `WebSearch` is the route for every other search. One run on one model shows the miss exists and does not size it.
+The arm shows the trigger is the gap rather than the body: a session that never loads the skill cannot follow it. The pointers from `plan-groundwork` and `draft-doc`'s wiki kind reach only those procedures, and the hook matching `WebSearch` is the route for every other search. One run on one model shows the miss exists and does not size it.

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

@@ -78,6 +78,6 @@ Each line is a claim measured once, and `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` rec
 ## What this delegates
 
 - The form a citation takes: the surface writing it, such as the standard the procedure writes to
-- A Claude Code subject: the `claude-code-guide` agent, which `draft-wiki` routes to
+- A Claude Code subject: the `claude-code-guide` agent, which `draft-doc`'s wiki sourcing step routes to
 - Generating an image: whatever draws the surface, since making one is not search
 - Access code a session needs repeatedly: a `canon` verb, never a script in this skill

package/docs/agents/commands.md

@@ -130,7 +130,7 @@ Subcommands no other page describes:
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
 - `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
 - `slides render --source <folder>` lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
-- A deck folder's `deck.json`, its per-slide `<body>` attributes, speaker notes, and charts are described in `slides.md`.
+- A deck folder's `deck.json` and the faces it embeds, its per-slide `<body>` attributes, transitions and entrances, speaker notes, and charts are described in `slides.md`.
 - `canvas`, with its verbs, content format, and write routes, is described in `canvas.md`.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
 - `repo metadata propose` compares a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing, and `repo metadata apply` writes an explicitly supplied set through `gh repo edit` (`--description`, `--homepage`, `--topics`).

package/docs/agents/drift-surfaces.md

@@ -1,19 +1,19 @@
 ---
 title: Drift surfaces
-description: The six sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
+description: The seven sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, surfaces at the old root, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
 ---
 
 # Drift surfaces
 
-`canon sync --check` reports six sections outside the per-domain scan that
+`canon sync --check` reports seven sections outside the per-domain scan that
 `install-and-sync.md` describes, because each names something
-that walk cannot see: `seeds`, `superseded`, `unmigrated`, `newSkills`,
-`newRules`, and `reverse`. None of them produces a change, and no sync command
-applies any of them. The headings below group the first three together and give
-`newSkills` its description under `newRules`, which answers the same question
-about a different corpus.
+that walk cannot see: `seeds`, `superseded`, `unmigrated`, `unmovedSurfaces`,
+`newSkills`, `newRules`, and `reverse`. None of them produces a change, and no
+sync command applies any of them. The headings below group the first four
+together and give `newSkills` its description under `newRules`, which answers the
+same question about a different corpus.
 
-All six report only against a toolkit-managed target, which is one carrying a
+All seven report only against a toolkit-managed target, which is one carrying a
 `.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
 report says so through `managed` in the JSON and routes an unmanaged directory to
 `canon init`. Seeds are why the gate exists, since they enumerate from the toolkit
@@ -26,7 +26,7 @@ toolkit installed. When `managed` is false every section comes back empty rather
 than the render alone going quiet, so a consumer reading `--json` never acts on a
 finding the rendered half withheld.
 
-## Seeds, superseded artifacts, and unmigrated domains
+## Seeds, superseded artifacts, unmigrated domains, and old-root surfaces
 
 `seeds` classifies every seed the toolkit ships against the target's copy, as
 `matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
@@ -68,6 +68,13 @@ Nothing proposes moving it, and no command relocates the content. Move it
 yourself. A leftover `snippets/` folder reports under the reverse walk instead,
 where `docs/target/sync.md` says what to do with it.
 
+`unmovedSurfaces` names a tracked surface the target still holds at its `.claude/`
+spelling with nothing at the `canon/` one, such as `.claude/REQUIREMENTS.md` or
+`.claude/context/`. Each entry carries `rel` and `movesTo`, and the render names
+`canon migrate surface-roots`, the verb that moves them. Rules glob the `canon/`
+spelling alone, so a target on the old root stops loading the rules scoped to
+those files until it moves. <!-- canon-keep-surface-root -->
+
 ## Rules the target never received
 
 `newRules` names a rule the target could receive and its tree does not hold. A
@@ -182,6 +189,10 @@ toolkit shipped and the target renamed goes unmatched, the same limit the
 is: only the user can move content they wrote, so failing a job on it leaves the
 job red with no mechanical remedy.
 
+`unmovedSurfaces` is excluded although `canon migrate surface-roots` closes it.
+The move rewrites citations across the project, so it is a change the project
+schedules, and a job counting it would go red the day a target updated the CLI.
+
 `newRules` is excluded on a different ground, since a command does close it. What
 excludes it is that installing a rule changes what a project is governed by, so
 gating on the count would pressure a target into adopting rules nobody chose.

package/docs/agents/index.md

@@ -22,7 +22,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
 - [Design board](design-board.md): Generating a static index over a project's design surfaces, what each panel reads, and which two stay toolkit-checkout-only
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
-- [Drift surfaces](drift-surfaces.md): The six sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
+- [Drift surfaces](drift-surfaces.md): The seven sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, surfaces at the old root, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
 - [Hooks](hooks.md): Running the post-merge steps through one verb, the order and the child call behind each, the root and working directory each step reads, the skip switches, and the line each record maps to
@@ -55,7 +55,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
 - [Skill audit](skills-audit.md): Measuring both skill corpora against the skill standards, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
-- [Slides](slides.md): What a folder of HTML slides declares for the whole deck in deck.json, what each slide declares on its own body, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+- [Slides](slides.md): What a folder of HTML slides declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 - [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates

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

@@ -233,9 +233,9 @@ edit and a job counting those stays red with no remedy.
 
 ### Surfaces reported beside the domains
 
-Six sections sit outside the per-domain scan, because each names something
-that walk cannot see: `seeds`, `superseded`, `unmigrated`, `newSkills`,
-`newRules`, and `reverse`. None of them produces a change, and no sync command
+Seven sections sit outside the per-domain scan, because each names something
+that walk cannot see: `seeds`, `superseded`, `unmigrated`, `unmovedSurfaces`,
+`newSkills`, `newRules`, and `reverse`. None of them produces a change, and no sync command
 applies any of them. What each reports, the managed-target gate they share, and
 which count toward `--exit-code` are in `drift-surfaces.md`.
 

package/docs/agents/migrate.md

@@ -9,7 +9,7 @@ description: What each canon migrate verb moves and rewrites, what it refuses, t
 
 `migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
 
-`migrate skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It carries two plain renames as well, where a skill carried no prefix and changed its name because the old one described a job it no longer does, landing on `ui-checklist` and `context-fold`, and it leaves the pointer answering under the fold skill's old name in place. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then.
+`migrate skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It carries two plain renames as well, where a skill carried no prefix and changed its name because the old one described a job it no longer does, landing on `ui-checklist` and `context-fold`, and one merge, where the five per-kind document drafters land on `draft-doc`. It leaves the pointer answering under the fold skill's old name in place. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then.
 
 `migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
 

package/docs/agents/rule-citations.md

@@ -59,7 +59,7 @@ The extension test is what carries most of the separation, and it costs one real
 
 Two classes resolve to nothing and are right to. Both are reported by name rather than dropped, so a reader can see what the verdict declined to judge.
 
-**Governed.** A rule spelling a path in its own frontmatter `paths:` is naming an artifact a target holds rather than a file here. `governance/rules/standards/diagrams.md` declares `.claude/DIAGRAMS.md` and then tells its reader to convert one an older install left behind, so the file is correctly absent from this tree and correctly named in the rule.
+**Governed.** A rule spelling a path in its own frontmatter `paths:` is naming an artifact a target holds rather than a file here, so the file is correctly absent from this tree and correctly named in the rule. No shipped rule declares one today, and the stage's test fixtures carry the instance that keeps the class exercised.
 
 Only an exact declaration exempts, never a glob match against one. A glob declares a shape, so a body path sitting inside it is still a citation and a stale one is still a defect. A rule scoped at `docs/**` citing a `docs/agents/renamed.md` that moved is exactly the class this stage exists to catch, and matching the glob would excuse it.
 

package/docs/agents/slides.md

@@ -1,6 +1,6 @@
 ---
 title: Slides
-description: What a folder of HTML slides declares for the whole deck in deck.json, what each slide declares on its own body, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+description: What a folder of HTML slides declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 ---
 
 # Slides
@@ -22,13 +22,18 @@ canon slides render --source slides/q3-review
 | `footer`       | on, with the title on the left | a band at the bottom, with the same three slots   |
 | `slideNumbers` | `true`                         | the number at the right of the footer             |
 | `mark`         | none                           | an image path, relative to the folder, top right  |
+| `fonts`        | none                           | faces to embed in the file, described below       |
 
 ```json
 {
   "title": "Q3 review",
   "header": { "left": "Acme" },
   "footer": { "center": "Internal" },
-  "mark": "assets/mark.png"
+  "mark": "assets/mark.png",
+  "fonts": [
+    { "family": "Inter", "path": "fonts/Inter-Regular.ttf" },
+    { "family": "Inter", "weight": 700, "path": "fonts/Inter-Bold.ttf" }
+  ]
 }
 ```
 
@@ -38,6 +43,17 @@ Slide numbers belong to the footer and hold its right slot. They show only where
 
 Prefer a raster mark. An SVG mark lands as a vector, and its fallback for a viewer that cannot draw SVG comes out broken.
 
+### Embedded faces
+
+Each entry in `fonts` names one TrueType or OpenType file inside the deck folder, and the deck carries it so it renders in its own face on a machine without the font installed.
+
+- `family` is required and should match the family the slides set, since that is the name PowerPoint looks the face up by.
+- `weight` defaults to `400`. PowerPoint holds four faces a family, so `600` and above fills the bold slot and anything lighter fills regular.
+- `style` is `normal` or `italic`, defaulting to `normal`.
+- `path` is relative to the folder and has to stay inside it.
+
+A face is refused, and the deck still written without it, when its license forbids embedding or allows a bitmap only, when it is a variable font, when it is a `woff` or `woff2` file, or when a second face lands in a slot one already fills. Supply static instances, one per weight, in place of a variable face. For `woff2`, supply the TrueType or OpenType file it was compressed from, which most font downloads ship beside it.
+
 ## What each slide declares
 
 A slide sets its own place in the deck through attributes on `<body>`.
@@ -55,6 +71,30 @@ Once any slide opens a section, slides ahead of the first one sit in a section n
 
 A slide dropping one band keeps the other from the master. A slide replacing a slot draws its band as its own text, so editing that band once in PowerPoint's master view reaches every slide except the ones that replaced it.
 
+## Motion
+
+A slide declares how it arrives on `<body>`, and an element declares how it comes in on its own tag.
+
+| Attribute                  | Takes                           | Effect                                 |
+| -------------------------- | ------------------------------- | -------------------------------------- |
+| `data-transition`          | `fade`, `push`, `wipe`, `cover` | the transition into this slide         |
+| `data-transition-duration` | `500`, `500ms`, or `0.5s`       | rounded to 0.5, 0.75, or 1 second      |
+| `data-enter`               | `fade`, `fly`, `wipe`, `zoom`   | an entrance played on a click          |
+| `data-enter-order`         | a number                        | the click it plays on, lowest first    |
+| `data-enter-duration`      | `500`, `500ms`, or `0.5s`       | the entrance length, 500 ms by default |
+
+```html
+<body data-transition="fade">
+  <h1>Results</h1>
+  <div class="card" data-enter="fly" data-enter-order="1">…</div>
+  <div class="card" data-enter="fly" data-enter-order="2">…</div>
+</body>
+```
+
+Each entrance is its own click. Entrances without an order play after the ordered ones, in page order. An entrance brings in every shape drawn from its element and the elements inside it together, so a card's box and its text arrive on one click, and an element drawn as a picture brings in that picture. An element inside it with its own `data-enter` waits for its own click. Fly comes in from the bottom and wipe from the left.
+
+A transition length rounds to the nearest of the three speeds PowerPoint's file format names, since a length in milliseconds needs an extension the deck does not write.
+
 ## The master
 
 The master takes its colors from the `<html>` element of the first slide as Chromium laid it out with the project's token stylesheet injected, so a theme switched on one slide's `<body>`, such as a dark cover, stays on that slide:
@@ -112,9 +152,13 @@ A `<figure data-chart="...">` holding a `<table>` becomes a native, editable cha
 | -------------------------------------- | ---------------------------------------------- | ---- |
 | `deck.json` field malformed or unknown | `✗` naming the file and the field              | 1    |
 | `mark` path missing                    | `✗` naming the resolved path                   | 1    |
+| `fonts` path missing or outside folder | `✗` naming the field and the path              | 1    |
+| face not embeddable                    | `✗` naming the path and the reason             | 0    |
+| unknown transition or entrance name    | `✗` naming the slide, the element, the effect  | 0    |
+| entrance on an element that draws none | `✗` naming the slide and the element           | 0    |
 | chart cell not a number                | `✗` naming the slide, the figure, and the cell | 0    |
 | `data-chart` outside the five types    | `✗` naming the value                           | 0    |
 | token role not declared                | `✗` naming the role                            | 0    |
 | slide body sets its own `--color-text` | `✗` naming the slides                          | 0    |
 
-A refused chart is left out and the rest of the deck is written.
+A refused chart, effect, or face is left out and the rest of the deck is written.

package/docs/agents/tasks.md

@@ -64,7 +64,7 @@ Run from a branch other than `main` or `master`, the verb also drops that branch
 
 Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, or `ambiguous`. `git-pr` skips silently on those three, because each is a case where a guessed write would archive the wrong task once the branch merges.
 
-A malformed argument refuses as `bad-input` instead, which sits outside that set on purpose. `git-pr` derives the number by slicing whatever `gh pr create` printed, so a non-numeric value is reachable, and folding it into the swallowed set would lose the number with nothing reporting it.
+A malformed argument refuses as `bad-input` instead, which sits outside that set on purpose. `git-pr` derives the number by slicing the address the create call returned, so a non-numeric value is reachable, and folding it into the swallowed set would lose the number with nothing reporting it.
 
 ## Outcome
 

package/docs/target/migrations.md

@@ -62,7 +62,9 @@ The first line reports the plan and the second applies it, relocating each rule
 
 Twenty-five plugin skills dropped their `claude-` prefix for two-word names, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. A project that installed governance or tooling before that release holds files naming the old ones, and the plugin answers to none of them. A later release renamed `docs-fold` to `context-fold`, since the skill folds a session into the context entries and the task board rather than into `docs/`, and the same sweep carries a project across that rename too. The pointer that answered under the old name no longer ships, so a citation the sweep has not reached names nothing. <!-- canon-keep-retired -->
 
-Two of those files run rather than sit there. `.husky/post-merge` runs the `canon hooks post-merge` verb, so a stale copy of the hook calls a binary that may lack it, and `.claude/hooks/pr-create-log.sh` hands a session a message naming a skill, so a stale copy tells someone to invoke something that no longer exists. A rule under `.claude/rules/canon/core/` names skills too, though a rule is read rather than run.
+The same sweep carries the merge of the five per-kind document drafters into `draft-doc`, so a citation of any one of them lands on `canon:draft-doc`.
+
+Two of those files run rather than sit there. `.husky/post-merge` runs the `canon hooks post-merge` verb, so a stale copy of the hook calls a binary that may lack it, and `.claude/hooks/pr-create-log.sh` hands a session a message naming a skill, so a stale copy tells someone to invoke something that no longer exists. A copy older than `git-pr`'s move to REST also matches only `gh pr create`, so it stays silent on every pull request `git-pr` opens. A rule under `.claude/rules/canon/core/` names skills too, though a rule is read rather than run.
 
 Resync what the toolkit owns, then sweep what the project wrote:
 

package/docs/target/sync.md

@@ -28,7 +28,7 @@ Each domain holds its own toolkit commit, so syncing governance today does not m
 
 A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
-Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `canon:seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.canon/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated`, and no command moves it either. The project moves the content itself.
+Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `canon:seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.canon/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated`, and no command moves it either. The project moves the content itself. A surface still at its `.claude/` spelling with nothing under `canon/`, such as `.claude/REQUIREMENTS.md`, is reported under `unmovedSurfaces`, since rules glob the `canon/` spelling alone, and `canon migrate surface-roots` moves it. <!-- canon-keep-surface-root -->
 
 `unmigrated` currently names no domain, since standards and snippets are the two the toolkit ever installed at the project root, standards closed its install channel, and snippets retired outright. A target still holding a root `standards/` folder from an older toolkit is carrying its own authoring surface now, not an unfinished install, and nothing proposes moving it. A leftover `.claude/snippets/` reports under `reverse` below instead.
 

package/docs/workflow/skill-map.md

@@ -118,24 +118,20 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## Generate an artifact on demand
 
-| Skill                     | When to use                                                                                                       |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                  |
-| `canon:create-skill`      | For a new `SKILL.md`                                                                                              |
-| `canon:create-standard`   | For a new authoring convention                                                                                    |
-| `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                                             |
-| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task         |
-| `canon:draft-context`     | For a brand-new `canon/context/<domain>.md` entry, drafted against `standards/context.md`                         |
-| `canon:draft-wireframes`  | For a brand-new `canon/wireframes/<surface>.md` file, drafted against `standards/wireframes.md`                   |
-| `canon:draft-wiki`        | For a brand-new wiki reference page on a subject owned outside the project, drafted against `standards/wiki.md`   |
-| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` in Mermaid or freehand SVG |
-| `canon:draft-readme`      | For a project's `README.md`, drafted against `standards/readme.md`                                                |
-| `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                    |
-| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                |
-| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                             |
-| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                     |
-| `canon:record-screencast` | For recording a screencast draft, then composing the take into a finished mp4 when the draft asks for a wrap      |
-| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                       |
+| Skill                     | When to use                                                                                                                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                                               |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                                                                           |
+| `canon:create-standard`   | For a new authoring convention                                                                                                                 |
+| `canon:draft-doc`         | For a brand-new `docs/` page, context entry, wireframe surface, wiki reference page, or `README.md`, drafted against the standard for its kind |
+| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                                      |
+| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` in Mermaid or freehand SVG                              |
+| `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                                                 |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                                             |
+| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                                                          |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                                                  |
+| `canon:record-screencast` | For recording a screencast draft, then composing the take into a finished mp4 when the draft asks for a wrap                                   |
+| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                                                    |
 
 ## Answer a question at any point
 

package/governance/rules/canon/604-scratch.md

@@ -7,4 +7,3 @@ description: Write temporary files to the scratch folder structure
 ## Temporary files
 
 - Write temporary files to `.canon/tmp/<slug>/<file>.md` at the current worktree's root, a nested folder with a kebab-slug tied to the topic rather than a flat `<slug>-<file>.md`. The slug must not take one of the five reserved names `runs`, `hooks`, `handoff`, `pr`, and `render`. A skill that resolves a write at the main root instead states so in its own body.
-- Write to `.claude/.tmp/<slug>/` instead in a project that carries no `.canon/` root, and `canon migrate records` moves it to the first spelling. <!-- canon-keep-record-root -->

package/governance/rules/claude/575-hooks.md

@@ -1,8 +1,7 @@
 ---
-description: State the hook stdin guard and the silencing rule for .claude/hooks scripts and their seeded copies
+description: State the hook stdin guard and the silencing rule for .claude/hooks scripts
 paths:
   - '.claude/hooks/**/*.sh'
-  - 'tooling/claude/seeds/.claude/hooks/**/*.sh'
 ---
 
 # Hook standards

package/governance/rules/claude/576-settings.md

@@ -1,8 +1,7 @@
 ---
-description: State the autoContinueAtUsageLimit inversion and the autoCompactWindow cap for .claude/settings.json and its seeded copy
+description: State the autoContinueAtUsageLimit inversion and the autoCompactWindow cap for .claude/settings.json
 paths:
   - '.claude/settings.json'
-  - 'tooling/claude/seeds/.claude/settings.json'
 ---
 
 # Settings standards

package/governance/rules/standards/architecture.md

@@ -3,7 +3,6 @@
 description: Shape and content rules for canon/ARCHITECTURE.md
 paths:
   - 'canon/ARCHITECTURE.md'
-  - '.claude/ARCHITECTURE.md'
 ---
 
 # Architecture standards

package/governance/rules/standards/context.md

@@ -3,7 +3,6 @@
 description: Shape and content rules for canon/context/<domain>.md entries
 paths:
   - 'canon/context/**'
-  - '.claude/context/**'
 ---
 
 # Context entry standards

package/governance/rules/standards/design.md

@@ -3,7 +3,6 @@
 description: Shape and content rules for canon/DESIGN.md
 paths:
   - 'canon/DESIGN.md'
-  - '.claude/DESIGN.md'
 ---
 
 # Design standards

package/governance/rules/standards/diagrams.md

@@ -3,7 +3,6 @@
 description: Shape and content rules for .canon/diagrams/<kind>.md files
 paths:
   - '.canon/diagrams/**'
-  - '.claude/DIAGRAMS.md'
 ---
 
 # Diagram standards
@@ -13,5 +12,3 @@ paths:
 - Follow the diagrams standard for shape and content rules for .canon/diagrams/<kind>.md files. It is the single source. Read it with `canon standards diagrams`.
 - Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. The mermaid standard routes them.
 - A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
-- Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
-- Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it

package/governance/rules/standards/requirements.md

@@ -3,7 +3,6 @@
 description: Shape and content rules for canon/REQUIREMENTS.md
 paths:
   - 'canon/REQUIREMENTS.md'
-  - '.claude/REQUIREMENTS.md'
 ---
 
 # Requirements standards

package/governance/rules/standards/wireframes.md

@@ -3,7 +3,6 @@
 description: Shape and content rules for canon/wireframes/<surface>.md files
 paths:
   - 'canon/wireframes/**'
-  - '.claude/wireframes/**'
 ---
 
 # Wireframe standards

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.21.0",
+  "version": "5.22.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {