@erclx/canon 4.0.0

package/claude/skills/claude-tasks/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: claude-tasks
+description: Creates a task file in `.claude/tasks/` with the filename, phase label, and frontmatter the standard requires, and archives a shipped one out of the folder. Use when asked to "add a task", "create a task", "queue this", "put this on the board", "archive that task", or "close out a shipped task". Do NOT use to mark an outcome `[x]` or to archive a plan. That is `claude-docs`.
+---
+
+# Claude tasks
+
+Owns the two operations that bring a task file into existence and take it out of the folder. `claude-docs` edits the contents of a task that already exists, marking outcomes `[x]` and sweeping the plans those tasks cite. Do not mark outcomes here and do not archive a plan on its own.
+
+Read `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` before writing any file. It holds the filename convention, the frontmatter contract, and the file format. Do not work them from memory.
+
+## Guards
+
+- Resolve the board at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo. Every read and write below resolves against that root. The board is gitignored scratch shared across worktrees, so a linked worktree writing to its own `pwd` creates a second board nothing else reads.
+- From a linked worktree the file-editing tools refuse that root, so a new task file goes out through `Bash` as a plain single command carrying a heredoc. Archiving already runs through `canon tasks archive`, which resolves the root in-process. Marking an outcome shipped is `claude-docs` and runs through `canon tasks outcome`. See Worktrees in `CLAUDE.md`.
+- If `.claude/tasks/` does not exist at that root, stop: `❌ No .claude/tasks/ board. Run canon claude init to set it up.`
+- Route on the request rather than on a flag. Creating names work that does not exist yet, archiving names a task file already on the board. If the request fits neither, stop: `❌ Ambiguous. Say whether to create a task or archive one.`
+- Never hand-edit `.claude/tasks/index.md`. A hook regenerates it from sibling frontmatter after a write. Do not run the regen command directly, except after a shell write from a linked worktree: the hook matches `Write|Edit|MultiEdit` and nothing fires on `Bash`, so that one case regenerates explicitly with `canon indexes regen --no-stage --root <main-root> <main-root>/.claude/tasks/index.md`.
+
+## Create
+
+### Step 1: require an origin
+
+Every task traces to a plan, a groundwork folder, an intake folder, or a GitHub issue. Ask for it when the request does not carry one, and stop rather than guessing: `❌ No origin. Name the plan, groundwork folder, intake folder, or issue this task comes from.`
+
+A task with no origin is either lost context or work nobody decided to do. This is the only moment the invariant is enforceable, because it is the only moment a task file comes into existence.
+
+Accept work whose origin is the conversation itself only when the user says so explicitly, and record what it was in the intro paragraph instead of writing a link line to a file that does not exist.
+
+### Step 2: propose the phase label
+
+List the existing filenames in `.claude/tasks/` and read `index.md` for what each holds. Propose the next label from what is already on the board, and say which neighbors it sits between.
+
+Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the board is the only surface that knows what a label currently means. Pad the phase to two digits in the filename, since index entries sort by filename alone and a bare `v9.0` sorts after `v15.0`.
+
+### Step 3: write the file
+
+Write `.claude/tasks/vXX.Y-<slug>.md` following the format in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
+
+Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.claude/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
+
+Never write a `Pull request:` line here. `git-pr` adds it when a pull request opens, and a number guessed at create time points at someone else's work.
+
+Write it immediately. Claude Code's tool permission dialog is the confirmation gate. Do not pause for approval.
+
+### Step 4: place it on a surface
+
+A task file with no row is a dropped task, so name the surface it lands on in the same pass that creates it. A task that would plausibly be planned within the next few waves takes a row under `## Needs a plan` in `.claude/tasks/priority.md`, positioned by where it sits against the rows already there, with the reason for that position in its `Waiting on` cell. Anything else takes a line in `.claude/tasks/backlog.md`, which is unordered and where in the file it goes means nothing.
+
+The test and both file shapes are in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. From a linked worktree the file-editing tools refuse the main root, so a row lands through the same `Bash` route the file itself took.
+
+Say which surface it went to and why in the report. The call is a judgment restated on every sweep rather than a property of the task, and a placement with no stated reason is one the next sweep re-derives from nothing.
+
+### Step 5: report unlinked origins
+
+Scan for work that has been decided and would otherwise be forgotten. Three origins carry it, and every run reads all three.
+
+List `.claude/groundwork/` and run `gh issue list --state open` when a remote is configured, then grep the board for each track name and issue number. Report any with no task, one line each.
+
+Read the dumps through `canon intake list --json`, which reports items, open, unread, and malformed per folder and owns the parse of the answer contract `${CLAUDE_SKILL_DIR}/../../standards/intake.md` fixes. Then grep both `.claude/tasks/` and `.claude/tasks/archive/` for each folder slug. A dump with no live task is the ordinary shape of one already promoted and shipped, so a check reading the board by itself reports every finished folder as abandoned.
+
+A dump is the stronger case for this scan rather than the weaker one. A track holds one question and stays visible, while a dump holds dozens of items whose verdicts were reached and then left with nothing carrying them forward.
+
+Those two reads give four states, and the first three earn a line each:
+
+- Every item answered, `malformed` at zero, and neither the board nor the archive cites the folder. Decided work nobody promoted, which is what this step exists to find.
+- Unread items. The folder is waiting on the operator rather than forgotten, so it takes its own wording and never lands in the block above.
+- `malformed` above zero. An item carrying no answer slot can be reached by no verb, so name the folder as a file to repair rather than as work in either state above.
+- The archive cites it. Promoted and shipped, so say nothing.
+
+`malformed` is why the first state tests two counts rather than one. A malformed item is neither unread nor answered, so reading `unread` alone folds it onto the answered side and reports a broken file as decided work nobody promoted.
+
+Say which read fired. "No task points at this" is true of every reported state and useful about none of them.
+
+Report rather than prompt. A track can be opened long after its task would have been written, so an offer to create one for each is noise on most runs, and that reasoning covers a dump unchanged.
+
+Say the origins were read even when nothing comes back, which is the ordinary result. A step going silent on a clean pass is indistinguishable from one that never ran.
+
+## Archive
+
+The `post-merge` git hook archives the task a merge closed, so a request arriving here is usually one the hook could not resolve on its own. Run the steps below against whatever the hook left in place.
+
+Do not move the file, edit `priority.md`, or regenerate the index by hand. `canon tasks archive` owns all three as one unit and the hook calls the same command, so a hand-rolled move here drifts from the unattended path.
+
+### Step 1: confirm the work reached main
+
+`claude-docs` marks outcomes on the branch as step 1 of the ship chain, so an all-`[x]` task routinely describes a pull request that is still open. The command gates on the outcomes and cannot tell those two apart, which is what puts this check here:
+
+```bash
+git fetch origin main --quiet && git log origin/main --oneline -20
+```
+
+Match the shipped outcomes against that log, widening to `gh pr list --state merged --limit 20` when a remote is configured and the log does not settle it. When the work is not on `main`, name the task and stop: `❌ Work not on main. Archiving now loses the task if the pull request is abandoned.`
+
+The board is gitignored, so an archived task has no history behind it and nothing restores one archived early. Skip this check when the task carries a `Pull request:` line and that pull request is merged, since the number already proves what the log is being read for.
+
+### Step 2: run the archive
+
+Pass the task's filename stem, or the pull request number when the request names one:
+
+```bash
+canon tasks archive <stem> --json
+```
+
+The command refuses rather than reports, and the refusal reaches this skill through the record rather than through the exit. Branch on `ok`, then on `reason`. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, which masks every non-zero exit rather than only an absent verb. The binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike, so the record is the only signal that survives the wrapper.
+
+On success the record carries `from`, `to`, `priorityRowRemoved`, and `indexRegenerated`, which is what moved, what row it cleared, and whether the index changed.
+
+### Step 3: route on a refusal
+
+Each reason has one resolution and none of them is to archive around it:
+
+- `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `claude-docs` when the work shipped and nothing marked it. Leave the task on the board when the outcome is real. Cut the outcomes first when the work is being abandoned, so the board records what was dropped.
+- `plan-unswept`: stop and route to `claude-docs`, which owns the plans sweep and the last-live-citation rule. `❌ Plan not yet swept. Run /claude-docs first, then archive.`
+- `ambiguous`: two tasks name one pull request, which is the misfile `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
+- `no-match`: the stem or number names nothing on the board. Check the name against the listed stems.
+- `bad-input`: the command line was wrong rather than the board. Read the message, fix the arguments, and run it again. Nothing on the board needs repair, which is what separates this from the two above.
+
+Do not move a plan from this skill. `claude-docs` owns that move. Two skills relocating the same file drift into relocating it differently.
+
+Leave `TASK-ARCHIVE.md` alone when it is present in the archive folder. It records the single-file era in the shape that era used, and splitting it would fabricate per-task files nobody wrote.
+
+### Step 4: clear prose naming the task
+
+The command drops the task's row from `.claude/tasks/priority.md` and leaves prose alone. Remove any sentence that still names the archived task or counts the rows that changed, since a stale count reads as board state.
+
+## Output
+
+Emit the full relative path from the project root for every file written or moved. A bare filename names a file the reader cannot open.
+
+Create:
+
+```plaintext
+✅ Created: .claude/tasks/vXX.Y-<slug>.md
+
+<label> sits between <neighbor> and <neighbor>.
+<board or backlog, and why it landed there>.
+
+**Origin with no task:**
+
+- `.claude/groundwork/<slug>/`: open, touched <date>
+- `.claude/intake/<slug>/`: every item answered, nothing promoted
+- #NNN: <issue title>
+
+**Waiting on you:**
+
+- `.claude/intake/<slug>/`: <n> of <n> items unread
+- `.claude/intake/<slug>/`: <n> items carry no answer slot, so no verb reaches them
+```
+
+Drop either block when it carries no rows. When both are empty, which is the ordinary result, replace them with one line naming what was read: `Read <n> tracks, <n> dumps, and <n> open issues. Nothing unlinked.`
+
+Archive, reporting the paths the command returned:
+
+```plaintext
+📦 Archived: .claude/tasks/archive/vXX.Y-<slug>.md
+
+<ordering and index disposition in one line>
+```
+
+A refusal reports the reason and the resolution Step 3 routes it to, on one line each.

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

@@ -0,0 +1,56 @@
+---
+name: claude-teach
+description: Scope boundary for learning a subject across sessions, and the split between the disposable lesson and the durable reference page
+---
+
+# Claude teach requirement
+
+## Gap
+
+Without this skill, a session asked to teach a subject answers in the conversation, so everything it produced dies with the session and the next one starts from nothing. It teaches from recall rather than from a source, so the learner is handed claims nothing was read for and cannot tell which ones. It picks the next topic from the subject's own order rather than from what the learner got wrong, so it teaches past a gap it never measured. It asks nothing about what the learner already knows, so difficulty has no floor and the session lands either below or far above them.
+
+It also produces one output where two are needed. A page written to be worked through once and a page written to be looked up later have different lifetimes and different readers, and merging them yields material that is disposable and gets kept, or durable and carries a quiz nobody can promote. Writing the durable half in a format the authoring gates do not read costs a conversion at the moment it matters most, which is the moment someone tries to promote it.
+
+A session that does record something records the wrong thing. It writes what was taught rather than what the learner retrieved, and a tally of errors carries none of the misconception a later session would work against.
+
+The lesson then reaches nobody. It is a page carrying a stylesheet and a script, and the only thing a session hands over is a file path, which an editor preview opens with neither. The learner reads unstyled markup and takes it for the lesson, or opens nothing at all, and either way the session reports the lesson as delivered. A path is also the wrong unit once a workspace holds several pages, since the learner wants the one they are on rather than the folder it sits in.
+
+The durable half then has nowhere to go. A reference page and a glossary carry no learner and are ordinary reference prose, so they belong wherever the project already keeps prose on that subject, and a workspace holding them is a gitignored folder one person reads. A session moving them by hand picks a destination from the reader's activity rather than from who owns the subject, drops a page into a corpus without the source line that corpus requires, and has nothing stopping it from carrying a lesson across.
+
+Two failures land specifically on where the folder sits. A workspace resolved against the current directory forks into a copy per linked worktree, so the learning records split and no session sees the whole history. A body naming only the destination path reports success and loses the write, because the file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead.
+
+## Must
+
+- Hold the workspace at the main worktree root, so one learner has one history rather than one per worktree
+- Name the write route for a main-root path from a linked worktree, since a body naming only the destination reports a success that did not happen
+- Route every edit inside a workspace file that already exists through a verb resolving the root in-process, since a heredoc reaches a whole-file create alone and the stream editors that would reach the rest are banned
+- Settle the learner's starting point by asking, so difficulty sits above a measured floor
+- Research the subject from sources before teaching it, and record what was read and what was found and not opened
+- Place each lesson from the learning records rather than from the subject's order, and open with retrieval on the last wrong answer
+- Split the output by lifetime, sending the worked-through half to lessons and the looked-up half to reference pages in the format the authoring gates read
+- Record the wrong answer itself rather than the count, since that is what the next session places the learner from
+- Report progress against the mission's success lines, so a mission can be called finished
+- Hand the learner a link that opens the workspace in a real browser on every run, reading it back from the verb that served it rather than composing one, since the port a preview lands on is not the port it asked for
+- Propose a destination for each durable page by who owns its subject, and wait for the operator rather than routing on the session's own reading
+- Hand each confirmed page off through a named file of its own, so one skill owns the durable writes and no other producer's unread work is discarded with it
+- Name what the destination expects that the page does not carry yet, since the workspace runs none of the gates the destination does
+
+## Must not
+
+- Teach from recall without saying which claims rest on it
+- Write to a destination surface directly, since the skill owning that file makes the edit and two skills writing one file at one step is what the handoff exists against
+- Open a second workspace on a subject an existing one already covers
+- Renumber a workspace folder, a lesson, or a learning record, since the number is cited by files already written
+- Promote a lesson, at any age and on any request, since it is generated markup carrying a quiz and a learner into a corpus every other page passed a gate to enter
+
+## Guards
+
+- No subject named and no existing workspace matching, stop rather than opening a workspace with nothing to learn
+- No wiki folder in the project and a page routing there, refuse and name the command that creates one rather than scaffolding a surface the project never chose
+
+## Out of scope
+
+- Landing a promoted page at its destination, which belongs to the skill that owns durable writes there, and creating a wiki folder a project never chose
+- What the verbs do internally, which is the CLI domain's own contract rather than this skill's, and the records backup that carries the folder off one disk
+- What a lesson renders as and how a quiz behaves once rendered, which the lesson-craft reference shapes and a rendering layer executes
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so opening a workspace is the learner's call rather than a description match.

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

@@ -0,0 +1,196 @@
+---
+name: claude-teach
+description: Opens and runs a learning workspace on one subject, holding a mission, resources, numbered lessons, reference pages, a glossary, and learning records that survive across sessions, and proposes where a durable page from one belongs once it outgrows the workspace. Use when asked to "teach me X", "open a learning workspace", "I want to learn X", "quiz me on this", "continue the lesson", "resume my workspace on X", or "promote this reference page". Do NOT use to write project documentation, which belongs to the surface owning that document, and do NOT use to answer one question, which is an ordinary reply.
+disable-model-invocation: true
+argument-hint: <subject to learn, or the topic of a workspace to resume or promote>
+---
+
+# Claude teach
+
+Run a learning workspace on one subject across sessions. The workspace holds what the learner has been through, so a session weeks later resumes from the folder rather than from the conversation.
+
+The shape of the workspace is fixed by `${CLAUDE_SKILL_DIR}/../../standards/teach.md`. Read it before writing anything into the folder. The glossary answers to `${CLAUDE_SKILL_DIR}/../../standards/glossary.md`, whose shape governs a glossary wherever it lands, since a promoted glossary keeps its shape at whatever path it reaches and no project folder covers all of them. The pedagogy sits in `${CLAUDE_SKILL_DIR}/references/pedagogy.md`, the lesson craft in `${CLAUDE_SKILL_DIR}/references/lesson-craft.md`, and the promotion routing in `${CLAUDE_SKILL_DIR}/references/promotion.md`.
+
+## Guards
+
+- If the invocation names no subject and no existing workspace matches, stop: `❌ No subject. Invoke with the subject to learn, or the topic of a workspace to resume.`
+- Never trust recall for what the subject says. Research first, cite what was read, and say what was not.
+- Write nothing outside the workspace folder, apart from the one handoff file Step 6 names. A durable page stays in `reference/` and is copied out by the skill that owns the destination, never by this one.
+- Do not open a second workspace on a subject one already covers. Resume that one.
+- Never promote a lesson. It is generated markup carrying a quiz and a learner, and no request makes it promotable.
+
+## Step 0: let the CLI resolve the workspace root
+
+Workspaces live at the main worktree root, never inside a linked worktree. A copy per worktree forks the learning records, and the learner is one person.
+
+Every `canon teach` verb resolves that root in-process, so no step below composes a path to a workspace file. Read the folder through the CLI rather than deriving its location:
+
+```bash
+canon teach list --json
+```
+
+It reports every workspace with its path, its counts, and the ordinal a new one would take. A `no-teach` refusal means the project has opened none yet, which is the new-workspace path in Step 1 rather than a reason to stop. The open verb creates the folder.
+
+From a linked worktree the file-editing tools refuse every path under the main root and offer a worktree copy instead, which is a second file no later session reads. Never take that redirect. The route splits by what the write does to the file:
+
+- Creating a whole file that does not exist yet, which is a lesson, a reference page, and a learning record, goes out as one plain shell command carrying a heredoc
+- Changing a line inside a file that already exists goes through the verb that owns it, since the stream editors are banned and no other shell route reaches it
+
+## Step 1: open or resume
+
+A topic the listing already carries is a resume, and anything else is a new workspace. An invocation asking to promote is neither: read the named workspace through the listing and go to Step 6, which teaches nothing and writes no lesson.
+
+On a resume, run `canon teach list <topic> --json` for the files behind each count, then read the highest-numbered learning record and `GLOSSARY.md`. Those carry where the learner stopped and what they got wrong. The listing record carries `success`, the mission's success lines, which are the exit criteria this workspace is finished against. Report them with what is already met before teaching anything.
+
+On a new workspace, settle the starting point first, by asking rather than by assuming. Difficulty with no floor under it teaches nobody, and the mission cannot be written without it.
+
+Then open the workspace, which derives the ordinal and writes all three required files:
+
+```bash
+canon teach open <topic> --json \
+  --subject "<one line stating the subject>" \
+  --starting-point "<what the learner already knows>" \
+  --success "<an observable thing the learner will be able to do>" \
+  --out-of-scope "<what this workspace does not cover>"
+```
+
+Repeat `--success` and `--out-of-scope` per line. The verb refuses a topic another workspace already covers, which is the guard against opening a second one on the same subject.
+
+## Step 2: research before teaching
+
+Read the subject from sources rather than from recall. Record what was read and what was only found through the verb that owns the file:
+
+```bash
+canon teach resource <topic> --json \
+  --read "<title, naming which claims rest on it>=<url>" \
+  --lead "<title>=<url>"
+```
+
+Each flag repeats, and the pair splits on the first `=` so a URL carrying one survives. A URL already listed is refused rather than repeated.
+
+A claim nothing was read for is the failure this step exists against. Where no source is reachable, say so in the lesson and mark what rests on recall.
+
+## Step 3: place the learner
+
+Pick the next lesson from the learning records rather than from the subject's own order. The target is the band immediately past what the learner can already do unaided, which `${CLAUDE_SKILL_DIR}/references/pedagogy.md` states in full.
+
+Open with retrieval on what the last session got wrong, before anything new. A learner who cannot retrieve the previous lesson is not ready for the next one, and moving on anyway buys fluency that decays.
+
+## Step 4: write the lesson and the reference
+
+Two outputs with two lifetimes, and the split decides the format.
+
+- A lesson is a self-contained page carrying its own quiz and the feedback for each answer. It links one shared stylesheet rather than restating styles, and it is disposable and never promoted.
+- A reference page goes to `reference/<slug>.md`, written for a reader with no learner in it. This is the half that survives the workspace, so it is written in markdown to pass the authoring gates a promotion would put it through.
+
+Resolve the lesson before writing it, rather than composing its name or its quiz order by hand:
+
+```bash
+canon teach lesson <topic> --json \
+  --slug <kebab slug for what this lesson covers> \
+  --questions <how many questions the quiz carries> \
+  --options <how many options each question carries>
+```
+
+It writes nothing and reports four things:
+
+- `lesson`, the numbered path the lesson takes. Write it there.
+- `stylesheet` with `stylesheetExists` and `stylesheetHref`. Write the stylesheet only when it reports absent, which is the first lesson in the workspace. Every lesson after that links the file already on disk and adds to it rather than replacing it, since overwriting discards what the last lesson put there.
+- `success`, the mission's success lines, carried here so Step 5 needs no second read.
+- `quiz`, one entry per question, carrying `order` and `answer`.
+
+Write the correct option first, then present the options in the order `order` reports, reading it as authored indices where `0` is the correct one. Take the order as given. Position drawn here rather than chosen is the whole reason the verb exists, and a lesson that reorders on its own judgment puts the answer back in the first slot.
+
+Add every term the lesson defines to `GLOSSARY.md` through the verb, which places the entries alphabetically in the shape the standard fixes:
+
+```bash
+canon teach glossary <topic> --json \
+  --term "<term>=<definition, written without using the term>" \
+  --first-seen <the lesson or reference page this batch comes from>
+```
+
+`--term` repeats and one call writes the file once, which is what keeps a batch of terms from racing on it. A term already defined is refused, since a definition the subject has moved under is a revision of the entry rather than a second one.
+
+Follow `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` for what makes a lesson worth returning to. Keep every quiz answer the same length, so formatting leaks no clue about which one is correct.
+
+### Hand over a link, never a path
+
+A lesson is a page carrying a stylesheet and a script, and an editor preview opens it with neither, so a path alone delivers unstyled markup that reads as the lesson. Serve the teach root and give the learner a link they can click:
+
+```bash
+canon serve .claude/teach --entry <nn>-<topic>/index.html --json
+```
+
+Start it in the background so the session keeps going, and read `url` off the record rather than composing one. The verb walks past a port already in use, so the port it took is exactly the half a guessed URL gets wrong. Report the refusal and its `reason` when `ok` is false, and report it rather than proceeding silently when the verb does not resolve at all, which is an installed CLI predating it.
+
+Do this on every run that opens or resumes a workspace, including one that writes no lesson, since the learner's route into what is already there is the same link.
+
+## Step 5: record what happened
+
+Write `learning-records/<nnnn>-<slug>.md` before the session ends, carrying the lessons covered, what the learner retrieved unaided, what they got wrong with the wrong answer itself, and what to revisit.
+
+Record the wrong answer rather than the count. The next session places the learner from this file, and a tally carries no misconception to work against.
+
+Then restate the mission's success lines with what is now met, reading them from the `success` the lesson verb already reported rather than from `MISSION.md` by eye. Report each line as met or not met, and name what the learner did that meets it. A mission whose lines are all met is finished, and saying so is what closes a workspace.
+
+## Step 6: propose where the durable half belongs
+
+Run this when the invocation asks for it, or offer it in one line when a mission finishes, since that is when the workspace stops growing and its reference pages stop changing. Never run it unasked mid-course.
+
+Read `${CLAUDE_SKILL_DIR}/references/promotion.md` first. It carries what may be promoted, the routing test, both spellings of the wiki folder, the refusal when a project has none, and what each destination expects a page to carry.
+
+Propose and wait. A promoted page is public prose that needs a line naming who owns its subject, which is a judgment about ownership rather than a move a session makes on its own reading. Present one block per candidate page:
+
+```plaintext
+reference/<slug>.md → <destination path>
+Subject owner: <who owns it, in a few words>
+Still owed:    <what the destination expects that the page does not carry yet>
+```
+
+Then stop and let the operator strike, redirect, or confirm each block.
+
+Write nothing to a destination here. One skill owns the durable writes, and two skills editing one file at one step is the failure that rule exists against. Record each confirmed block in `.claude/.tmp/teach-promotion/<slug>.md` at the main worktree root instead, appending when the file exists, with one H2 per destination naming its path, the source page beneath it, and the page body fenced:
+
+````markdown
+## <destination path>
+
+Source: .claude/teach/<nn>-<topic>/reference/<slug>.md
+
+```markdown
+<the page body as it should land, with the source line the destination expects>
+```
+````
+
+The body is fenced rather than written bare because a reference page carries headings of its own, and the reader splits this file on its H2 lines. An unfenced body turns every section heading in the page into a destination naming no path. Open the body fence with four backticks so a page carrying a fenced code block of its own still closes where it should, and widen both fences together if it carries a four-backtick fence.
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+The handoff is its own file rather than a shared one. The routed-facts file another skill writes is deleted by whichever pass folds it, so a second producer's unread work goes with it, and a sibling path costs the folding skill one more read and removes the interaction.
+
+An append is a whole-file operation, so send it as a plain single `Bash` command carrying a heredoc, per Step 0. Then tell the operator that `/claude-docs` folds the file in from a branch. The proposal costs nothing tracked and runs anywhere, while the page it describes is a tracked file, so the fold is a worktree operation and the workspace it came from is not.
+
+## Output
+
+```plaintext
+✅ <opened|resumed> .claude/teach/<nn>-<topic>/
+Lesson:    .claude/teach/<nn>-<topic>/lessons/<nnnn>-<slug>.html
+Reference: .claude/teach/<nn>-<topic>/reference/<slug>.md
+Record:    .claude/teach/<nn>-<topic>/learning-records/<nnnn>-<slug>.md
+Progress:  <n> of <m> success lines met
+Open:      [<the url the serve verb reported>](<the same url>)
+```
+
+Omit the reference line where the lesson produced no durable page. The open line is the one line that is never omitted, since it is the only route the learner has into the page, and it carries what `canon serve` reported rather than a URL composed here. Where the verb refused, that line names the refusal instead of a link.
+
+Write that line as a markdown link carrying the URL as both its text and its target, rather than as a bare URL and never inside backticks. A code span renders as text the reader has to select and copy, which is the one thing the line exists to save them, and the path rule the project states governs a file path rather than a URL.
+
+Emit every path from the project root, in the form the project's instruction file sets.
+
+A promotion pass reports its own shape instead, one line per page the operator confirmed and one naming the handoff:
+
+```plaintext
+➡️ Promoting: .claude/teach/<nn>-<topic>/reference/<slug>.md → <destination path>
+→ Confirmed pages wait at .claude/.tmp/teach-promotion/<slug>.md. Run /claude-docs from a branch to fold them in.
+```
+
+A pass where the operator confirmed nothing writes no handoff file and reports that alone.

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

@@ -0,0 +1,59 @@
+---
+title: Lesson craft reference
+description: Typography, restraint, quiz construction, and what makes a lesson worth returning to
+---
+
+# Lesson craft reference
+
+Judgment rather than shape. The workspace standard fixes where a lesson sits and what it is named, and this file covers what makes one worth opening twice.
+
+## One course, not a pile of pages
+
+A workspace accumulates lessons over weeks. The learner reads them as one body of material, so a lesson that invents its own look reads as someone else's work.
+
+- Write the shared stylesheet into the workspace assets on the first lesson, and link it from every lesson after
+- Promote anything used a second time into that stylesheet. A second use makes it a component of the course.
+- Add to that stylesheet rather than replacing it. The lesson writing it is rarely the lesson that needs it changed, and a rewrite drops what every earlier lesson links it for.
+- Keep the structural furniture identical across lessons: where the title sits, where the quiz sits, what a correct answer looks like
+- Do not restate styles inside a lesson. A local override is a decision the next lesson has to either copy or contradict.
+
+## Typography
+
+The learner is reading, so the reading surface is the product.
+
+- Set body text at a comfortable reading size with generous line height, and hold the measure to roughly 65 to 75 characters
+- Use one typeface for prose and one for code, and no others
+- Build hierarchy from size and weight rather than from color. Color that carries meaning fails for a reader who cannot see it.
+- Give code blocks room. Cramped code is the part of a lesson a learner skips.
+
+## Restraint
+
+Every element competes with the material for attention.
+
+- Cut any decoration that carries no information
+- Use at most one accent color, reserved for the thing the learner acts on
+- Do not animate anything the learner did not trigger
+- Prefer whitespace over rules and boxes to separate sections
+
+## Quiz construction
+
+The quiz is the retrieval, so a leak in its construction turns it into a reading test.
+
+- Write every option to the same length, in words and in characters. A longer option reads as the considered one.
+- Write the correct option first and let the ordering verb place it. Position is not the author's to pick: an author who varies it by hand still varies it by judgment, and the judgment settles on the first slot.
+- Make each wrong option a misconception someone actually holds. An obviously wrong option removes itself and shrinks the question.
+- Write feedback for every option, including the correct one, saying why rather than whether
+- Give feedback after the attempt, never alongside the question
+
+## Tokens travel with the course
+
+A lesson carries its own values in the shared stylesheet rather than reading a host project's. A workspace runs in any project and most carry no token record at all, so a lesson inheriting one is a lesson that renders unstyled wherever the record is absent, with nothing reporting it.
+
+Pick values the material needs rather than values the project happens to hold. Inheriting is worth offering as something a learner asks for once, and it is the wrong default in every project that cannot answer.
+
+## What makes a lesson worth returning to
+
+- The worked example is complete. A learner returning for the example finds the whole thing rather than a fragment they have to reconstruct.
+- The lesson states what it assumes. A returning reader can tell in one line whether they are in the right place.
+- The hard part is named as the hard part. Material that flattens everything to one difficulty gives a returning reader nothing to navigate by.
+- Nothing depends on the session it was written in. A lesson referring to what was discussed is unreadable a week later.

package/claude/skills/claude-teach/references/pedagogy.md

@@ -0,0 +1,67 @@
+---
+title: Pedagogy reference
+description: Fluency against storage strength, retrieval practice, spacing, interleaving, the zone of proximal development, and where difficulty helps
+---
+
+# Pedagogy reference
+
+The rules a lesson is built from. Read this before picking what to teach next, not while writing the markup.
+
+## Fluency is not storage strength
+
+A learner who follows an explanation smoothly has demonstrated that the explanation was clear. That is fluency, and it decays within days. Storage strength is whether the material can be retrieved later without the explanation present, and the two move independently.
+
+The practical consequence is that a lesson cannot report its own success. Only a later retrieval can, which is why the learning record exists and why every session opens by testing the last one rather than by reviewing it.
+
+- Treat a learner's confidence as evidence about the lesson, never about their retention
+- Never advance on the strength of a smooth session. Advance on a retrieval the learner passed unaided.
+
+## Retrieval practice
+
+Pulling an answer out of memory strengthens it far more than reading it again. Recognition is the weak form: a learner who picks the right option from four has done less work than one who produced the answer from nothing.
+
+- Ask before telling. Open with the question, then teach into the gap the attempt exposes.
+- Prefer a question the learner has to produce an answer to over one they select from
+- Let the learner fail an attempt before correcting it. A failed retrieval followed by the answer beats being told first.
+- Do not cue the answer in the question. A question restating the material tests reading rather than memory.
+
+## Spacing
+
+The same total time spread across days beats the same time in one sitting. Forgetting between sessions is the mechanism rather than the cost, because effortful retrieval is what strengthens the trace.
+
+- Revisit a topic after the learner has begun to forget it, not while it is still fresh
+- Widen the gap each time a topic is retrieved correctly, and shorten it after a miss
+- Name what to revisit and roughly when in the learning record, so the next session has a schedule rather than a guess
+
+## Interleaving
+
+Mixing related topics within a session beats finishing one before starting the next. Blocked practice inflates in-session performance and hurts what survives it, because the learner stops having to work out which approach a problem calls for.
+
+- Mix topics inside a session once the learner has a foothold in each
+- Keep problems in a mixed set close enough that telling them apart is the work
+- Do not interleave a topic the learner has never seen. Interleaving discriminates between things already known.
+
+## The zone of proximal development
+
+The productive band is what the learner cannot do alone and can do with support. Below it the session is review, and above it the support carries the whole task and nothing transfers.
+
+- Compute the band from the learning records rather than from the subject's own order
+- Target the first thing the last record shows the learner could not do unaided
+- Withdraw support as the learner succeeds, and restore it on a miss rather than repeating the lesson
+- Where the records show nothing, ask. A guessed starting point misses in both directions.
+
+## Where difficulty helps and where it hurts
+
+Difficulty is not uniformly good. It helps skill acquisition, where the learner is building a procedure they will execute, and it hurts knowledge acquisition, where the learner is taking on facts and structure they do not have yet.
+
+- Introduce new facts and structure in their clearest form, with worked examples and no invented obstacles
+- Add difficulty once the learner is practicing rather than acquiring: withhold the worked step, vary the surface of the problem, delay the feedback
+- Never confuse a hard explanation with a hard problem. A confusing explanation adds load that teaches nothing.
+
+## Sourcing
+
+Parametric recall is confident where it is wrong, and a learner cannot audit it. Every claim in a lesson traces to something read.
+
+- Read the subject from sources before teaching, and record each one with its link
+- Mark any claim resting on recall as resting on recall, in the lesson itself
+- List a source found and not opened as a lead, and never cite it

package/claude/skills/claude-teach/references/promotion.md

@@ -0,0 +1,54 @@
+# Promotion routing
+
+Which surface a durable page from a learning workspace belongs to, and what to do when the destination does not exist yet.
+
+## What may be promoted
+
+Only the durable half. A reference page under `reference/` and `GLOSSARY.md` carry no learner and are ordinary reference prose about a subject, so they sort under the routing test like anything else.
+
+A lesson is never promoted, at any age and on any request. It is generated markup written to be worked through once, it carries a quiz and a second person, and nothing downstream cites it. Promoting one puts ungated markup into a corpus every other page passed a gate to enter.
+
+A reference page that reads like a lesson is a lesson wearing the wrong extension. Where a page under `reference/` carries a quiz, a second person, or an instruction to the learner, say so and propose rewriting it in place before promotion rather than promoting it and repairing it at the destination.
+
+## The routing test
+
+Sort by who owns the subject, which is the test the wiki already runs. The reader's activity decided the workspace and decides nothing here.
+
+| The page's subject                                             | Destination                   |
+| -------------------------------------------------------------- | ----------------------------- |
+| Owned by someone outside the project, such as a tool or vendor | the project's wiki            |
+| How this project itself works, for the people who build it     | `.claude/context/<domain>.md` |
+| Written for someone consuming what this project ships          | the project's public docs     |
+
+A page a reader cannot sort by that question is a page whose subject has not been settled. Say which two destinations it sits between and let the operator choose, rather than picking the nearer one.
+
+Within the wiki, place the page by the same owner test that decides the folder: a vendor's own subject, another tool's subject, and a subject no single vendor owns each take the folder the project's wiki index names for them.
+
+## Where the wiki sits
+
+The folder has two spellings and a project carries whichever its scaffold wrote:
+
+- `.claude/wiki/`, which is where the scaffolding verb creates one
+- A folder named `wiki` at the project root, which is where a project scaffolded before the move keeps its pages
+
+Read which one exists rather than composing either. A project carrying both keeps its pages at the root, so propose the root spelling and say the other folder is there.
+
+A project carrying neither gets a refusal rather than a scaffold:
+
+`❌ No wiki folder. Run canon wiki init to create one, then promote again.`
+
+Creating the folder as a side effect of promoting one page hands the project a surface it never chose, and the refusal is one command from resolved.
+
+## What a promoted page owes its destination
+
+Each destination gates prose the workspace does not, so name what the page still needs rather than proposing a move that fails at the gate.
+
+- A wiki page closes its intro paragraph with a sentence naming who owns the subject, and links the canonical page when one exists. A page carrying no such sentence is not ready to move.
+- A context entry is internal narrative about one domain, so a page landing there merges into an existing entry rather than arriving as a new one.
+- A glossary keeps the shape `glossary.md` fixes wherever it lands, and a promoted one has to state any rule it departs from.
+
+## Anti-patterns
+
+- **The page promoted into a new context entry.** Entries are created deliberately, so a promotion proposing one is proposing a domain rather than moving a page.
+- **The glossary split across destinations.** Terms drawn from one subject move together or not at all, since an entry defining a term the other half uses strands both.
+- **The workspace emptied on promotion.** Promotion copies rather than moves. The workspace stays readable to the learner who built it, and the page's later life belongs to its destination.