@erclx/canon 5.38.0 → 5.40.0

package/docs/workflow/parallel-features.md

@@ -6,93 +6,56 @@ category: Workflow
 
 # Parallel features
 
-When features are independent, run them in parallel instead of sequentially. Use one git worktree per feature so each session has its own working tree and branch.
+Run independent features in parallel, one git worktree and one Claude Code session per feature.
 
 ## One worktree per feature
 
-- Create a worktree per feature, then start a Claude Code session in each
-- Invoke `canon:plan-feature` in each session. Plans land at the main worktree root as `.canon/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `ui-checklist` writes a per-branch checklist handoff there too (`tmp/handoff/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
-- Ship each worktree separately with `canon:git-ship`
-- For full autonomy per worktree, invoke `canon:auto-ship` instead of the manual chain. Approve the plan, walk away, come back to a pull request the chain marked as a draft and then read the flag back on. The mark says the work has had no review yet, and it holds no window, since readying a pull request to merge lifts it directly, an act reserved to the operator or to the controlling session that closed the review.
+- Invoke `canon:plan-feature` in each session. Plans land at `.canon/plans/feature-<slug>.md` at the main root.
+- `ui-checklist` writes a per-branch handoff at `tmp/handoff/ui-checklist/<slug>.md`, which `git-pr` posts and removes. The slug is the branch name minus its leading type segment.
+- Ship each worktree with `canon:git-ship`, or `canon:auto-ship` for a draft pull request
+- Only the operator or the controlling session readies a draft
 
 ## A coordinated flow
 
-To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `canon:role-orchestrator`. It holds the cross-feature call, plans each feature itself or dispatches a cold planner under `canon:role-planner` to write the plan, refills the ready queue so a free worker never waits, and reviews each worker's PR with `canon:review-pr` or dispatches a cold reviewer under `canon:role-reviewer` to run it, then tells the session holding that branch to run `canon:review-address` whenever the pass posted a finding at any severity, which is the same threshold `canon:review-pr` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
+Assert the orchestrator role in one warm session with `canon:role-orchestrator`. It plans each feature or dispatches a cold planner under `canon:role-planner`, and dispatches a reviewer under `canon:role-reviewer` for each PR. The human launches workers and merges. See [operating model](operating-model.md).
 
-Execution order comes off `.canon/tasks/priority.md` and nothing sequences work into versions. Scope stays in `canon/REQUIREMENTS.md` as a statement of what is wanted, and it reaches the board as discrete tasks the orchestrator orders by readiness.
-
-Run one orchestrator at a time. The board is gitignored, so a second session reads none of the first one's writes and the two collide on labels and archives.
-
-See [operating model](operating-model.md) for what caps the worker tracks under it and what conflict holds one behind another. An operator caps a session's workers by saying so, and that cap binds for the session rather than standing as a number in a file.
-
-Before a handoff, the orchestrator checks the plan against the tree rather than reading it: grep each construct it names and count the sites, confirm every phase label it cites is still open, and open each file it describes. A plan goes stale from whatever merged after it was written, and reading cannot catch that.
-
-A constraint naming a track in flight carries the same problem past the handoff, so the block opens with the commit it was measured against. A worker re-tests before honoring one, fetching and then logging that commit against `origin/main` over the paths the constraint names, and any merge there means the track landed and the constraint is dead. An unstamped block reads as unverified rather than as live, which covers every plan written before the rule.
+- Run one orchestrator at a time
+- Execution order comes off `.canon/tasks/priority.md`
+- Before a handoff, grep each construct the plan names and open each file it describes
+- A constraint naming a track in flight opens with the commit it was measured against. A merge of that track into `origin/main` over the named paths kills the constraint.
 
 ## Records at the main root
 
-`.canon/plans/` and `.canon/review/` both resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for why the tool refuses the write, and the fan-out section below for the domain-level guidance.
-
-The plan's shape is fixed by `claude/skills/plan-feature/references/plan.md`: the section list, the filename, and the contract its questions keep. Its lifecycle, from the session that writes it to the archive, is `claude/skills/plan-feature/references/plan-lifecycle.md`. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
-
-An execution that picks other than the suggestion rewrites the `- Suggested:` line as `overridden at execution to <pick>,` followed by the measurement that moved it, and leaves the slot blank. That fixed phrase is how a reader of the archived plan tells an override from a suggestion the execution accepted, since an authored suggestion often carries a number of its own. The same deviation takes one line in the open task's `## Findings`, which is the register that survives the plan being archived. A deviation from a question somebody already answered goes back to whoever answered it instead, since a filled slot is a decision already made.
-
-`canon records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all four folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
-
-`canon records push` carries these folders off the disk they live on, and `canon records pull` brings them back. Every top-level entry under `.canon/` is backed except `tmp`, `ordinal-locks`, and `.records.git`, so a folder added later enters the payload on its own rather than waiting on a name written into a list. Push names each folder it carries the first time it sees it, which is what keeps a stray folder visible instead of silently entering the payload. It refuses the whole push, naming each path, when a new or changed file is over 25 MB or carries a credential `canon secrets scan` would report. The history lives in a second git directory at `.canon/.records.git` with `.canon/` as its work tree, so every path a task file cites stays where it is.
-
-A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the task board and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records push](../agents/records-push.md) for the refusal table.
-
-`canon records size` reports what each of these folders holds, heaviest first, along with `.canon/tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: a pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
-
-`canon records prune-tmp` reports scratch under `.canon/tmp` nobody has touched inside an age window, and deletes it only with `--write`. A `tmp/handoff/` folder and the live `tmp/pr/poll/` baseline are never offered, since a reader deletes a handoff once it is read and a poll baseline is state a session still needs. See [records](../agents/records.md) for the candidate shapes and the exit codes.
+`.canon/plans/` and `.canon/review/` resolve at the main worktree root. File-editing tools refuse a main-root path from a worktree, so write a whole file through the shell and change an existing one through a `canon` verb.
 
-`canon records stale canonical` reports when the requirements record was last reviewed and how many releases have shipped since, so a review of it starts from a count rather than from the tag list. It writes nothing. See [records stale](../agents/records-stale.md) for how the count is taken and the refusals.
+`claude/skills/plan-feature/references/plan.md` fixes the plan's shape and `claude/skills/plan-feature/references/plan-lifecycle.md` its lifecycle. A blank `- Answer:` slot accepts the `- Suggested:` line.
 
-A plan that ships is archived, never deleted. `canon tasks archive` moves it to `.canon/plans/archive/` alongside the task it belonged to and retargets that task's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
+- To pick otherwise, rewrite that line as `overridden at execution to <pick>,` plus the measurement, and add one line to the open task's `## Findings`
 
-An older branch review report takes the other route and is swept rather than archived. It sits flat in `.canon/review/` as `branch-<slug>.md`, the session addressing it read it once, and the durable record of what a review found is the comment `review-pr` posts on the pull request, so `canon:task-complete` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
-
-`canon:task-complete` decides which task closed by reading the diff rather than the conversation, as the ship-chain step after `canon:context-fold`. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Decisions stay session-sourced, because a diff cannot carry a judgment, and `canon:context-fold` folds them into the context entries. The requirements record is never folded. A direction change gets one report line naming `canon:document-health`, which reviews that record only when asked.
+- `canon records validate plans` reports a plan breaking its standard, and takes `groundwork`, `intake`, and `teach`
+- `canon records push` and `canon records pull` carry `.canon/` to and from a private repository. See [records](../agents/records.md).
+- `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements review
+- `canon tasks archive` moves a shipped plan to `.canon/plans/archive/` and retargets the task's `Plan:` line
 
 ## Shipping a fan-out
 
-A fan-out of N worktrees produces N pull requests. The order they merge in matters only when two branches touch the same file.
-
-**Rebase profile.** Work confined to one domain directory, such as a new skill under its own folder or independent fixes in different subtrees of `scripts/`, rarely touches a sibling's files. A shared file does not hold a branch back, per the conflict test in [operating model](operating-model.md). These paths are shared hotspots, the ones a second branch should expect to rebase over and resolve:
-
-- `CLAUDE.md`, since cross-domain behavior lives there
-- `tooling/**`, since stack manifests, golden configs, and seeds are tightly coupled
-- `canon/context/context-model/overview.md` and `docs/agents/`, which several domains cross-reference
-- Any folder's `index.md`, since `canon indexes regen` rewrites it and two worktrees adding files to a regen-covered folder race on it. Resolve its conflict by running the regen over the rebased tree rather than by hand.
-
-Land any in-flight edit to a hotspot on `main` before fanning out where you can. A worktree on a stale `CLAUDE.md` costs more to rebase than it saved.
-
-**Merge order.** Merge the branch with the smallest hotspot footprint first. A branch touching `CLAUDE.md`, a context entry, or a regenerated `index.md` merges last, and its siblings rebase on the new `main` once it lands.
-
-**Rebase before the next merge.** After one squash-merge, each sibling is behind `main` and may carry a stale copy of a shared file. The branch merging second resolves, in the session that built it and after the first lands, never against a sibling still building: run `/review-address` there, which trial-merges against `origin/main` and rebases a branch that no longer merges or whose files `main` changed. Push, then merge. Never force-merge a stale branch.
+Merge order matters only when two branches touch the same file. Expect to rebase over `CLAUDE.md`, `tooling/**`, `canon/context/context-model.md`, `docs/agents/`, and any folder's `index.md`. Resolve an `index.md` conflict with `canon indexes regen` over the rebased tree.
 
-**Clean up after merge.** Run `/git-worktree cleanup` to remove worktrees whose branches merged on GitHub and prune the local branches. The skill reads merge state through `gh pr view`. To start a fresh feature from a stale worktree, `ExitWorktree(action: "keep")` back to main, then `/session-worktree <new-name>`.
-
-**When fan-out was the wrong call.** Sharing a file was never the reason. If every rebase needs a decision the tree does not carry, because one branch depended on another, changed a contract the other consumed, moved a path the other wrote, or swept a folder the other wrote inside, the branches should have serialized. Land one, wait, then start the next. The cleanup skill only tidies a flow that already worked.
+- **Merge order.** Merge the smallest hotspot footprint first, and a branch touching `CLAUDE.md` or a context entry last.
+- **Rebase.** The branch merging second runs `/review-address`, which trial-merges against `origin/main` and rebases. Push, then merge.
+- **Clean up.** Run `/git-worktree cleanup` to remove merged worktrees. To start fresh, `ExitWorktree(action: "keep")`, then `/session-worktree <new-name>`.
+- **Wrong call.** If a rebase needs a decision the tree does not carry, land one branch before starting the next.
 
 ## The task board
 
-`.canon/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders.
-
-A hand-maintained `priority.md` sits beside the index carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
-
-`canon tasks validate` reads a row against its own table before it reads anything the row claims. A blank or prose line closes the table above it, so a row stranded there is checked against the line behind it rather than parsed as a continuation, and a row that clears that test still has its cell count checked against its header. A `## Needs a plan` row that states its own position, searched for `<ordinal> here` or the bare word `last` anywhere in the cell rather than at its start, is checked against where it actually sits, which is what catches a gap, a duplicate, and a sequence starting somewhere other than first alike.
-
-Past that shape, it checks what a surviving row claims against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and every row marked ready names its files. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. Paths two ready rows share go to a `shared` array moving no exit code, the candidate list the orchestrator's conflict check reads. Blockers re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
-
-`canon:task-board` creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and declines a task decided against. `canon:task-complete` marks a shipped task's outcomes and moves one the merge hook left to `.canon/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
+`.canon/tasks/` is gitignored and resolves at the main worktree root, one file per task. A hook generates `index.md`, and `priority.md` carries execution order and blockers.
 
-Archiving a task carries its plan with it, in the same act. The merge is what settles a plan, and the hook below reaches the archive with nobody watching, so a second call after it would be a second failure point leaving the task archived and the plan live. A task whose plan a sibling still cites archives on its own and leaves the plan live, since moving it on the first task to close strands every other pointer at a path that has gone.
+`canon tasks validate` reports and never writes:
 
-Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `canon:auto-ship` or `canon:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook archives the task a merged pull request closed, through the same verb the base stack ships to every target, and does nothing on a project with no board.
+- A row's cell count must match its header, and a `## Needs a plan` row stating its position is checked against where it sits
+- Every plan pointer resolves, every task file is named once, and every ready row names its files
+- A parked row is reported when its cited task reached the trunk
 
-The archive gates on a pull request number the merge carried and a closed task, because outcomes are marked on the branch and a task can read all `[x]` while its pull request is still open, so `canon:task-complete` still confirms the work reached `main` when a person archives by hand. A companion `post-rewrite` hook carries the same steps for anyone pulling with rebase, which fires that event instead of `post-merge`.
+`canon:task-board` creates a task file, and `canon:task-complete` marks outcomes. The `post-merge` hook archives the task a merged pull request closed, with its plan, and a `post-rewrite` hook does the same for a rebase pull. Both archive only when the merge carried a PR number and the task is closed.
 
-The hook archives through `canon tasks archive`, which carries the refusals above, so a task whose pull request has not merged stays where it is. Both hooks ship with the `base` tooling stack, so a target project running this workflow gets the same trigger, and `CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three steps that act on the machine.
+`CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three hook steps that act on the machine.

package/docs/workflow/skill-map-on-request.md

@@ -6,34 +6,32 @@ category: Workflow
 
 # Skill map on request
 
-These two groups hold the skills no single moment in a project's life calls for, so they sit apart from the moment-ordered groups in the [skill map](skill-map.md). The two pages together are the corpus the coverage claim is measured against, and a skill takes one row across both.
+These skills serve a request rather than a moment. With the [skill map](skill-map.md) they cover every plugin skill once.
 
 ## 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:draft-doc`         | For a brand-new `docs/` page, context entry, 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 or an architecture view inside an existing doc, drafted in Mermaid or freehand SVG                  |
-| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                          |
-| `canon:draft-slides`      | For a deck, drawn as HTML slides in its own folder and rendered to editable 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`       | A project rule the toolkit does not ship          |
+| `canon:create-skill`      | A new `SKILL.md`                                  |
+| `canon:draft-doc`         | A new `docs/` page, context entry, or `README.md` |
+| `canon:draft-ready`       | Finished files a worker should copy               |
+| `canon:draft-figure`      | A figure or architecture view inside a doc        |
+| `canon:ci-workflow`       | A GitHub Actions workflow file                    |
+| `canon:draft-slides`      | A deck rendered to editable PowerPoint            |
+| `canon:draft-screencast`  | A recording script with beats seeded              |
+| `canon:record-screencast` | Recording a screencast draft into a finished mp4  |
+| `canon:draft-identity`    | A logo mark and social card                       |
 
 ## Answer a question at any point
 
-| Skill                       | When to use                                                                                                                      |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `canon:canon-cli`           | To pick the `canon` verb that does a job, or before a sync or migrate, to learn which verbs can lose the project's edits         |
-| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                         |
-| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right |
-| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                       |
-| `canon:markdown-craft`      | Before a substantial markdown edit, for the format and structure rules and the audit that follows                                |
-| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                |
+| Skill                       | When to use                                           |
+| --------------------------- | ----------------------------------------------------- |
+| `canon:canon-cli`           | To pick a `canon` verb, or learn which can lose edits |
+| `canon:youtube-transcripts` | A video transcript wanted as context                  |
+| `canon:read-frames`         | To read a recorded demo back frame by frame           |
+| `canon:teach-workspace`     | To learn a subject across sessions                    |
+| `canon:markdown-craft`      | Before a substantial markdown edit                    |
+| `canon:write-human`         | Before drafting or revising prose                     |
 
-Every row answers a question rather than marking a point in a project's life, so filing one under a phase on the [skill map](skill-map.md) would send a reader to the wrong group.
-
-A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:teach-workspace` folds in from a branch in its fold mode. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.
+Ask `canon:teach-workspace` to promote a learning workspace's reference pages and glossaries. It proposes a destination per page and waits. An Anthropic-owned subject goes to the wiki, an internal one to the matching context entry, and the rest to the public docs. A project with no wiki folder gets a refusal naming `canon wiki init`.

package/docs/workflow/skill-map.md

@@ -6,103 +6,99 @@ category: Workflow
 
 # Skill map
 
-Groups run in the order a project meets them. They reconcile the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, so every moment either one names has a group. Each row says when to reach for a skill, and its description says what it does.
-
-This page and [skill map on request](skill-map-on-request.md) are the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row across the two. A skill serving two moments sits at the earlier one, this page counting as earlier than the sibling, and a mention on any other page is prose rather than routing. The sibling holds the groups that answer a request rather than mark a moment.
-
-Each row sits under the group its skill's `metadata.family` names. The landing page's skills field groups by that field and reads each row's text from both pages, so its build refuses a skill with no row, a row naming no skill, a row filed under another group, and a heading on either page naming no family group, even one with no rows under it. A new group takes its vocabulary entry in `src/claude/skills-families.ts` before its heading lands here.
+Groups run in the order a project meets them. Every name `canon claude skills list --names` reports takes one row across this page and [skill map on request](skill-map-on-request.md), under the group its `metadata.family` names.
 
 ## Set up a project
 
-| Skill                | When to use                                                                                                 |
-| -------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `canon:target-setup` | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone       |
-| `canon:deploy-app`   | Once a project is ready to publish, to set up its Cloudflare or Vercel deploy and stop for token and domain |
+| Skill                | When to use                                   |
+| -------------------- | --------------------------------------------- |
+| `canon:target-setup` | On a fresh scaffold, to run the install chain |
+| `canon:deploy-app`   | When a project is ready to publish            |
 
 ## Decide what to build
 
-| Skill                      | When to use                                                                       |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| `canon:plan-intake`        | When the input is a pile of findings rather than one feature                      |
-| `canon:plan-intake-answer` | When an intake folder holds unread slots waiting on your decision                 |
-| `canon:backlog-triage`     | When the backlog needs pruning, to file a verdict per row and apply approved ones |
-| `canon:plan-groundwork`    | When the state is unmeasured and more than one approach is live                   |
-| `canon:decision-escalate`  | When open decisions turn on your preference and want batching into one set        |
-| `canon:draft-and-pick`     | When the call is taste and wants several candidates rendered side by side         |
-| `canon:canvas-board`       | When a direction should be drawn as frames the operator can see, select, and edit |
-| `canon:task-board`         | When a decided item needs a file on the board, or one is decided against          |
-| `canon:plan-feature`       | When the approach is settled and the next step is a plan                          |
-| `canon:codebase-layout`    | When a plan or change adds a file and you need to decide which folder holds it    |
+| Skill                      | When to use                                        |
+| -------------------------- | -------------------------------------------------- |
+| `canon:plan-intake`        | The input is a pile of findings                    |
+| `canon:plan-intake-answer` | An intake folder holds unread slots                |
+| `canon:backlog-triage`     | The backlog needs pruning                          |
+| `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
+| `canon:decision-escalate`  | Open decisions turn on your preference             |
+| `canon:draft-and-pick`     | The call is taste, wanting candidates side by side |
+| `canon:canvas-board`       | A direction should be drawn as editable frames     |
+| `canon:task-board`         | A decided item needs a file on the board           |
+| `canon:plan-feature`       | The approach is settled and needs a plan           |
+| `canon:codebase-layout`    | A change adds a file and needs a folder            |
 
 ## Build the feature
 
-| Skill                         | When to use                                                                                                |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `canon:session-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
-| `canon:auto-ship`             | After plan approval, to chain implement, verify, draft PR                                                  |
-| `canon:test-first`            | Before implementing a planned change, to run its test red, green, then refactor                            |
-| `canon:test-craft`            | When writing or changing any test, to pick its layer and filter what it asserts                            |
-| `canon:build-in-slices`       | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
-| `canon:api-design`            | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
-| `canon:deprecation-migration` | When deleting or replacing code something may still call, to migrate its callers and prove none remain     |
-| `canon:code-craft`            | Before writing a function, class, or module, to pick the shape the next change needs                       |
-| `canon:review-craft`          | When reviewing a change, for what to look for and how much evidence a finding needs                        |
-| `canon:search-craft`          | Before searching outside the project, to derive where the field's authorities publish and search there too |
-| `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
-| `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
-| `canon:video-craft`           | Before composing or judging a video, for sourced captions, zoom, pointer, and audio judgment               |
-| `canon:ui-checklist`          | After a UI change, to write what to look at and name what ships untested                                   |
+| Skill                         | When to use                                        |
+| ----------------------------- | -------------------------------------------------- |
+| `canon:session-worktree`      | At plan-to-execute, for an isolated tree           |
+| `canon:auto-ship`             | After plan approval, to chain implement through PR |
+| `canon:test-first`            | Before implementing a planned change               |
+| `canon:test-craft`            | Writing or changing a test                         |
+| `canon:build-in-slices`       | While building, to commit each slice               |
+| `canon:api-design`            | Changing what a caller sees                        |
+| `canon:deprecation-migration` | Deleting or replacing code something may call      |
+| `canon:code-craft`            | Before writing a function, class, or module        |
+| `canon:review-craft`          | Reviewing a change                                 |
+| `canon:search-craft`          | Before searching outside the project               |
+| `canon:systematic-debugging`  | A test fails or a bug surfaces                     |
+| `canon:design-taste`          | Drafting or judging an interface                   |
+| `canon:video-craft`           | Before composing or judging a video                |
+| `canon:ui-checklist`          | After a UI change, to list what to check           |
 
 ## Check the work before it leaves the branch
 
-| Skill                   | When to use                                                                       |
-| ----------------------- | --------------------------------------------------------------------------------- |
-| `canon:document-health` | When the documents themselves have to answer for length, placement, and staleness |
-| `canon:ux-audit`        | To read UI source for missing states, edge cases, and inconsistencies             |
-| `canon:ux-measure`      | To start the interface and measure paint, processor, and layout cost              |
+| Skill                   | When to use                                    |
+| ----------------------- | ---------------------------------------------- |
+| `canon:document-health` | Documents must answer for length and staleness |
+| `canon:ux-audit`        | To read UI source for missing states           |
+| `canon:ux-measure`      | To measure paint, processor, and layout cost   |
 
 ## Ship it
 
-| Skill                 | When to use                                                                                     |
-| --------------------- | ----------------------------------------------------------------------------------------------- |
-| `canon:git-ship`      | To run the whole post-feature chain from the verify gate through open PR                        |
-| `canon:context-fold`  | When decisions diverged from the plan, or the diff left a context entry stale                   |
-| `canon:task-complete` | After the fold, to mark the outcomes the diff shipped, or to archive a task the merge hook left |
-| `canon:docs-sync`     | When a change since main left `README.md` or `docs/` stale                                      |
-| `canon:git-stage`     | When the staged set spans several concerns and wants one commit each                            |
-| `canon:git-commit`    | When the staged set is one concern, or was staged hunk by hand                                  |
-| `canon:git-branch`    | When a branch name needs generating or renaming to conventional form                            |
-| `canon:git-pr`        | When a pull request needs a title and body written from the diff                                |
+| Skill                 | When to use                                   |
+| --------------------- | --------------------------------------------- |
+| `canon:git-ship`      | To run the post-feature chain through open PR |
+| `canon:context-fold`  | The diff left a context entry untrue          |
+| `canon:task-complete` | After the fold, to mark shipped outcomes      |
+| `canon:docs-sync`     | A change left `README.md` or `docs/` stale    |
+| `canon:git-stage`     | Staged changes span several concerns          |
+| `canon:git-commit`    | Staged changes are one concern                |
+| `canon:git-branch`    | A branch name needs generating or renaming    |
+| `canon:git-pr`        | A pull request needs a title and body         |
 
 ## After the pull request opens
 
-| Skill                  | When to use                                                            |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `canon:review-pr`      | From an independent session, to post findings on the PR itself         |
-| `canon:review-ui`      | Beside the code review, to drive the PR's checklist in the running app |
-| `canon:review-address` | On the worker's side, to fix posted findings and push a follow-up      |
-| `canon:git-followup`   | For a small self-review edit on a branch whose PR is already open      |
-| `canon:git-split`      | When a branch turns out to carry unrelated commits                     |
-| `canon:git-issue`      | When something surfaced that belongs on the tracker rather than here   |
-| `canon:git-worktree`   | After a PR merges, to list worktrees and reclaim the slot              |
+| Skill                  | When to use                                   |
+| ---------------------- | --------------------------------------------- |
+| `canon:review-pr`      | From an independent session, to post findings |
+| `canon:review-ui`      | Beside code review, to drive the checklist    |
+| `canon:review-address` | As the worker, to fix posted findings         |
+| `canon:git-followup`   | A small edit on a branch with an open PR      |
+| `canon:git-split`      | A branch carries unrelated commits            |
+| `canon:git-issue`      | Something belongs on the tracker              |
+| `canon:git-worktree`   | After a merge, to reclaim worktrees           |
 
 ## Run several tracks at once
 
-| Skill                     | When to use                                                                                                 |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `canon:role-orchestrator` | To assert the control session that owns the queue and dispatches a reviewer for each worker's PR            |
-| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass        |
-| `canon:role-reviewer`     | To assert the reviewing role for a cold session dispatched to review one pull request                       |
-| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                             |
-| `canon:session-relay`     | When this session owes another session a message, with or without a role                                    |
-| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                              |
-| `canon:session-compact`   | Before a compaction or a move to another machine, to write a plain session's handoff note outside the board |
-| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                                   |
+| Skill                     | When to use                                         |
+| ------------------------- | --------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that dispatches       |
+| `canon:role-planner`      | To assert the role of a session writing a plan      |
+| `canon:role-reviewer`     | To assert the role of a session reviewing one PR    |
+| `canon:role-worker`       | To assert the role of a session building one branch |
+| `canon:session-relay`     | This session owes another a message                 |
+| `canon:session-resume`    | At session start, to pick up a previous one         |
+| `canon:session-compact`   | Before a compaction, to write a handoff             |
+| `canon:session-map`       | When an orchestrating session closes                |
 
 ## Keep the project current with the toolkit
 
-| Skill                         | When to use                                                                            |
-| ----------------------------- | -------------------------------------------------------------------------------------- |
-| `canon:target-check`          | In a target project, to report per domain what it holds against what the toolkit ships |
-| `canon:canon-feedback`        | When something in the toolkit is broken, missing, or off, to open an issue on it       |
-| `canon:canon-feedback-triage` | In the toolkit repo, to file the open feedback issues into an intake folder            |
+| Skill                         | When to use                                          |
+| ----------------------------- | ---------------------------------------------------- |
+| `canon:target-check`          | In a target, to compare each domain with the toolkit |
+| `canon:canon-feedback`        | The toolkit is broken, missing, or off               |
+| `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues         |

package/docs/workflow/visual-design-workflow.md

@@ -6,147 +6,54 @@ category: Workflow
 
 # Visual design workflow
 
-Three tiers cover the range from prose-only design docs to a fully graphical design source of truth. Pick one per project based on how UI-heavy the work is, whether stakeholders review visuals, and whether a designer is involved. Tiers stack, so moving up does not invalidate work done at a lower tier.
-
-The tier framework sits alongside [Claude Design](../../wiki/claude/design.md), the one catalog page in this range. Excalidraw and the surrounding MCP and skill ecosystem are named inline below rather than catalogued separately. This page decides when to reach for what.
-
-[Claude Design](../../wiki/claude/design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool for tier 1 and tier 2. Reserve it for codebase extraction and the richly annotated handoff bundle.
+Three tiers run from prose-only design docs to a graphical source of truth, and tiers stack. [Claude Design](../../wiki/claude/design.md) is the ceiling tool for tiers 1 and 2.
 
 ## Tier 0: prose only
 
-The default. `canon/DESIGN.md` holds visual intent, being one Overview paragraph, at most three one-line rules a section, and a table naming what each color and shape role is for. Its lead names the stylesheet the values live in, since a hand-typed copy of them drifts from the CSS.
-
-Claude Code reads it and writes the implementation. Works for CLI tools, internal dashboards, admin panels, and backend-focused projects.
-
-### Seed shape
-
-The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships an intent template with a starting set of roles, each naming its custom property, and `claude/skills/canvas-board/references/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the parser reads, so they stay verbatim in either, while the rows are the project's own. The seed's lead asks for the project's own stylesheet, such as `src/styles/tokens.css` or a Tailwind `@theme` block, and falls back to `.claude/design/project/` only when the project has none.
-
-`canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design/index.md`.
-
-A project wanting a neutral starting point to override runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying an achromatic token set as custom properties and two components built on them. Greys run from near-black to near-white and the accent is monochrome, so the only palette the project renders is one it writes itself. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record the project wrote is its own, and the installed stylesheet is the toolkit's.
-
-A record generated from a token source carries the values in tables instead, which is the shape this toolkit's own record takes. There a cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
-
-### Tools
-
-- None beyond Claude Code itself
-- Playwright CLI optional for verifying journeys across routes and browser-only behavior. See [`test-craft`](../../claude/skills/test-craft/SKILL.md) for which layer a journey belongs at.
+The default. `canon/DESIGN.md` holds visual intent as one Overview paragraph, at most three one-line rules a section, and a table naming each color and shape role, with a lead naming the stylesheet. Claude Code alone suffices, and [`test-craft`](../../claude/skills/test-craft/SKILL.md) says which layer a Playwright journey belongs at.
 
-### Skills
+- The seed is `tooling/claude/seeds/canon/DESIGN.md`, and its column headers stay verbatim
+- `canon design render` previews it in `.canon/tmp/render/design/`
+- `canon design install` copies a neutral base to `.claude/design/base.css`, so override values in `.claude/design/project/`. See `canon/context/features/design.md`.
 
-#### Reviewing and measuring
+These skills cover the tier:
 
-- `canon:ui-checklist` for what a reviewer has to look at after UI changes, and what ships without a test
-- `canon:ux-audit` for UX gap detection on existing surfaces
-- `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
+- `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
+- `canon:draft-and-pick` drafts candidates as frames on the canvas and takes your pick
+- `canon:canvas-board` works a direction out as HTML frames you edit in the browser. Only the pick moves into `canon/DESIGN.md`.
+- `canon:draft-identity` drafts a logo mark and social card
 
-#### Drafting
-
-- `canon:draft-and-pick` for a call settled by looking, drafting several candidates as frames on the canvas and taking your pick
-- `canon:canvas-board` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
-- `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.
-- Anthropic's `frontend-design` plugin optional for light visual steering
-
-### When to pick
-
-- UI is not the core product
-- Design decisions are few and can be written as sentences
-- No designer on the project
-- Stakeholders review code or behavior rather than mockups
+Pick tier 0 when the UI is not the core product, decisions fit in sentences, and stakeholders review code.
 
 ## Tier 1: visual companion
 
-Prose stays as source of truth. Add a visual render as a feedback surface for the agent and for human review.
-
-- Excalidraw handles agent-drawn layouts when the round-trip canvas loop matters
-- Claude Design joins only when codebase extraction or the annotated handoff bundle is worth the ceiling cost
-
-Both produce derived artifacts, so human edits are review annotations rather than source changes.
-
-### Seed shape
-
-Same as tier 0. `DESIGN.md` stays human-maintained.
-
-Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in its own format. These are separate files from the toolkit's `canon/DESIGN.md` and are not synced with it. Treat impeccable's pair as its own source of truth for its commands, and the toolkit's `canon/DESIGN.md` as the source other toolkit skills read.
-
-### Tools
-
-- Excalidraw canvas server on localhost plus the community [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw) MCP shim, for projects that need an agent to draw, read back, and revise a canvas. MIT-licensed, plaintext JSON scene format. `describe_scene` and `get_canvas_screenshot` let the agent verify its own layout before claiming it is correct.
-- Playwright MCP ([`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp)) for browser-side verification, driven off the accessibility tree rather than screenshots.
-- Chrome DevTools MCP ([`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)) for live frontend debugging: performance traces, network inspection, and DOM and CSS inspection.
-- Claude Design as the ceiling option for codebase extraction or polished handoff bundles. See [Claude Design](../../wiki/claude/design.md).
+Prose stays the source of truth, with a visual render as a feedback surface. Human edits to these derived artifacts are review annotations.
 
-### Skills
+- Excalidraw canvas server plus the community [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw) MCP, where the agent draws, reads back, and revises
+- Playwright MCP ([`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp)) for browser checks off the accessibility tree
+- Chrome DevTools MCP ([`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)) for traces, network, DOM, and CSS
+- Claude Design for codebase extraction or a polished handoff bundle
+- A frontend design skill: [pbakaus/impeccable](https://github.com/pbakaus/impeccable), [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), or Anthropic's `frontend-design`
 
-- Everything from tier 0
-- A frontend design skill to steer visual quality. Pick one of [pbakaus/impeccable](https://github.com/pbakaus/impeccable), which bundles curated anti-pattern references and is the strongest default, [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), which maps product type to UI rules through a reasoning engine, or Anthropic's `frontend-design` plugin.
+Impeccable keeps its own root `DESIGN.md` and `PRODUCT.md`, separate from `canon/DESIGN.md`. Use Excalidraw for agent-driven layout iteration, and Claude Design for one extraction pass or the final handoff. Most projects pick one.
 
-### When to pick
-
-- UI is a meaningful part of the product but not the entire product
-- Stakeholders want to see layout proposals before code exists
-- Design decisions benefit from visual inspection
-- A single contributor owns both design and implementation
-
-### Excalidraw vs Claude Design in tier 1
-
-The two tools solve non-overlapping halves of the visual companion problem.
-
-Excalidraw gives the agent a canvas it can read back over MCP. Output is agent-facing and persists as a JSON file in the repo. Pick it when Claude Code needs to iterate on layouts autonomously, not when a human needs polished review artifacts.
-
-Claude Design reads the raw codebase without prose curation and produces a polished handoff bundle with chat history. Weekly quota makes it expensive, so reserve it for the extraction pass or the final handoff moment, not daily iteration.
-
-Most tier 1 projects pick one. Projects with a messy codebase and no curated `DESIGN.md` may want Claude Design once for the initial extraction.
+Pick tier 1 when stakeholders want layouts before code and one contributor owns design and implementation.
 
 ## Tier 2: visual as source of truth
 
-Design happens in a graphical tool. `canon/DESIGN.md` either regenerates from the graphical source or takes a secondary role as agent-facing summary. Implementation follows the graphical source, either through an MCP round-trip or a one-way handoff bundle. Fits teams with a dedicated designer or projects where design iteration outpaces code changes.
-
-### Seed shape
-
-`canon/DESIGN.md` becomes a generated artifact. A top-of-file note identifies the upstream source, either a Claude Design project ID or a Figma file URL. Manual edits in the seed carry a warning tag because they will not survive regeneration.
-
-### Tools
-
-- Figma desktop app with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture of a running Claude Code UI into editable Figma frames.
-- Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../../wiki/claude/design.md).
-- Playwright and Chrome DevTools MCPs as in tier 1
+Design happens in a graphical tool, and implementation follows it. `canon/DESIGN.md` becomes generated, with a top note naming the upstream Claude Design project ID or Figma file URL.
 
-### Skills
+- Figma desktop with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/) for teams with a designer already on Figma. It syncs both ways and captures a running UI into editable frames.
+- Claude Design with its Claude Code handoff bundle for teams without Figma. The handoff is one-way.
+- The Playwright and Chrome DevTools MCPs from tier 1
 
-- Everything from tier 1
-
-### When to pick
-
-- UI is the product or a major differentiator
-- A dedicated designer is on the project or will join
-- Design review happens in the graphical tool rather than in code
-- Design changes more often than implementation
-
-### Figma vs Claude Design in tier 2
-
-Figma wins when a dedicated designer already owns a Figma file, external collaborators expect Figma for review, or the workflow needs the agent to capture a running Claude Code UI and push it back as editable frames via Code to Canvas. Figma's MCP is bidirectional.
-
-Claude Design wins when nobody on the team has a Figma workflow yet and the handoff bundle with chat history is the intended implementation path. Claude Design's handoff is one-way, and its quota limits daily iteration, so it is most useful for the initial extraction pass and the final handoff moment rather than day-to-day design work.
+Pick tier 2 when the UI is the product, a designer owns it, and design changes more often than code.
 
 ## Decision guide
 
-Four questions. Each yes weighs toward a higher tier.
+Count yes answers to four questions. Zero or one is tier 0, two or three is tier 1, and four is tier 2.
 
 - Is the UI the product rather than a thin interface over a backend?
 - Do non-engineers review visual proposals before code exists?
 - Is there a dedicated designer, or will there be one?
 - Does design iterate independently of code?
-
-Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2.
-
-Resist over-tiering early. Moving up is cheap because tiers stack. Moving down means abandoning tooling and confusing collaborators.
-
-## References
-
-- [Claude Design](../../wiki/claude/design.md): first-party hosted design product and handoff bundle
-- `canon/context/claude-plugin/skill-strategy/overview.md`: how to decide between workflow and domain-knowledge skills
-- [`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp): browser automation MCP used in tier 1 and tier 2
-- [`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp): live frontend debugging MCP used in tier 1 and tier 2
-- [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw): community MCP server behind the tier 1 visual companion