@erclx/canon 5.42.0 → 5.44.0

package/claude/skills/record-screencast/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: Why compiling and running a screencast draft needs a routed skill r
 
 ## Gap
 
-Without this skill, `draft-screencast` writes a draft and names `canon demo compile` as the next step, and nothing after that routes a session there or to `canon demo run`. An operator has to know both verbs, type them in order, and read the compile record for unresolved fields by hand. A session that fills one in on its own reproduces the exact failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it.
+Without this skill, `script-screencast` writes a draft and names `canon demo compile` as the next step, and nothing after that routes a session there or to `canon demo run`. An operator has to know both verbs, type them in order, and read the compile record for unresolved fields by hand. A session that fills one in on its own reproduces the exact failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it.
 
 ## Must
 
@@ -25,7 +25,7 @@ Without this skill, `draft-screencast` writes a draft and names `canon demo comp
 - Guess or fill a target, a URL, or any other unresolved field
 - Drive the application through anything other than `canon demo run`
 - Install HyperFrames, vendor it, or restate its composition rules, which its own skills own
-- Assume this skill's own invocation frequency needs no check. `draft-screencast`'s closing block names it by hand, but whether anything else reaches for it beyond that pointer or an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
+- Assume this skill's own invocation frequency needs no check. `script-screencast`'s closing block names it by hand, but whether anything else reaches for it beyond that pointer or an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
 
 ## Guards
 
@@ -33,6 +33,6 @@ Without this skill, `draft-screencast` writes a draft and names `canon demo comp
 
 ## Out of scope
 
-- Drafting the beats, which `draft-screencast` owns
+- Drafting the beats, which `script-screencast` owns
 - Filling an existing plan's target or URL, which is the operator's own edit
 - Verifying a recording beyond its own caption, which nothing in the toolkit does yet

package/claude/skills/record-screencast/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: record-screencast
-description: Drives a screencast draft through to a recording. Compiles it with `canon demo compile` when no plan exists yet at the default path, skipping compile when one is already there, runs `canon demo run` once nothing is unresolved, then composes the take into a finished mp4 through HyperFrames when the draft's wrap section asks for anything. Reports every unresolved field from the compile or run record and stops rather than guessing one. Use when asked to "record the screencast", "run the demo", "compile and record this draft", or right after `draft-screencast` prints its next-step line. Do NOT use to draft the beats, which is `draft-screencast`, or to fill in a plan's target or URL, which is the operator's own edit.
+description: Drives a screencast draft through to a recording. Compiles it with `canon demo compile` when no plan exists yet at the default path, skipping compile when one is already there, runs `canon demo run` once nothing is unresolved, then composes the take into a finished mp4 through HyperFrames when the draft's wrap section asks for anything. Reports every unresolved field from the compile or run record and stops rather than guessing one. Use when asked to "record the screencast", "run the demo", "compile and record this draft", or right after `script-screencast` prints its next-step line. Do NOT use to draft the beats, which is `script-screencast`, or to fill in a plan's target or URL, which is the operator's own edit.
 metadata:
   family: generate
 ---
@@ -9,7 +9,7 @@ metadata:
 
 ## Guards
 
-- If no draft path is given, stop: `❌ No draft path. Pass the path draft-screencast printed.`
+- If no draft path is given, stop: `❌ No draft path. Pass the path script-screencast printed.`
 - Never guess or fill an unresolved field, a target, a URL, or anything else the compile or run record names. Report it and stop.
 - Filling one in reproduces the failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it
 - Never pass `--force` to compile. A plan at the default output path may carry timing tuned by hand that the draft cannot reproduce.

package/claude/skills/role-orchestrator/REQUIREMENT.md

@@ -79,7 +79,7 @@ Dispatch parts from what it checked in three ways. The gate and the worker each
 - Name each self-dispatched worker explicitly with the `worker-` prefix, since that is the role the name marks and a client-derived name is a fragment of the session's identifier
 - Carry the dispatcher's `sessionId` in the launch prompt, since a worker owed two messages has no property on the roster that resolves a controller and a name goes stale inside the window it builds in
 - Report each self-dispatch and the row it fired against loudly enough to follow, since a person no longer watches the launch step happen
-- Stop dispatching once `## Run now` is empty or every row in it reads claimed, rather than waking again to fire on a board nobody is clearing
+- Stop dispatching once `## Up next` is empty or every row left in it is held, rather than waking again to fire on a board nobody is clearing
 - Launch a planner or worker the operator will talk with from the talk shape, with the `-talk` suffix and the brief sentence that tells it so, since a cold launch retires the session the moment its delivery lands while the operator still wants the conversation
 - Retire a talk session only on the operator's word and report it as held open until then, since its delivery says nothing about whether the conversation is over
 - Dispatch every non-release pull request's review to `role-reviewer`, leave each round's messages to it and the worker, and keep one cross-branch pass per wave here, since any pass or relay run here bills the context the wave shares

package/claude/skills/role-orchestrator/SKILL.md

@@ -132,6 +132,8 @@ A worker is a separate process the controller can steer, and scope reaches it th
 - Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
 - Do not hand a worker anything but a plan, which carries exact diffs only when already known and otherwise states scope and open questions
 
+A late ask about a building row is a follow-up filed through `task-board`, with the ask as its origin and the running task cited in the intro. Amend the plan only on the operator's word, naming the re-review cost, and message the worker.
+
 The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards, which is the separation `review-pr` exists to supply.
 
 ### Filing a row

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

@@ -3,7 +3,7 @@ title: Orchestrator dispatch runbook
 description: The plan-answer gate, the collision check before a self-dispatch, the conflict check against the tracks in flight and the evidence it rests on, the branch the launch names, the one model test applied to each role, the fallback to a human launch, and the loop's stopping condition
 ---
 
-Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The conflict check below is where that row is tested against every track in flight, and it is the one statement of what holds a row there.
+Run this at loop step 4, for a `## Up next` row whose plan is verified, in place of handing the worktree to a human. The conflict check below is where that row is tested against every track in flight, and it is the one statement of what holds a row there.
 
 ## Contents
 
@@ -40,6 +40,7 @@ Never shorten a non-conforming slug here, since a rename parts the branch from t
 
 Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record. Branch on `launchable` rather than on the exit code, which a wrapping shell function can flatten to zero and so read a held row as clear.
 
+- Hold a row whose `Waiting on` has not cleared, which no other check reads
 - `launchable: true`: the plan answers itself, so proceed to the branch check.
 - `launchable: false`: report every entry in `open`, each with its question label and stated reason, and hand the row to the human-launch line below
 - Never fill the slot on the operator's behalf, the one move the plan standard forbids outright
@@ -152,6 +153,8 @@ A row qualifies for that pick when its plan carries no open question and touches
 
 Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template, which sits beside the review-address and planning shapes that skip these checks. A cloud row launches from `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md`, since the VM shares no plugin or board.
 
+Once the launch succeeds, run `canon tasks promote <stem>`.
+
 ## Fall back to the human
 
 Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one. A shared file alone is not listed.
@@ -171,4 +174,4 @@ Hand the person one command, `/canon:auto-ship <plan>`, naming the row, the plan
 
 ## Stop the loop
 
-Wrapped in `/loop`, re-run the check against `## Run now` on each wake, and stop once the group is empty or every row reads `claimed: true`. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.
+Wrapped in `/loop`, re-run the check against `## Up next` on each wake, and stop once the group is empty or every row left in it is held. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.

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

@@ -65,5 +65,9 @@ Keep the detail below the block and keep it skippable. A decision reached at the
 
 - Reuse the vocabulary above rather than inventing a second one
 - Keep a file set on the row claiming it, so the reader can check a hold or a shared-path claim instead of taking it
+- Name a session by its launch name in any line sending the operator into it, such as `claude attach worker-frameboard-design-reference-set`, with the id in parentheses
+  - A bare id tells the operator nothing about which session it is
+  - A rename leaves the launch name matching nothing, so read the current name off `canon sessions list --json` when the line is written
+  - `claude rm` takes the id alone, so that line carries the id
 
 Write no shape for a correction. A correction is a sentence, and a format for admitting error invites ceremony where plainness is the whole value.

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

@@ -55,7 +55,7 @@ Every measurement this pass takes decides whether a row can start rather than ho
 
 Write the result into the row, since a re-test reported in chat is lost at the next compaction and measured again.
 
-- Rewrite a blocker cell whose test no longer holds, and move the row to the group its new state puts it in
+- Rewrite a blocker cell whose test no longer holds through `canon tasks block <stem> "<blocker>"`, and move the row to the group its new state puts it in through `canon tasks place`
 - Record the measurement in the task's `## Findings` as a line labeled with this session and the date, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`
 - `### Writing the board` in `role-orchestrator` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report
 
@@ -69,7 +69,7 @@ A backlog row carries no blocker cell, since `${CLAUDE_SKILL_DIR}/../task-board/
 
 ### Moving a cleared row
 
-A cleared row moves out of `backlog.md` onto the bottom of `## Needs a plan`, with a `Waiting on` cell stating what changed and ending with the word `last`.
+A cleared row moves out of `backlog.md` onto the bottom of `## Needs a plan` in one call, `canon tasks place <stem> --group needs-a-plan --bottom --waiting "<what changed>. Last"`.
 
 - `canon tasks validate`'s ordering check reads `last` as the ordinal the bottom placement claims
 - A cell stating only what changed matches neither the ordinal nor the rank reading, raising a finding against the pass's own row

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

@@ -25,7 +25,7 @@ The third trigger reaches a window the first two cannot. A session with three wo
    - Run `task-complete` to archive one the hook left in place
    - A task whose outcomes are standing policy never closes, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason and archive once that branch merges
    - Encoding it from this session would write a tracked file, which `## Boundaries` in the skill body forbids
-4. Read `.canon/tasks/priority.md` and count entries under its `## Run now` heading that carry a written plan. Keep one in reserve beyond what is running.
+4. Read `.canon/tasks/priority.md` and count the `## Up next` rows whose `Waiting on` has cleared, since a blocked row is no reserve. `## Run now` is what is running, so keep one in reserve beyond it.
 5. Promote from the top of `## Needs a plan`, where the last sweep recorded what to plan next.
    - Depart from that order when something changed under it and say what, since a position nobody honors is the ordering going stale
    - The order is set by whether a task establishes functionality, so prefer one that adds or proves a mechanism over one that trims, tidies, or audits
@@ -53,27 +53,32 @@ That block is the detail. Lead the reply with the three slots under `## Every la
 
 ## Writing the board
 
-Promoting, demoting, and archiving a row all write `.canon/tasks/priority.md`, and this session is the only writer apart from `canon tasks archive`. Moving a task between the board and `.canon/tasks/backlog.md` writes both files, and this session is that file's only writer.
+Write `.canon/tasks/priority.md` through the `canon tasks` verbs alone, each reading the file once, rendering every table, and writing it once. Beside this session, `canon tasks archive` drops a shipped row and `plan-link` promotes a parked one.
 
-- Edit with the file-editing tool, which errors on a non-match, where a shell stream editor or an inline replace exits clean and leaves the board wrong
-- Write both halves of a move before reporting it, since a row on neither surface leaves a task file nothing names in a gitignored folder with no history
-- `canon tasks validate` reports that state, so run it after any move
-- Put the reason a row sits where it does in its Waiting on cell, since a row promoted with the cell left alone carries an order the next sweep cannot check
+| Move                                      | Verb                                                       |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| A backlog row onto the board, or across   | `canon tasks place <stem> --group <group> --waiting "..."` |
+| A planned row to `## Run now` on dispatch | `canon tasks promote <stem>`                               |
+| A row up or down inside its group         | `canon tasks move <stem> --before <stem>`                  |
+| What a row waits on, or why it sits there | `canon tasks block <stem> "<reason>"`                      |
+
+- `place` removes the task's backlog line in the same call, so a row never sits on both surfaces or on neither
+- Demoting a row to `backlog.md` has no verb yet. Add the backlog line first, then delete the row with the file-editing tool, which errors on a non-match.
+- Put the reason a row sits where it does in its Waiting on cell through `block`, since a row promoted with the cell left alone carries an order the next sweep cannot check
+- Run `canon tasks validate` after any move, which reports a hand edit the verbs would have refused
 
 ### Columns and read-back
 
-Each column carries a fact a later reader checks rather than reasons again.
+The verbs derive the Task, Touches, and Plan cells from the task file and its live plans, so a later reader checks them rather than reasoning again.
 
-- Put a pointer in the Plan column, never prose, since `auto-ship` refuses at its guard when the column leads to no plan, spending a dispatch
-- `## Run now` claims a written plan covers every open outcome, which is what the pointer backs
-- Name the file set in the Touches column, which feeds the merge order and the shared paths a dispatch names, so step 6's hold call stays checkable later
-- Re-resolve every Plan pointer after anything archives a plan
-- Read the file back after writing it, since the row that lands is the row a worker acts on
+- `place` and `promote` refuse a row the target group's test fails, so a Plan cell never leads `auto-ship` to no plan and spends a dispatch
+- A Touches cell differing from its plan's list is `touches-stale`. Change the plan's list rather than the cell, and step 6's hold call reads the result.
+- Read the board back after a write, since the row that lands is the row a worker acts on
 
 ### Stale plan pointers
 
 A Plan pointer goes stale from a merge this board never sees. The `post-merge` hook moves a plan to `.canon/plans/archive/` through `canon tasks archive` and rewrites the citation in the archived task file alone.
 
-- A row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved
+- A row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved, until the next verb call re-derives every Plan cell from the live plans
 - `task-complete` marks outcomes on each worker's branch and moves nothing, so the move lands at the merge
 - The board then reads as correct until a pointer is followed

package/claude/skills/role-planner/REQUIREMENT.md

@@ -61,7 +61,7 @@ four carried at least one, caught only because the planner ran
 - Owe an announcement when the record lands, carrying the path and what the row got wrong, since the controller cannot watch the read happen
 - Owe a message before a block becomes an interactive prompt, since a session already waiting on input never reaches the tool round an inbound message drains at
 - Keep correcting the dispatcher a first-class move carrying its evidence, since a trial corrected a brief's premise, planned every row anyway, and carried the consequence into a plan question
-- Carry a talk clause for a launch whose operator is in the session, putting each open question to them, recording a settled pick in place, and owing a close message when they end the conversation, since a cold planner's halting rules contradict a brief that asks it to talk
+- Carry a talk clause for a launch whose operator is in the session, putting each open question to them, recording a settled pick in place, sending an ask about a row now building to the controller rather than the worker, and owing a close message when they end the conversation, since a cold planner's halting rules contradict a brief that asks it to talk
 - Point at each of the three skills for its record's shape and the steps that write it
 - Defer the addressee resolution to `session-relay` and keep only the last-rung inference, which discriminates differently here than it does for a worker because a session in this role holds no feature branch either
 

package/claude/skills/role-planner/SKILL.md

@@ -72,7 +72,8 @@ The plan standard fixes that block for a feature plan, and a groundwork or intak
 
 ## The board is read-only
 
-- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md` by hand. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- `canon tasks plan-link` is the one board write this role makes. It moves the row out of `## Needs a plan` once the plan is linked, in one read and one write a hand edit cannot match.
 - Never write the task file. The record is the whole output, and a row edited from here changes what the controller reads back as the board's state.
 - Report what the row got wrong rather than repairing it, such as a stale count or a dead path, in the record and the handback. The controller decides which carries the correction.
 - Leave the cross-feature call alone. `priority.md` shows enough to write a confident merge order off a partial picture, which is the failure this boundary prevents.
@@ -101,10 +102,10 @@ One rung stays here because it differs between roles. Inference takes the sessio
 
 A launch whose brief says it is a talk session puts the operator in this one. Everything above holds, and the clause below changes how questions are answered and when the role ends. A launch carrying no such sentence takes none of this.
 
-- Put each open question to the operator through the structured question surface before writing the record, and record a settled pick in place per the plan standard
-- Never fill an `- Answer:` slot the operator did not answer
+- Put each open question to the operator through the structured question surface before writing the record
+- Record each pick per `### Overrides and settled questions` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
 - Keep answering under `plan-feature`'s discussion rounds after the record lands, since the operator launched this session to keep talking.
-- Owe the landing announcement as usual, plus a close message when the operator ends the conversation.
+- Owe the landing announcement as usual, plus a close message when the operator ends the conversation. Send an ask about a building row to the controller, never the worker.
 - Skip the before-prompt block message for a question put to the operator in the session. Keep it for a block the operator cannot answer, since a controller learns of a stall only from a message.
 
 The operator being present is an assumption the launch carries. A talk planner whose operator has walked away waits silently on its first question, so say what the session is waiting on in the turn it stops.

package/claude/skills/role-worker/REQUIREMENT.md

@@ -35,6 +35,8 @@ The draft mark fails from both ends. On 2026-08-31 four sessions re-drafted a pu
 - Keep refusing a dispatcher a first-class move carrying its evidence, since the halts measured so far were correct and the cost of each fell where it belonged
 - State that a held body may be older than the branch under it, since a plugin skill loads from the marketplace cache rather than from the working tree
 - Carry a talk clause for a launch whose operator is in the session, asking them at a judgment call and sending a close message when they end the conversation, since a cold worker's halt-toward-the-controller and merge-ends-the-role rules contradict a brief that asks it to talk
+- Freeze the plan's scope at dispatch, sorting a late ask into a defect to fix, a follow-up row to report, or an addition the operator's word admits with its re-review cost stated, since intake 155 measured about four UI review rounds on one pull request from late asks, each re-running both reviews
+- Own the local preview server for a painted diff, started as a tracked background command before the pull request opens, since a `no-server` read leaves the evidence comment and the UI reviewer without an address on the one path nobody watched being built (erclx/frameboard#1 and erclx/frameboard#4)
 - Point at `session-worktree`, `auto-ship`, and `review-address` for the steps each already owns
 
 ## Must not

package/claude/skills/role-worker/SKILL.md

@@ -36,9 +36,41 @@ A ready folder and the draft mark each carry work another session already did, s
 
 ### Overriding a plan question
 
-Rewrite an unanswered question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against it, leaving `- Answer:` blank, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+Follow `### Overrides and settled questions` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` when this build decides against a suggestion.
 
-Put the same deviation in one line under the open task's `## Findings`, opening with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
+Open the task's `## Findings` line for an override with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
+
+### The preview server
+
+A painted pull request needs a server in this worktree for `canon pr local` to find, and this session is the one with a lifetime to own it. `auto-ship` Step 5 decides whether the diff is painted, so this body restates no file test.
+
+- Run `canon pr local --json` first and start nothing when `reason` reads `ok`
+- Otherwise start the stack's `dev` script as a background command from the worktree root before the pull request step. `dev` follows the worktree, so a `review-address` fix shows on the same link.
+- Wait up to 60 seconds for the verb to read `ok`, then ship either way. A stack with no `dev` script gets no start, and `pr-evidence` reports `no-server`.
+- Never detach it with `nohup`, `setsid`, or `disown`, since the owning session is the stop. `canon worktrees reclaim` ends any listener left in a worktree it removes.
+
+A hand-run `git-ship` or `git-pr` starts no server, since only a worker has a lifetime to own one.
+
+### Building against a design reference
+
+A plan carrying a `**Design references:**` section names the accepted design for the surface it changes. Open it before building, since the build matches it and a worker that reads the dark image alone ships a light theme nobody saw.
+
+- Open each cited folder's light and dark images and its frame HTML before the first edit to that surface
+- Take sizes, spacing, and colors from the frame HTML rather than from the image
+- Report a reference that does not resolve in the working tree, naming the path, rather than building without it
+- Leave `None identified.` as it stands and build without a reference
+
+## Scope after dispatch
+
+The plan is the scope from the dispatch on. A late ask restarts both reviews, and one pull request took about four UI review rounds from asks that arrived mid-build.
+
+Sort each ask that arrives after dispatch three ways:
+
+- A defect is a failed outcome or a regression in what the plan builds. Fix it in this build, and take every review finding on the pull request through `review-address` the same way.
+- Anything else is a follow-up row. Do not build it. Reply with the follow-up wording, and report the row to the controller with its title, origin, and surface.
+- Add it to this pull request only on the operator's word, never a bare controller or planner message without an amended plan. Before the commit, say that both reviews run again.
+
+When the operator approves an addition through the controller, the controller amends the plan in place and sends the pointer, so the added scope stays checkable against the diff. Fall back to `session-relay`'s copyable block when no controller is live, and never drop the row.
 
 ## The board is read-only
 
@@ -107,6 +139,7 @@ A launch whose brief says it is a talk session puts the operator in this one. Ev
 
 - Ask the operator in the session through the structured question surface at a judgment call, rather than halting toward the controller
 - Put a plan question written as needing the operator's call to them directly
+- Sort a late ask from the operator in place under the scope rule above, and send the controller the follow-up row rather than relaying the ask
 - Send the controller a close message when the operator ends the conversation, beside the announcements the channel above owes.
 - Keep the before-prompt block message for a block the operator cannot answer. A question put to the operator who is in the session needs none.
 

package/claude/skills/script-screencast/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: script-screencast
+description: Why a recording script ships pre-seeded rather than blank, what the four discovery questions buy, and why the draft stays stack-agnostic
+---
+
+# Script screencast requirement
+
+## Gap
+
+Without this skill, a recording plan arrives as a wall of blank fields, so the user fills a template instead of editing a draft and the work the skill was meant to do lands back on them. The opposite failure costs more. A session that skips discovery guesses the audience, the length, and the hero moment, then writes five beats for a video nobody asked for, and every one of them has to be thrown away rather than edited.
+
+A draft that names the recording software, the editing software, or the window manager pins the script to one machine and one person's setup, so it stops being reusable the moment anyone else records. And re-invoking to refine silently overwrites the edits the user made in the file, which is the one failure that destroys work rather than wasting it.
+
+## Must
+
+- Read project context and recent commits before proposing, since what shipped recently is usually the subject
+- Ask exactly four discovery questions, each carrying a default derived from that context
+- Wait for answers rather than reading silence as acceptance
+- Pre-seed every section with concrete content so the draft is shippable as written and the user edits down
+- Derive the slug from the topic and the discovery answers
+- Write to `demos/<slug>/beats.md` at the project root, the committed folder the rest of the demo lives in, and print that path on its own line
+- Seed a wrap section naming intro, outro, and music with a default each, so the choice of what surrounds the take is made at draft time rather than discovered at compose time
+
+## Must not
+
+- Name recording software, editing software, fonts, or window managers
+- Record, edit video, or generate captions
+- Re-run against an existing draft to refine it, since re-running overwrites
+- Infer the hero moment without asking, which is the beat the whole script is built around
+
+## Guards
+
+- No topic provided: stop rather than guessing what is being recorded
+
+## Out of scope
+
+- Producing the recording, which `record-screencast` owns
+- Refining an existing draft, which is a direct edit of the file
+- Slide decks, which `make-deck` owns
+- Where the recording ships, which the draft lists and the user decides

package/claude/skills/script-screencast/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: script-screencast
+description: Drafts a screencast script with pre-seeded beats, defaults, and decisions to `demos/<slug>/beats.md`. Reads project context, asks four discovery questions with proposed defaults, then writes a shippable draft. Use when asked to "draft a screencast", "write a recording script", "plan a demo video", or "scaffold a screencast for X". Do NOT re-invoke to refine an existing draft. Re-running overwrites. Edit the draft file directly.
+metadata:
+  family: generate
+---
+
+# Script screencast
+
+## Guards
+
+- If no topic is provided, stop: `❌ No screencast topic. Describe what you are recording.`
+- Draft, then hand off. Do not edit video, generate captions, or drive the application, since a recording is `record-screencast`'s job. Name it as the next step and stop.
+- Stack-agnostic in the draft. Never name a recording tool, an editing tool, a font, or a window manager.
+- Keep selectors, URLs, wait conditions, and timings out of the beats, since the compiler adds those four in a plan of its own and a beat carrying them stops being readable
+
+## Step 1: read the project context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules and project pitch
+- `canon/REQUIREMENTS.md`: feature scope, non-goals, audience hints
+- `.canon/tasks/index.md`: current scope
+- Recent commits via `git log --oneline -20 2>/dev/null || echo "FALLBACK"`: what shipped recently is usually the recording subject.
+
+## Step 2: discovery with proposed defaults
+
+Ask exactly four questions in chat. Each carries a proposed default derived from Step 1. The user confirms, overrides, or says "use defaults" to accept all.
+
+```markdown
+**Discovery:**
+
+1. Audience: proposing technical peers. Override?
+2. Length: proposing 75-90s. Override?
+3. Hero moment: proposing <best guess from context, or "the single thing that has to land">. Override?
+4. What to cut: proposing <best guess, or "anything that is not the hero moment">. Override?
+```
+
+Wait for answers before drafting. Do not infer silence as acceptance.
+
+## Step 3: derive the slug
+
+Build a 2-to-4-word kebab-case slug from the topic and discovery answers. Examples: `auth-flow-redesign`, `cli-onboarding`, `inline-edit-launch`.
+
+## Step 4: write the draft
+
+Create `demos/<slug>/beats.md` at the project root, creating the folder if it does not exist. The file is committed with the rest of the demo's sources, so a recording can be rebuilt from the folder alone.
+
+### Fill the template
+
+Write all nine sections from `${CLAUDE_SKILL_DIR}/references/beats-template.md`, read on reaching this step. Pre-seed every section with concrete content so the draft ships as-is, and the user edits down rather than fills blanks. A run stopped at discovery skips it.
+
+Load `canon:video-craft` for every zoom and caption value the draft names, and report it rather than proceeding silently when it does not resolve.
+
+## Step 5: output
+
+Print the file path on its own line and a one-line summary. Do not paraphrase the path into prose.
+
+```markdown
+📝 Wrote demos/<slug>/beats.md
+
+Draft has 5 beats and pre-seeded defaults. Edit the beats, the resolved decisions, and the wrap.
+
+To record it rather than shoot it by hand:
+record-screencast demos/<slug>/beats.md
+```
+
+Name the skill and stop there. Do not compile the draft, do not run it, and do not generate captions. The operator edits the beats first, and the compiler reports which selectors and URLs they still owe it.
+
+Say so plainly if `canon demo compile` is not available, rather than driving the application some other way. The command ships with the CLI and the skills ship with the plugin, so a project carrying one and not the other is a real state.

package/claude/skills/{draft-screencast → script-screencast}/references/beats-template.md

@@ -1,11 +1,11 @@
 ---
 title: Beats template
-description: The nine-section template draft-screencast writes to demos/<slug>/beats.md, pre-seeded so the draft ships as-is
+description: The nine-section template script-screencast writes to demos/<slug>/beats.md, pre-seeded so the draft ships as-is
 ---
 
 # Beats template
 
-Applies to the draft `draft-screencast` Step 4 writes. Fill every placeholder from the project context and the discovery answers. The template states no zoom or caption value, since each traces to a source `canon:video-craft` records.
+Applies to the draft `script-screencast` Step 4 writes. Fill every placeholder from the project context and the discovery answers. The template states no zoom or caption value, since each traces to a source `canon:video-craft` records.
 
 ## Template
 

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: search-craft
-description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is the `claude-code-guide` agent, or to generate an image, which is not search.
+description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is a direct fetch of Anthropic's docs index, or to generate an image, which is not search.
 metadata:
   family: build
 ---
@@ -87,6 +87,6 @@ These flags fire after the search has run.
 ## What this delegates
 
 - The form a citation takes: the surface writing it, such as the standard the procedure writes to
-- A Claude Code subject: the `claude-code-guide` agent, which `draft-doc`'s wiki sourcing step routes to
+- A Claude Code subject: a direct fetch of `https://code.claude.com/docs/llms.txt` and the `.md` page it names, as `write-doc`'s wiki sourcing step does
 - Generating an image: whatever draws the surface, since making one is not search
 - Access code a session needs repeatedly: a `canon` verb, never a script in this skill

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

@@ -183,6 +183,7 @@ After the chain, report as well:
 - Any domains or scripts that failed
 - Any detection gaps surfaced during resolve
 - Claude Code plugins as an onboarding step this chain does not cover, so a clean result does not read as onboarding complete
+- `/canon:write-doc README.md` when the root `README.md` is missing or carries no H1 naming the project, and nothing when it is authored
 
 A resolved name and a fallback read alike once written, so the preview marks the
 fallback rather than this report. The preview is the last point before the first

package/claude/skills/task-board/SKILL.md

@@ -67,10 +67,12 @@ Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file f
 
 A task file with no row is a dropped task, so name its surface in the same pass that creates it. The test and both file shapes are in `${CLAUDE_SKILL_DIR}/references/board.md`.
 
-| Task                                        | Surface                                                                                                                         |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Plausibly planned within the next few waves | A row under `## Needs a plan` in `.canon/tasks/priority.md`, positioned against the rows there, with the reason in `Waiting on` |
-| Anything else                               | A line in `.canon/tasks/backlog.md`, which is unordered                                                                         |
+| Task                                        | Surface                                                                                                                                   |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Plausibly planned within the next few waves | A row under `## Needs a plan` in `.canon/tasks/priority.md`, through `canon tasks place <stem> --group needs-a-plan --waiting "<reason>"` |
+| Anything else                               | A line in `.canon/tasks/backlog.md`, which is unordered                                                                                   |
+
+Position the row against its siblings with `--before <stem>` or `--after <stem>`, and state what it ranks against in the reason.
 
 ### Check for a live orchestrator
 
@@ -80,11 +82,11 @@ Check the roster before writing either file. Read `canon sessions list --self --
 - Its `name` starts with `orchestrator-`, the convention every hand-launched controller here uses, which excludes every `worker-` and `planner-` session
 - Treat a refusal from either call the same as a roster read that failed
 
-| Roster read                                                                | Act                                                                                                          |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| **Found**                                                                  | Write neither file. Report the surface and reason, and message that session so it places the row itself      |
-| **Not found**, and this session's name starts with `worker-` or `planner-` | Write neither file, since both role bodies ban a board write. Report the row and its surface.                |
-| **Not found otherwise**, or the read fails                                 | Write the row directly, through the same heredoc route as the file. A failed read looks like a solo project. |
+| Roster read                                                                | Act                                                                                                     |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **Found**                                                                  | Write neither file. Report the surface and reason, and message that session so it places the row itself |
+| **Not found**, and this session's name starts with `worker-` or `planner-` | Write neither file, since both role bodies ban a board write. Report the row and its surface.           |
+| **Not found otherwise**, or the read fails                                 | Place the row through `canon tasks place`. A failed read looks like a solo project.                     |
 
 Say which branch fired and why in the report. A placement with no stated reason is one the next sweep re-derives from nothing.
 

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

@@ -70,28 +70,31 @@ Group tasks by readiness rather than by status, one row per task, under the colu
 
 Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. A task belongs to exactly one, and the tests are read in order.
 
-| Group             | Test                                                                                   |
-| ----------------- | -------------------------------------------------------------------------------------- |
-| `## Run now`      | A written plan covers every open outcome, and nothing stated keeps the task from start |
-| `## Up next`      | A written plan exists, and the `Waiting on` column names why the task cannot start     |
-| `## Needs a plan` | Everything else. No plan, or a plan that no longer describes the work                  |
+| Group             | Test                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `## Run now`      | A worker was dispatched on it, under a written plan covering every open outcome      |
+| `## Up next`      | A written plan exists and no worker holds it yet, and `Waiting on` names what is due |
+| `## Needs a plan` | Everything else. No plan, or a plan that no longer describes the work                |
 
 The names are the contract. A board grouped by readiness under names of its own reads as empty to anything counting rows under a heading, so add no fourth group.
 
+### Writing the board
+
+Every write goes through `canon tasks place`, `promote`, `move`, or `block`, each reading the file once, rendering the columns the template fixes, and writing it once. `plan-link` promotes a parked row the same way. Only `Waiting on` is typed, since every other cell derives from the task and its live plans.
+
 ### What blocks a run
 
 A collision with running work blocks a task only where no merge settles it, being a contract, a relocation, or a sweep. A shared file alone is none, since the branch merging second rebases.
 
-- A worker is handed a task from `## Run now` alone, and its `Touches` column states the set to read
-- Each group's columns follow from its test. Neither half of the `## Run now` test is checkable without the file set and the plan beside the task.
+- A dispatcher picks from `## Up next` and runs `canon tasks promote` once the launch succeeds
+- Each group's columns follow from its test. Neither half of the `## Up next` test is checkable without the file set and the plan beside the task.
 
 ### The `Touches` cell
 
-A `Touches` cell is copied from its plan's list, so it states what the branch sets out to write rather than a bound on it. A branch outgrows it while the row still reads as it did at dispatch.
+A `Touches` cell is the first three paths of its plan's `**Files to touch:**` and a count of the rest, the union in line order for a sliced task. It states what the branch sets out to write, and a running branch outgrows it.
 
-- Once a branch runs, correct the cell from the diff rather than the plan, which is the prediction that already went stale
-- `canon tasks plan-reach <plan>` reads that diff against every live plan and every cell in the group
-- The row's owner writes the correction. A worker never edits this board.
+- `canon tasks plan-reach <plan>` reads the current reach off the branch's diff
+- Change the plan's list to change the cell. A worker never edits this board.
 
 ### Cell width
 
@@ -118,7 +121,7 @@ The `Waiting on` column under `## Up next` carries the reason in one of three fo
 | Sibling task       | That task                                                                     |
 | External condition | The condition and what would satisfy it                                       |
 
-Naming what would satisfy a condition separates a blocked row from one nobody examined, so a condition with no way out fails the test. The header text is the contract, since a reader resolves the column by header rather than position.
+Naming what would satisfy a condition separates a blocked row from one nobody examined, so a condition with no way out fails the test. The header text is the contract, since a reader resolves the column by header rather than position. A cell renders at most 120 characters, a link counting as its label alone, and the verbs refuse a longer one.
 
 ### The needs-a-plan cell
 

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

@@ -183,7 +183,7 @@ Read `${CLAUDE_SKILL_DIR}/references/promotion-fold.md` for how each block lands
 Lesson:    .canon/teach/<nn>-<topic>/lessons/<nnnn>-<slug>.html
 Reference: .canon/teach/<nn>-<topic>/reference/<slug>.md
 Record:    .canon/teach/<nn>-<topic>/learning-records/<nnnn>-<slug>.md
-Figure:    <drawn through draft-figure, or the one-line reason prose carries it>
+Figure:    <drawn through draw-figure, or the one-line reason prose carries it>
 Progress:  <n> of <m> success lines met
 Open:      [<the url the serve verb reported>](<the same url>)
 ```