@erclx/canon 5.51.0 → 5.53.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [5.53.0](https://github.com/erclx/canon/compare/v5.52.0...v5.53.0) (2026-10-21)
+
+
+### Features
+
+* **products:** drop teach, slides, and demo for a teach-craft skill ([#2588](https://github.com/erclx/canon/issues/2588)) ([bb1930f](https://github.com/erclx/canon/commit/bb1930fa8911ae637eddadbaabfa498e6e7f769d))
+
+## [5.52.0](https://github.com/erclx/canon/compare/v5.51.0...v5.52.0) (2026-10-21)
+
+
+### Features
+
+* **labels:** fail the scan on pull request body density ([#2585](https://github.com/erclx/canon/issues/2585)) ([121216f](https://github.com/erclx/canon/commit/121216fa258de521ff2b077aa0b897b5f2b9d519))
+* **skills:** add target-update to catch a target up to the toolkit ([#2583](https://github.com/erclx/canon/issues/2583)) ([065b971](https://github.com/erclx/canon/commit/065b9716df290bd87a94b16bed1e54e4ebf29f4e))
+
+
+### Bug Fixes
+
+* **hooks:** anchor the method flag in review-post-scan on whitespace ([#2584](https://github.com/erclx/canon/issues/2584)) ([32c52a2](https://github.com/erclx/canon/commit/32c52a25e4eef6d7d9a88d83aed3d16ab433dcf7))
+
 ## [5.51.0](https://github.com/erclx/canon/compare/v5.50.0...v5.51.0) (2026-10-21)
 
 

package/README.md

@@ -72,8 +72,6 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                               | Installed per project by `canon gov install`, refreshed by sync |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                    | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` intent format pointing at your stylesheet for values, a skill that drafts one, and a render command | `canon design render`                                           |
-| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                          | `canon slides render` writes PowerPoint                         |
-| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                             | `canon teach`                                                   |
 | Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                        | `canon canvas serve`                                            |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                          | `canon transcripts <url>` writes it into any repo               |
 | Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                              | `canon sandbox`                                                 |
@@ -93,7 +91,7 @@ The workflow this toolkit ships is the workflow that built it. Several Claude Co
  <img src="demos/agent-view-light/demo.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
 </picture>
 
-That recording is the landing page's own `dispatch` and `workers` sections, driven by `canon demo run` against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
+That recording is the landing page's own `dispatch` and `workers` sections, driven through a browser against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
 
 ## Documentation
 
@@ -182,7 +180,6 @@ Each domain carries an entry written for someone maintaining the toolkit rather
 - [Governance rules](canon/context/surfaces/governance.md)
 - [Tooling stacks](canon/context/surfaces/tooling.md)
 - [Design system](canon/context/features/design.md)
-- [Slides](canon/context/features/slides.md)
 - [Transcripts](canon/context/features/transcripts.md)
 - [Sandbox](canon/context/development/sandbox.md)
 

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

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

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

@@ -45,14 +45,11 @@ Each verb here has a skill that owns the job. Load the skill rather than driving
 | Job                                          | Verb                | Skill                       |
 | -------------------------------------------- | ------------------- | --------------------------- |
 | Render the design system                     | `canon design`      | `canon:draw-figure`         |
-| Render a slide deck                          | `canon slides`      | `canon:make-deck`           |
 | Render an HTML source to a PNG               | `canon capture`     | `canon:design-identity`     |
 | Serve a directory and print the link         | `canon serve`       | none                        |
-| Record a running app                         | `canon demo`        | `canon:script-screencast`   |
 | Report one computed property across routes   | `canon inventory`   | `canon:target-check`        |
 | Walk a page through interactions and measure | `canon drive`       | `canon:ux-measure`          |
 | Fetch a YouTube transcript                   | `canon transcripts` | `canon:youtube-transcripts` |
-| Open a learning workspace                    | `canon teach`       | `canon:teach-workspace`     |
 | Work on the local canvas                     | `canon canvas`      | `canon:canvas-board`        |
 
 ## Session and ship

package/claude/skills/context-fold/REQUIREMENT.md

@@ -29,7 +29,6 @@ The context entries describe the repository the session opened with. An entry ke
 ## Out of scope
 
 - Marking outcomes, sweeping receipts, and archiving a task, which `task-complete` owns
-- Landing a teach promotion page, which `teach-workspace` owns
 - Creating or declining a task file, which `task-board` owns
 - Public-facing docs, which `docs-sync` owns
 - Regenerating the context catalog, which a commit hook owns

package/claude/skills/design-taste/references/kinds.md

@@ -47,7 +47,6 @@ Documentation, articles, reference pages, learning material. The reader arrived
 ## Kinds this file does not cover
 
 - **Transactional flows** such as checkout, sign-up and settings are read as application UI. Their distinctive rules, state coverage and error recovery, sit in the `ui` governance rules.
-- **Presentation surfaces** such as slide decks are drafted by `make-deck`, which carries the deck's design rules. Take the layer ordering and the floor from the body and the rest from it.
 - **Terminal and text-mode surfaces** have no layout engine and their own color rules, stated where the writing surface is decided rather than here.
 
 A read naming any of the three above takes the body's rules and says it has no per-kind guidance, naming the surface that governs it. A read naming a kind this file does not list at all says so rather than borrowing the nearest section.

package/claude/skills/draw-figure/REQUIREMENT.md

@@ -7,13 +7,13 @@ description: Why a figure decides between Mermaid, an architecture view, and fre
 
 ## Gap
 
-Without this skill, a session asked for a figure takes the first path it thinks of. A graph gets SVG coordinates nobody checked against a render, and a subject that is not a graph gets forced through Mermaid. In a teach lesson the renderer cannot load the hand font, so labels clip, and a check reading the standalone image passes them.
+Without this skill, a session asked for a figure takes the first path it thinks of. A graph gets SVG coordinates nobody checked against a render, and a subject that is not a graph gets forced through Mermaid.
 
 Asked to refresh one architecture view, it redraws every view beside it. It judges the source and calls the figure verified, though a valid source can render a picture asserting something false. Mermaid's theme writes literal hex values, so the figure stops re-coloring when the page switches palette.
 
 ## Must
 
-- The figure clears the standard's earn-its-place bar, and its path follows whether the subject reduces to a graph, with a teach lesson drawn freehand whatever its shape
+- The figure clears the standard's earn-its-place bar, and its path follows whether the subject reduces to a graph
 - An architecture view is drawn from its named source signal in `flowchart` or `sequenceDiagram`, and only the view the request names changes
 - The Mermaid render uses the hand-drawn look and the figure font stack, with every literal color rewritten to the host's custom property
 - The render is read back against what the figure means to say, and a figure bound for a rendered page is verified by a capture inside that page
@@ -31,5 +31,4 @@ Asked to refresh one architecture view, it redraws every view beside it. It judg
 
 - Mermaid's layout, budgets, and label rules inside the fence, which the mermaid standard owns
 - A UI screen mockup, and design tokens or the visual system, which `canvas-board` owns
-- Which lesson needs a figure and where it sits, which `teach-workspace` owns
 - Implementation detail behind an architecture view, which the context entry the caption points at owns

package/claude/skills/draw-figure/SKILL.md

@@ -30,12 +30,11 @@ Apply the standard's bar: a relationship, a boundary, a path, or a before-and-af
 
 Take the first that matches, and state which path was picked and why in one sentence:
 
-1. **A teach lesson**, a page in a learning workspace's `lessons/` folder: the hand-drawn path, any shape. The renderer cannot load the lesson's hand font, so Mermaid labels measure narrow and clip.
-2. **An architecture view**, meaning the request names system context, components, request flow, data pipeline, or deployment: the architecture set, then the Mermaid path.
-3. **Graph-shaped**, meaning the relationship, boundary, or path is already what a flowchart or sequence diagram expresses: the Mermaid path.
-4. **Anything else**, a spatial or physical arrangement no flowchart reduces to: the hand-drawn path.
+1. **An architecture view**, meaning the request names system context, components, request flow, data pipeline, or deployment: the architecture set, then the Mermaid path.
+2. **Graph-shaped**, meaning the relationship, boundary, or path is already what a flowchart or sequence diagram expresses: the Mermaid path.
+3. **Anything else**, a spatial or physical arrangement no flowchart reduces to: the hand-drawn path.
 
-The standard states this as a render-first policy rather than a ban on any tool-exported drawing, so outside a teach lesson a graph-shaped subject always routes through Mermaid even though that is itself an external renderer.
+The standard states this as a render-first policy rather than a ban on any tool-exported drawing, so a graph-shaped subject always routes through Mermaid even though that is itself an external renderer.
 
 ## Step 4: draw
 

package/claude/skills/draw-figure/references/figures.md

@@ -39,7 +39,6 @@ Route a graph-shaped subject, one whose relationship, boundary, or path a flowch
 
 - Reserve freehand inline SVG, plain shapes and lines authored in the markup, for a subject that is not graph-shaped
 - A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent hand-drawn one, so the hatch stays open
-- Draw a figure in a teach lesson freehand whatever its shape. Its hand font cannot load in the renderer, so Mermaid measures labels in a narrower fallback face and the page clips them.
 - State this as a render-first policy rather than a ban on a tool-exported drawing, since routing through Mermaid is itself running an external tool
 
 ## Wrapping and captioning

package/claude/skills/draw-figure/references/hand-drawn.md

@@ -5,7 +5,7 @@ description: Authoring a freehand SVG, its color and accessibility audit, and th
 
 # Hand-drawn path
 
-`draw-figure` reads this file when Step 3 routes a figure to a freehand drawing: a teach lesson whatever its subject, or a subject no flowchart reduces to.
+`draw-figure` reads this file when Step 3 routes a figure to a freehand drawing, for a subject no flowchart reduces to.
 
 ## Draw
 

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

@@ -129,7 +129,7 @@ A live agent session is never the human a box waits on.
 
 ### Density
 
-`canon labels scan` reports each section's density under `density`, naming the section, the kind, and the line in the whole body. Its help lists every limit.
+`canon labels scan` fails on a density finding, naming the section, the kind, and the line in the whole body under `density`. Its help lists every limit.
 
 - Every section but Testing holds bullets to 200 characters and 5 in a row, and paragraphs to 350 characters and 2 in a row
 - Any section reports a `subheading`, and Technical context reports a `mixed-form`

package/claude/skills/pick-by-eye/REQUIREMENT.md

@@ -33,4 +33,3 @@ The evidence fails as well. Arms get reported without being rendered or judged,
 - Finding roughness by reading source, which `ux-audit` owns
 - Measuring what a running interface costs to paint, which `ux-measure` owns
 - Listing what to look at on a change already made, which `ui-checklist` owns
-- Scripting a recording of something already built, which `script-screencast` owns

package/claude/skills/pick-by-eye/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pick-by-eye
-description: Drafts several candidates for a decision judged by looking, lays them out side by side as frames on one canvas page, hands the operator the address, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write what to look at on a change already made, which is `ui-checklist`, or to script a recording, which is `script-screencast`.
+description: Drafts several candidates for a decision judged by looking, lays them out side by side as frames on one canvas page, hands the operator the address, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, or to write what to look at on a change already made, which is `ui-checklist`.
 metadata:
   family: decide
 ---

package/claude/skills/review-address/SKILL.md

@@ -124,7 +124,7 @@ canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md --json
 The hook skips `.canon/tmp/`, and the `pull_request` check reads only a pull request's own title and body, so this scan is the only gate on the reply.
 
 - Fix any hit, and stop on a `density` entry too, shortening the line it names
-- Read the record rather than the exit, since density never sets the exit code
+- Read the record rather than the exit, since a post's density never sets the exit code
 
 Then post and keep the `id` the POST answers with, since Step 7 edits this exact comment:
 

package/claude/skills/review-address/references/post-review-findings.md

@@ -13,7 +13,7 @@ Write the body the way Step 6 writes a reply.
 
 - Load `write-human` for voice and word choice, and follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation
 - Run the `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` scan before posting, with `canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md --json`
-- Stop on a `density` entry as on any hit, since density never sets the exit code
+- Stop on a `density` entry as on any hit, since a post's density never sets the exit code
 - Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered
 - Close the body with `🤖 Addressed by Claude Code` on its own line, matching the reply's footer
 

package/claude/skills/review-pr/references/post.md

@@ -114,7 +114,7 @@ Run `canon labels scan --title "<title>" --body "<body>" --head <headRefName>` a
 
 - Name the token quoted from the title or body for a phase label, a board identifier, or a session link
 - Name the broken rule, being `structure`, a casing issue, or `length`, for a title-format hit
-- A heading in `sections.outside` or `sections.missing`, or a character in `bannedCharacters`, is a hit of the same weight, naming the heading or the character
+- A heading in `sections.outside` or `sections.missing`, an entry in `density`, or a character in `bannedCharacters`, is a hit of the same weight, naming the heading, the line and kind, or the character
 - This reads the pull request under review, distinct from the comment this pass posts, which the scan later in this step covers
 
 ### Why the threshold ignores the grade
@@ -175,7 +175,7 @@ The marker is the read-time record those fields are not.
 Before posting, run `canon labels scan --body-file .canon/tmp/pr/review/body-<number>-<short-sha>.md`, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`. Pass `--json` and fix the body and scan again on a finding.
 
 - A `density` entry is a finding here, naming a subject or nested bullet past 200 characters, a run past 5 plain bullets, or a paragraph past its limits, by its line in the whole body
-- Density never sets the exit code, so the hook below lets the post through on it and this step is the one that stops
+- A post's density never sets the exit code, so the hook below lets the post through on it and this step is the one that stops
 
 - A finding phrased against an internal phase label is what the label half of the scan catches here
 - The call carries no `--title`, so the scan reads the text as a review

package/claude/skills/target-check/SKILL.md

@@ -98,3 +98,5 @@ No overall verdict. The harness row is unchecked rather than passing.
 ```
 
 Keep the harness row `unchecked` on every run until a verb reads it. A domain left out of the table reads as a domain that passed, which is the one shape the row exists to prevent.
+
+Close on one line naming `/canon:target-update` as the skill that applies the catch-up, when a domain reads behind and `target-update` did not invoke this check.

package/claude/skills/target-setup/SKILL.md

@@ -59,7 +59,7 @@ Three states reach this skill that the chain does not serve. Name the destinatio
 
 ### An existing project
 
-Stop and hand off to `target-check`, which reports what the target already carries before anything is repaired. This chain never reads that, so a per-domain install picked here is a guess against configs nobody read.
+Stop and hand off to `target-check`, which reports what the target already carries before anything is repaired. This chain never reads that, so a per-domain install picked here is a guess against configs nobody read. Name `target-update` when the operator wants the catch-up applied.
 
 ### The `.claude/` folder alone
 

package/claude/skills/target-update/REQUIREMENT.md

@@ -0,0 +1,33 @@
+---
+name: target-update
+description: What catching a target up to the toolkit is for, the judgment it holds, and where it hands off to the check and the setup
+---
+
+# Target update requirement
+
+## Gap
+
+Without this skill, a session catching a target up after a release improvises the order. It runs a sync before the migrations that move its paths, writes a record-tree rewrite with no backup, and lets a sync replace a rule the project customized without saying what was lost.
+
+The verbs report every fact, so the gap is the judgment between them. A session reads a refused migration as a step to force, picks rules and seed merges with nobody asked, and ends with no way to tell a current target from one it stopped partway through.
+
+## Must
+
+- Show the changelog summary, the pending migrations, and the drift before the first write to the target, and apply only on the operator's go-ahead
+- Read every fact from a `canon` verb, so a later release changes what the skill reports with no edit to its body
+- Stop and ask on a refused migration, a stranded file, an unattributed folder, and a rule the stack newly ships
+- Keep a customized file and a drifted seed as the project wrote them, naming the toolkit change each one skipped
+- End on a clean `target-check` or on named remainders, with nothing written when nothing is pending
+
+## Must not
+
+- Detect pending migrations or parse the changelog inside the body, since `canon migrate status` and `canon changelog` own both
+- Name a toolkit version in an update commit's subject
+- Run from the toolkit's own checkout, or write into a target from another repository's session
+- Rely on being typed by name. It is reached through its description and `target-check`'s close, and a quarter of releases with no migration and no drift is the signal to fold it in there.
+
+## Out of scope
+
+- First-time scaffold, which `target-setup` owns
+- Reporting drift without repairing it, which `target-check` owns
+- Opening the target's pull request, which `git-ship` owns

package/claude/skills/target-update/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: target-update
+description: Catches a target project up to the toolkit after a release. Upgrades the binary and plugin, previews the changelog summary, the pending migrations, and the drift, then on the operator's go-ahead migrates, syncs, regenerates the indexes, and ends on a clean `target-check` or named remainders. Use when asked to "update this project to the latest canon", "catch this target up", "apply the new release here", "run the pending migrations", or "bring this project current with the toolkit". Do NOT use on a project without the toolkit, which is `target-setup`, or to report drift without repairing it, which is `target-check`.
+metadata:
+  family: upkeep
+---
+
+# Target update
+
+Takes a target from behind the toolkit to current. Every fact comes from a `canon` verb, and this body holds the order and the judgment calls the verbs leave open. It names no migration, rule, or stack, so a later release reaches it with no edit here.
+
+Read `canon docs migrate` for what each migrate verb moves and refuses, and `canon docs sync` for the drift causes. This body cites them rather than restating them.
+
+## Guards
+
+Stop with the line beside each state.
+
+| State                                       | Stop                                                                                              |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `canon` absent from the path                | `❌ canon is not on PATH, so nothing can be read.`                                                |
+| No `.claude/` directory at the working root | `❌ No .claude/ here, so the toolkit is not installed. Run /canon:target-setup instead.`          |
+| A `claude/skills/` folder, no leading dot   | `❌ This is the toolkit itself rather than a target. Run this from the target's own session.`     |
+| A dirty working tree                        | `❌ Uncommitted changes here. Commit or stash them first, since canon sync refuses a dirty tree.` |
+
+Then hold two rules for every verb this body runs.
+
+- Run it under `CANON_NON_INTERACTIVE=1` from the target root
+- Branch on its record's fields rather than its exit, which a shell function wrapping `canon` can flatten
+
+## Step 1: bring the binary and plugin forward
+
+Read `skew` off `canon sync --check . --json`. When `installed` trails `latest`, run `canon upgrade --json`, then `canon claude plugin-update --json` whatever the skew reads.
+
+Both write to the machine rather than the target, and the preview needs the verbs and the changelog a newer binary carries, so they run before it. The permission dialog gates each. Report a refusal from either and continue on the installed binary, saying the preview reads against it.
+
+## Step 2: read the pending work
+
+Run these in parallel from the target root:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon changelog --json
+CANON_NON_INTERACTIVE=1 canon migrate status --json
+CANON_NON_INTERACTIVE=1 canon sync --check . --json
+```
+
+Then take `<stack>` from the first name in the report's `tooling.chain` and run `canon tooling diff <stack> . --json`. Never run it bare, since the stack prompt resolves to the catalog's first entry under the non-interactive variable. Report tooling unmeasured when `tooling.measured` is false or `chain` names nothing.
+
+### When a read refuses
+
+A refusal is a fact for the preview, never a gap to fill by reading files.
+
+- `changelog` refusing `no-stamp` or `unknown-version`: say the summary is unread and why. Offer `--since <version>` when the operator names one, and never guess a start.
+- `migrate status` carrying no such subcommand: the binary predates it. Stop, since pending migrations cannot be listed without detecting them here, which this skill never does.
+- A missing report key is an older binary rather than an empty answer. Name the installed version beside it.
+
+## Step 3: preview and wait
+
+Write the preview from those records alone, then stop and wait for the operator. Nothing in the target is written before the go-ahead.
+
+```markdown
+Target update: `<path>`, canon `<installed>` to `<running>`.
+
+**What changed since `<since>`:** <three to six bullets from the changelog entries, each naming what this project will notice, never the version>
+
+**Migrations, in run order:** <each pending or refused entry from migrate status, with its verb>
+
+**Drift:** <each non-empty cause from sync --check, with its count and paths>
+
+**Calls for you:** <each judgment call below this run meets, with the default this skill takes>
+
+**Commands, in order:** <the exact commands Steps 4 to 6 will run>
+```
+
+Summarize the changelog for this project, not for the toolkit. Drop an entry that touches nothing the target holds, and lead with anything a migration or a sync will change.
+
+### Nothing pending
+
+When the changelog range is empty, `migrate status` lists nothing pending or refused, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
+
+## Step 4: migrate
+
+Run each pending migration in the order `migrate status` gave, one at a time, as the entry's `verb` with `--write --json` appended. The verb carries the flags its dry run used, so a bare `canon migrate <name>` would apply a plan the preview never showed.
+
+- Run `canon migrate status --json` again after each write, since an applied move can turn a clean entry pending
+- Stop and ask on a `refused` entry, quoting its reason and the remedy it names. Run the remedy only on the operator's word, since a refusal guards a destination the project may own.
+- Stage each write with `git add -A`, since no migrate verb stages and the tree was clean before it, then commit through `canon:git-commit`, one commit per migration
+- Skip the commit when the write changed no tracked file, as `record-tree` does by touching only gitignored records
+
+### Markers
+
+A planned rewrite can reach a line that names an old spelling on purpose, such as a dated note or a quoted history. Propose a marker for each such line in the preview, and add it before the write. `canon docs migrate` names the marker for each spelling.
+
+### The record-tree backup
+
+The record tree is untracked, so a `record-tree` rewrite has no undo. Run `canon records push --json` before its write. When that reports no backup repository, copy `.canon/` to a dated folder outside the project and name the path in the report.
+
+## Step 5: sync
+
+Run `canon sync .`, then `canon tooling sync <stack> . --write` when the tooling diff named files to change. Treat each drift cause the way the preview stated:
+
+| Cause                       | This skill                                                                                       |
+| --------------------------- | ------------------------------------------------------------------------------------------------ |
+| `stale`, `retired`, renamed | Takes the sync's write                                                                           |
+| `customized`                | Keeps the project's file. Shows `git diff -- <rel>` as the toolkit's change, then `git restore`s |
+| `stranded`                  | Names where the file sits and where the toolkit now installs, and moves it only on the word      |
+| `seeds` drifted             | Merges by hand against `canon claude seeds list --json`, keeping the project's edits             |
+| `seeds` stale or missing    | Takes the toolkit's copy whole                                                                   |
+| `newRules`                  | Lists them, and installs only the ones the operator picks, with `canon gov install --add`        |
+
+A `customized` rule is the file `canon sync` replaces, so read it back after the sync rather than trusting the report from Step 2. Report each kept file with the toolkit's change summarized in a line, so the operator can take it later.
+
+### What the toolkit dropped
+
+Read `reverse.unclaimed` by attribution. Delete a `dropped` folder, read an `unattributed` one and ask before deleting it, and leave a `project` one alone.
+
+Read the report's top-level `superseded` and `unmigrated` lists apart from it. Each names a move only the operator can make, being a file a newer seed replaced or a domain still at the root layout, so name each and move nothing.
+
+## Step 6: regenerate and verify
+
+Run `canon indexes regen`, then the project's own check script when it carries one. Invoke `canon:target-check` last.
+
+Stage the sync, the merges, and the regenerated indexes with `git add -A`, since `canon sync` leaves its writes unstaged, then commit through `canon:git-stage`. Name what changed in the project in each subject, such as the rules refreshed or the seeds merged, and never the toolkit version.
+
+## Output
+
+```markdown
+Target update: `<path>`, now on canon `<version>`.
+
+<the target-check table>
+
+**Kept for you:** <each customized or drifted file left as the project wrote it, with the toolkit change it skipped>
+
+**Remaining:** <each refusal, stranded file, or unread domain, with the command or decision it waits on>
+```
+
+Omit a section that holds nothing. End on the commits and the check, and leave the pull request to `canon:git-ship`.

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

@@ -0,0 +1,30 @@
+---
+name: teach-craft
+description: Scope boundary for the teaching judgment a session carries, and why it ships as knowledge rather than as a workspace
+---
+
+# Teach craft requirement
+
+## Gap
+
+Without this skill, a session asked to teach explains and calls a smooth reply a lesson. It teaches from recall, picks topics from the subject's order rather than the learner's errors, and asks nothing about what they know.
+
+Its quizzes leak the answer through option length or position, and nothing tests the learner later, so fluency passes for retention.
+
+## Must
+
+- Carry retrieval, spacing, interleaving, and placement as rules a session applies before picking what to teach next
+- Ask the learner's starting point and read the subject from sources, saying which claims rest on recall
+- State quiz design that leaks no answer, and pair a quiz with a teach-back
+- Hold that the wrong answer itself is what the next session places from
+
+## Must not
+
+- Name a verb, a folder, a markup contract, or a stylesheet, since the skill produces nothing of its own
+- Fire on a request to answer one question
+- Go unloaded when a session teaches across exchanges, since a craft body only its author types reaches no lesson
+
+## Out of scope
+
+- Where a lesson is stored or how it renders, which belongs to whatever surface the session writes to
+- A cited source ledger for the practice family, which is a follow-on task

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

@@ -0,0 +1,39 @@
+---
+name: teach-craft
+description: Carries the judgment for teaching a subject so it sticks, being retrieval over review, spacing, interleaving, placing the learner just past what they can do unaided, quiz design that leaks no answer, the teach-back, and what makes a lesson worth returning to. Use before teaching a subject over more than one exchange, when writing a quiz, a lesson, or a study plan, or when asked "teach me X", "quiz me on this", "how should I learn X", or "is this a good quiz question". Do NOT use to answer one question, which is an ordinary reply, or to write project documentation, which belongs to the surface owning that document.
+metadata:
+  family: answer
+---
+
+# Teach craft
+
+A session asked to teach explains, and a smooth explanation reads as a lesson learned. It is fluency, which decays within days. This skill carries what turns teaching into retention: test before telling, space the returns, and grade only what the learner produced unaided.
+
+It produces nothing of its own. The lesson lands wherever the session already writes, being the conversation, a file, or a page.
+
+## References
+
+- `${CLAUDE_SKILL_DIR}/references/pedagogy.md`: fluency against storage strength, retrieval practice, spacing and its ladder, interleaving, where to place the learner, and where difficulty helps
+- `${CLAUDE_SKILL_DIR}/references/lesson-craft.md`: restraint, quiz design, the teach-back, and what makes a lesson worth returning to
+
+Read `pedagogy.md` before picking what to teach next, and `lesson-craft.md` before writing a quiz or a lesson.
+
+## Before teaching
+
+- Ask what the learner already knows rather than assuming it. Difficulty with no floor under it teaches nobody.
+- Read the subject from sources rather than from recall, and say which claims rest on recall where no source was reachable
+- Open a returning learner on retrieval of what they got wrong last time, before anything new
+
+## While teaching
+
+- Place each step just past what the learner can do unaided, from what they got wrong rather than from the subject's own order
+- Carry a quiz and a teach-back, since recognition and production fail differently
+- Record the wrong answer itself rather than a count, since the next session places the learner from the misconception
+
+## Excuses and rebuttals
+
+| Excuse                                    | Rebuttal                                                                                     |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
+| They followed the explanation, so move on | Following is fluency. Advance on a retrieval the learner passed unaided.                     |
+| Review the last lesson before testing it  | Review rebuilds the fluency the test would have measured. Test first, then fill what missed. |
+| The answer is obvious from the options    | Then the distractors are not misconceptions anyone holds. Rewrite them.                      |

package/claude/skills/teach-craft/references/lesson-craft.md

@@ -0,0 +1,52 @@
+---
+title: Lesson craft reference
+description: Restraint, quiz design, teach back, and what makes a lesson worth returning to
+---
+
+# Lesson craft reference
+
+Judgment rather than shape. This file covers what makes a lesson worth opening twice, whatever surface it renders on.
+
+## Contents
+
+- [Restraint](#restraint)
+- [Quiz design](#quiz-design)
+- [Teach back](#teach-back)
+- [What makes a lesson worth returning to](#what-makes-a-lesson-worth-returning-to)
+
+## Restraint
+
+Every element competes with the material for attention.
+
+- Cut any decoration that carries no information
+- Use at most one accent color, reserved for the thing the learner acts on
+- Do not animate anything the learner did not trigger
+- Prefer whitespace over rules and boxes to separate sections
+
+## Quiz design
+
+The quiz is the retrieval, so a leak in its construction turns it into a reading test.
+
+- Write every option to the same length, in words and in characters. A longer option reads as the considered one.
+- Rotate the correct option's slot by question number, so question one puts it first, question two second, and so on. An author varying position by judgment settles on the first slot.
+- Make each wrong option a misconception someone actually holds. An obviously wrong option removes itself and shrinks the question.
+- Write one feedback block per question, covering the correct option and why each distractor fails, saying why rather than whether
+- Give feedback after the attempt, never alongside the question
+
+One feedback block reads as an explanation where a block per option reads as four verdicts, and only the explanation names what separates a wrong option from the answer. Name the correct option in the feedback text, since it is what a learner reads to find out whether they were right.
+
+## Teach back
+
+A quiz is recognition and a teach-back is production, which is the form retrieval practice prefers. Carry both: the quiz places the learner against options someone could hold, and the teach-back is where the learner finds out what they cannot say without help.
+
+- Ask for an explanation to a named audience rather than for an answer. Telling a non-programmer why a lazy quantifier is not an optional one has a floor, and "explain lazy quantifiers" has none.
+- Ask about the thing the lesson was for, not a detail beside it. A teach-back on a footnote tests attention rather than the material.
+- Carry a self-check, hidden until the learner opens it, listing what a complete explanation covers. A learner with no session in the room otherwise cannot grade the ask, and hidden leaks nothing.
+- Write the self-check as what the explanation has to cover rather than as the explanation itself. A model answer is read instead of produced, which turns the block back into reading.
+
+## What makes a lesson worth returning to
+
+- The worked example is complete. A learner returning for the example finds the whole thing rather than a fragment they have to reconstruct.
+- The lesson states what it assumes. A returning reader can tell in one line whether they are in the right place.
+- The hard part is named as the hard part. Material that flattens everything to one difficulty gives a returning reader nothing to navigate by.
+- Nothing depends on the session it was written in. A lesson referring to what was discussed is unreadable a week later.

package/claude/skills/{teach-workspace → teach-craft}/references/pedagogy.md

@@ -5,7 +5,7 @@ description: Fluency against storage strength, retrieval practice, spacing, inte
 
 # Pedagogy reference
 
-The rules a lesson is built from. Read this before picking what to teach next, not while writing the markup.
+The rules a lesson is built from. Read this before picking what to teach next.
 
 ## Fluency is not storage strength
 
@@ -43,8 +43,7 @@ The same total time spread across days beats the same time in one sitting. Forge
 
 The ladder is 1, 3, 7, 16, and 35 days. A topic retrieved unaided moves up a rung and a miss drops it back one, held inside the ladder at either end, so a topic the learner keeps missing stays on the shortest gap rather than restarting a sequence.
 
-- Do not compute a date from that ladder by hand. `canon teach list <topic> --json` reports both dates resolved for every item, a number to copy rather than a rule to apply.
-- An author told to widen a gap still picks it by judgment, the same reason quiz option order is drawn by a verb rather than stated here
+- Apply the ladder as written rather than picking a gap by judgment, since an author told to widen a gap settles on whatever feels right
 
 ## Interleaving
 
@@ -78,4 +77,13 @@ Parametric recall is confident where it is wrong, and a learner cannot audit it.
 - Read the subject from sources before teaching, and record each one with its link
 - Mark any claim resting on recall as resting on recall, in the lesson itself
 - List a source found and not opened as a lead, and never cite it
-- Choose which sources to read by the ladder under `### Choosing sources` in the teach standard, which also rules out the learner's own work as proof of a general claim
+- Rest each general claim on the highest rung of the ladder below that covers it
+- Never take the learner's own projects, or material specific to one employer, as proof of a general claim. Either may appear as a worked application labeled with whose it is.
+
+The ladder runs in three rungs, highest first.
+
+1. Documentation or a specification published by whoever owns the subject
+2. A canonical work on the subject, such as the standard text, a reference book, or a primary paper
+3. Other material, such as a tutorial, a course, or a post, and only for a claim the first two rungs do not cover
+
+A subject nobody owns, such as a mathematical topic or a craft, has no first rung, so its list starts at the second. Record a third-rung source with the claim it covers and why no higher rung does, since that reason is what a later session checks the choice against.

package/docs/agents/audits.md

@@ -77,7 +77,6 @@ The placement entry runs pinned to `--backend off`, so its tally stays comparabl
 | `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                   | Reports        |
 | `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                             | Reports        |
 | `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                 | Reports        |
-| `records-teach`      | `canon records validate teach`      | Teach records against their shape                                                  | Reports        |
 | `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`           | Reports        |
 | `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                      | Reports        |
 | `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                       | Gates          |

package/docs/agents/migrate.md

@@ -33,7 +33,8 @@ kind: reference
 - `record-tree` reports closed groundwork and intake trails, the scratch folder, and backup history as counts and rewrites none
 - `records` reports skipped record folders as a count on its own line
 - A `record-tree` rewrite has no undo in version control, so read the report before `--write`
-- `status` runs each verb as a dry run and exits 2 while any is pending, with a refusal outranking that. A clean entry can turn pending once an earlier one applies, so run it again after each `--write`.
+
+`status` runs each verb as a dry run and exits 2 while any is pending, with a refusal outranking that. Each entry's `verb` carries the flags its dry run used, so append `--write` to it. A clean entry can turn pending once an earlier one applies, so run it again after each `--write`.
 
 Three markers keep an old spelling on a line. Each also covers the nearest non-blank line, below it for `canon-keep-record-root` and above it for `canon-keep-surface-root`.