@erclx/canon 5.52.0 → 5.54.0

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

@@ -1,34 +0,0 @@
----
-name: teach-workspace
-description: Scope boundary for learning a subject across sessions, and the split between the disposable lesson and the durable reference page
----
-
-# Teach workspace requirement
-
-## Gap
-
-Without this skill, a session asked to teach answers in the conversation, so everything dies with it. It teaches from recall, picks topics from the subject's order rather than the learner's errors, and asks nothing about what they know. A structure lesson points at a diagram and ships none.
-
-A worked-through page and a looked-up page have different lifetimes, and merging them yields disposable material kept or durable material carrying a quiz. Opened by bare path, a lesson renders unstyled. A workspace resolved against the current directory forks per worktree, and the editing tools refuse a main-root write from one.
-
-## Must
-
-- Hold the workspace at the main worktree root, name the write route from a linked worktree, and route edits to an existing workspace file through a verb that resolves the root
-- Ask the learner's starting point, research from sources chosen by the teach standard's ladder, and place each lesson from the learning records
-- Split the output by lifetime into lessons and reference pages, record the wrong answer itself rather than a count, and decide each lesson's figure before its body
-- Hand the learner a link to the workspace in a real browser on every run, read back from the verb that served it
-- Propose each durable page's destination by who owns its subject, wait for the operator, and hand the page off through a named file a branch lands and deletes
-
-## Must not
-
-- Teach from recall without saying which claims rest on it
-- Write to a destination surface outside the fold mode, or overwrite a file a promotion block routes to
-- Promote a lesson at any age, since it is generated markup carrying a quiz
-- Open a second workspace on a covered subject, or renumber anything
-- Scaffold a wiki folder the project never chose
-
-## Out of scope
-
-- What the verbs do internally, which the `canon teach` CLI domain owns
-- What a lesson renders as and how its quiz behaves, which the lesson-craft reference and the rendering layer own
-- Firing on a description match, since opening a workspace is the learner's call

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

@@ -1,196 +0,0 @@
----
-name: teach-workspace
-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, proposes where a durable page from one belongs once it outgrows the workspace, and lands the confirmed pages from a branch. 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", "promote this reference page", or "fold the promoted pages in". 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. Do NOT auto-trigger.
-argument-hint: <subject to learn, the topic of a workspace to resume or promote, or fold>
-metadata:
-  family: answer
----
-
-# Teach workspace
-
-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.
-
-## References
-
-Read `${CLAUDE_SKILL_DIR}/references/teach.md` before writing anything into the folder, since it fixes the workspace's shape. The glossary answers to `${CLAUDE_SKILL_DIR}/references/glossary.md` wherever it lands.
-
-The pedagogy sits in `${CLAUDE_SKILL_DIR}/references/pedagogy.md`, the lesson craft and its build in `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` and `lesson-build.md`, the revisit schedule in `revisit.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 and the destinations the fold mode lands from that file
-- A durable page stays in `reference/` until the operator confirms a destination, and only the fold mode copies it out, from a branch
-
-### Workspaces and promotion
-
-One subject takes one workspace, and only its reference pages ever leave it.
-
-- 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.
-- Never write a favicon link by hand. `canon teach nav` puts the toolkit's icon on every page and in a lesson's `style` region, so a hand-written one gives the page two.
-
-## 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:
-
-```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 Step 1's new-workspace path, and the open verb creates the folder.
-
-Every path under the main root is a main-root write, routed the way `session-worktree` states. 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 a heredoc
-- Changing a line inside a file that already exists goes through the verb that owns it
-
-## Step 1: open or resume
-
-A topic the listing already carries is a resume, and anything else is a new workspace. Two invocations are neither.
-
-- One asking to promote reads the named workspace through the listing and goes to Step 6, which teaches nothing and writes no lesson
-- One asking to fold confirmed promotions in goes to `## Fold mode`
-
-### 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`, which carry where the learner stopped and what they got wrong.
-
-- The record's `success` holds the mission's success lines, the exit criteria. Report them with what is already met before teaching anything.
-- `due` lists what the learning records schedule, soonest first, each with its item, date, rung, `overdue` flag, and the two dates the next record could write
-- Read `due` here, since `canon teach lesson` takes a `--slug` naming a choice already made. Report what is overdue before proposing a lesson.
-- An empty `due` on a workspace holding records means no record scheduled anything, which is a gap in the records rather than a clear schedule
-
-### 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, chosen by the standard's `### Choosing sources` ladder, with a third-rung source's reason in its title. 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 listed URL is refused, but `--read` moves an opened lead.
-
-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 on what `due` reports as overdue, oldest date first, before anything new
-- Where nothing is overdue, open on retrieval of what the last session got wrong. A learner who cannot retrieve the previous lesson is not ready for the next one.
-- Never place from the last record alone, since a topic missed three sessions ago is invisible to that read and sits in `due` with a date already past
-
-## 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, a teach-back block, and feedback per question, embedding one shared stylesheet. It is disposable and never promoted.
-- A reference page goes to `reference/<slug>.md`, written for a reader with no learner in it. It is the half that survives, so it passes the authoring gates a promotion applies.
-- A lesson's `refs` pass the source ladder, and a learner's or organization's file goes in the body, labeled
-- `canon teach nav` renders a reference to a `reference/<slug>.html` sibling, and a lesson links that sibling, since a served `.md` opens as plain text
-
-### Resolve the lesson
-
-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 three things:
-
-- `lesson`, the numbered path the lesson takes. Write it 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, as authored indices where `0` is the correct one. Take the order as given, since a lesson that reorders by judgment puts the answer back in the first slot.
-
-### The quiz, the teach-back block, and the lesson body
-
-Read `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` before writing the lesson. Its `## Quiz construction` and `## Teach back` fix the markup `canon teach nav`'s stepper gates on, and a quiz in any other shape shows every question at once with nothing reporting it.
-
-- Then read `${CLAUDE_SKILL_DIR}/references/lesson-build.md` for the block list, the four marker pairs, the render, nav, stylesheet, and glossary verbs, and the rule against hand-composing any of them
-- Keep every quiz answer the same length, so formatting leaks no clue about which one is correct
-- Decide the figure first, by `## Diagrams` in `lesson-craft.md`
-
-### Hand over a link, never a path
-
-A lesson is a page carrying a script, and an editor preview cannot run it, so a path alone opens markup with no working quiz. Serve the teach root and give the learner a link. One verb refreshes every page's chrome and serves the folder from the main worktree root:
-
-```bash
-canon teach up <topic> --json
-```
-
-- Where the installed CLI predates `up`, run the line the `Open` step of `canon teach list <topic>` prints, with `--json` appended
-- Never hand-write `canon serve .canon/teach`, which serves an absent folder from a linked worktree
-- Start it in the background and read `url` off the record, since the verb walks past a port already in use and a guessed URL gets that port 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
-- Do this on every run that opens or resumes a workspace, including one that writes no lesson, since the learner's route in 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 a `## Revisit` section.
-
-- 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.
-- Record what the teach-back left out under what the learner got wrong, naming the concept and where the explanation broke, since both are retrieval failures one section holds
-- Read `${CLAUDE_SKILL_DIR}/references/revisit.md` before writing `## Revisit`, for the bullet shape, where each date and rung comes from, and an unscheduled item's first schedule
-
-### Restate the mission
-
-Restate the mission's success lines from the `success` the lesson verb 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 its reference pages then 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, the wiki folder and its refusal, each destination's expectations, and under `## Proposing and handing off` the proposal, the handoff file, and the fold instruction. Propose and wait, and write nothing to a destination here.
-
-## Fold mode
-
-Run this only when the invocation asks to fold, and only from a branch in a linked worktree, since every destination is a tracked file committing with the branch while the handoff sits in gitignored scratch at the main root.
-
-Read `${CLAUDE_SKILL_DIR}/references/promotion-fold.md` for how each block lands, the overwrite refusal, the handoff delete, and the output lines, which replace the Output block below.
-
-## Output
-
-```plaintext
-✅ <opened|resumed> .canon/teach/<nn>-<topic>/
-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 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>)
-```
-
-- Omit the reference line where the lesson produced no durable page
-- Never omit the open line, the learner's only route into the page. It carries what the serving verb reported, or names the refusal where the verb refused.
-- Write that line as a markdown link with the URL as both text and target, never a bare URL or a code span the reader has to copy
-- Emit every path from the project root, in the form the project's instruction file sets
-
-A promotion pass reports the shape `${CLAUDE_SKILL_DIR}/references/promotion.md` gives at the end of `## Proposing and handing off` instead.

package/claude/skills/teach-workspace/references/glossary.md

@@ -1,90 +0,0 @@
----
-title: Glossary reference
-description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
----
-
-# Glossary reference
-
-Applies to a glossary, the file holding one entry per term a body of material defines. It changes whenever the material names a concept a reader cannot look up yet, and it is revised in place rather than appended to.
-
-## Scope
-
-Governs a glossary at `.canon/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
-
-Does not govern:
-
-- The folder a learning workspace lays out around its glossary, and the other files in it: `teach.md`
-- Which surface a glossary moves to once it leaves the material that produced it, which belongs to the surface driving that move
-- Voice, rhythm, and sentence construction: the `write-human` skill
-- Headings, punctuation, word choice, and file references: `markdown.md`
-
-## What a working glossary looks like
-
-A glossary works when a reader who meets a term in the material settles it here without opening the page that introduced it:
-
-- Which word does this material use for the concept, and which words does it deliberately not use?
-- What does the term mean, stated without leaning on the term itself?
-- Where does the term appear, so a reader can see it used rather than only defined?
-- Does every entry carry a term the material actually uses?
-
-A glossary failing these is non-conforming even when it satisfies every shape rule below.
-
-## Frontmatter
-
-- `title` (required): names the material the terms come from, in sentence case
-- `description` (required): one line naming what a reader gets from the entries
-
-## Entries
-
-- Write one entry per term, as a single bullet.
-- Lead the bullet with the term as a bolded span, then the definition in one or two sentences.
-- Define the term without using it. A definition that spends the term explains nothing to the reader who arrived not knowing it.
-
-### Placement and order
-
-Each entry points at its first use and sits where a reader would look for it.
-
-- Name where the term first appears, so a reader can reach one use of it in context.
-- Keep an entry to the meaning. Worked detail belongs on the page that teaches the term.
-- Sort entries alphabetically, so a reader who knows only the word finds it without reading the file.
-
-## Which terms it carries
-
-- Add a term once the material has used it, never ahead of that. A glossary front-loaded with terms nothing has introduced is a syllabus rather than a reference.
-- Pick one word per concept and use that word everywhere. A glossary carrying two words for one thing hands the reader a choice it exists to remove.
-- List each rejected synonym as an alias to avoid inside the entry that won, so a reader arriving with the wrong word lands on the right one.
-- Use the glossary's own terms inside other definitions. A definition reaching for a synonym of a term defined two entries down teaches the reader a word the material does not use.
-- Revise an entry the material has moved under rather than adding a second one narrating the change.
-
-## Grouping
-
-- Keep a short glossary as one alphabetical list under the title. Grouping a handful of entries costs a heading per category and saves no lookup.
-- Group a glossary long enough that one list stops helping under `##` headings by category, sorted alphabetically within each. Roughly two screens of entries is the signal.
-- Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
-- State a departure from any rule above in the file itself, naming what it departs from and why
-- A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name
-
-## Rendered grouping
-
-Applies to a rendered glossary page, never to the source file above, which stays the flat alphabetical list the `## Grouping` rules above govern.
-
-- Group a rendered glossary by the lesson its own "First seen in" citation names, ordered by lesson order, under a sub-heading naming the lesson's title rather than its filename.
-- Trail with an "Other terms" group holding any entry the citation cannot attribute to a lesson, whether it names a reference page or carries no citation
-- Keep "Other terms" in the alphabetical order the source file already carries
-- Keep the workspace-wide term filter matching against every group, and drop a group's own heading once filtering leaves nothing under it.
-
-## Template
-
-```markdown
----
-title: <Material the terms come from>
-description: <one line naming what a reader gets from these entries>
----
-
-# <Material the terms come from>
-
-<One line on which material these terms come from and when the file changes.>
-
-- **<Term>**: <the meaning in one or two sentences, written without using the term>. Avoid <rejected synonym>. First appears in `<page or lesson>`.
-- **<Term>**: <the meaning in one or two sentences, written without using the term>. First appears in `<page or lesson>`.
-```

package/claude/skills/teach-workspace/references/lesson-build.md

@@ -1,106 +0,0 @@
----
-title: Lesson build reference
-description: The block list canon teach render takes and the verbs that build the lesson body, being render, nav, stylesheet, and glossary
----
-
-# Lesson build reference
-
-Mechanics rather than judgment. `lesson-craft.md` covers what a lesson should be, and this file covers how its body reaches the page through the verbs.
-
-## The block list
-
-`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Six types, and every structural body composes from them:
-
-- `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
-- `{"type":"paragraph","text":"<text>","lede":true,"cites":[1]}`: a `<p>`, marked `lede` for the opening dek. `cites` adds a footnote marker per reference number, and a lede takes none.
-- `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
-
-### Reference, code, and raw blocks
-
-The other three carry sources, code, and markup the components cannot.
-
-- `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the one reference list, numbered from 1. `url` and `note` are optional, and a `url` must be http or https.
-- `{"type":"code","lang":"ts","text":"<source>"}`: a sample highlighted at render time with no script. `lang` is optional and takes a highlight.js name or alias, and an unregistered one renders plain.
-- `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
-
-### Where code and raw go
-
-Code never travels through `raw`. A hand-written `<pre><code>` renders with no color, and `nav` never highlights markup already in a body, so it stays plain for good. A fenced block in a reference page's markdown is highlighted by `nav` on its own.
-
-The quiz and teach-back block in `lesson-craft.md` always need `raw`, since their fixed contract is not a components concern. Give them the array's last `raw` entry, followed only by `refs`, and use `raw` nowhere the other types could carry the content.
-
-### Citing
-
-A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than the sentence.
-
-- Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened
-- Render refuses a cite no reference resolves, so number the list before citing into it
-
-## Building the lesson body
-
-Step 4 of `teach-workspace` reads this section before writing a lesson, after the lesson verb has resolved its path and quiz order. Write the chrome as four empty marker pairs rather than composing it by hand.
-
-- `<!-- canon:teach:style -->` and `<!-- /canon:teach:style -->` inside `<head>`
-- `<!-- canon:teach:header -->`, `<!-- canon:teach:footnav -->`, and `<!-- canon:teach:scripts -->`, each with its own close marker, in that order in `<body>`
-
-### Render the body
-
-Build the authored `<h1>`, lede, body, and quiz as a JSON array of blocks, and render it through the verb rather than a component import:
-
-```bash
-echo '[
-  {"type":"heading","level":1,"text":"<title>"},
-  {"type":"paragraph","lede":true,"text":"<the dek>"},
-  {"type":"paragraph","text":"<a body paragraph>"},
-  {"type":"paragraph","text":"<a claim resting on a source>","cites":[1]},
-  {"type":"list","ordered":true,"items":["<step one>","<step two>"]},
-  {"type":"raw","html":"<the quiz and teach-back block composed per lesson-craft.md>"},
-  {"type":"refs","items":[{"title":"<source name>","url":"<https URL>"}]}
-]' | canon teach render --json
-```
-
-`## The block list` above states each type and where `raw` belongs. Write the call's `html` field between the header's close marker and the footnav's open marker, and nothing else anywhere in the file.
-
-### When a verb does not resolve
-
-Every verb in this section can be missing from an installed CLI that predates it. Report that rather than proceeding silently, and never hand-compose the body, the chrome, or a palette as a fallback.
-
-A hand-composed body is the state this section exists to end. A target holds this skill body before the verb, since a plugin skill reaches a target on merge while the CLI arrives only when a release publishes.
-
-### Fill the chrome
-
-Then run:
-
-```bash
-canon teach nav <topic> --json
-```
-
-It fills every marker pair from what the workspace holds on disk, and rewrites the workspace's contents page and the teach-root listing in the same run.
-
-- The markers take the embedded stylesheet, the header with its breadcrumb and jump menus, the prev and next footer nav, and the behavior scripts
-- It refuses a lesson missing a marker pair by name rather than guessing the boundary, so a dropped marker is caught here rather than read back as a lesson nothing links to
-
-### Seed the stylesheet
-
-On the first lesson in a workspace, seed the stylesheet through the verb rather than authoring a palette:
-
-```bash
-canon teach stylesheet <topic> --json
-```
-
-It writes the design tokens as custom properties and the components built on them, from the one source every rendered surface reads.
-
-- Add lesson rules under the seed, and reach a value through its property rather than restating the hex, which is how each workspace forked the palette
-- It refuses to overwrite, so a rerun on a workspace with its own rules is safe and reports `written` as false
-
-### Add glossary terms
-
-Add every term the lesson defines to `GLOSSARY.md` through the verb, which places 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 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.

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

@@ -1,135 +0,0 @@
----
-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. The block list and the verbs that build the lesson body sit in `lesson-build.md`.
-
-## Contents
-
-- [One course, not a pile of pages](#one-course-not-a-pile-of-pages)
-- [Typography](#typography)
-- [Restraint](#restraint)
-- [Diagrams](#diagrams)
-- [Quiz construction](#quiz-construction)
-- [Teach back](#teach-back)
-- [Tokens travel with the course](#tokens-travel-with-the-course)
-- [What makes a lesson worth returning to](#what-makes-a-lesson-worth-returning-to)
-
-## 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.
-
-- `canon teach nav` embeds and re-embeds the shared stylesheet into every lesson on each run, so growing that stylesheet, by promoting anything used a second time into it, is the only step left by hand.
-- 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.
-- Refer to another lesson in the workspace as "lesson" plus its four-digit number, such as "lesson 0003". `canon teach nav` links the mention and reports a number naming no lesson.
-- Never hand-write a link to another lesson, the one form nav never checks
-
-## 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
-
-## Diagrams
-
-Decide the figure once per lesson, before writing the body.
-
-1. Name the one relationship, boundary, path, or before-and-after the lesson is about. A lesson about none ends here, with `Figure: none, <why it names no structure>` on the reply.
-2. Hold it against the bar in `${CLAUDE_SKILL_DIR}/../draw-figure/references/figures.md`, which also carries the drawing rules.
-3. Draw it through `canon:draw-figure` into a `raw` block before the quiz, never inside it or after its feedback, which breaks the stepper's gating. Report an unresolved skill rather than drawing.
-4. Or write one line on why prose carries it better, such as a structure an earlier lesson gave.
-
-A structure lesson takes step 3 or 4, never neither. Put the outcome on the reply's `Figure:` line, off the lesson page. Never draw to satisfy the step, or on every section (`## Restraint`).
-
-## 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. An author varying position by hand varies it by judgment, which settles on the first slot.
-- Make each wrong option a misconception someone actually holds. An obviously wrong option removes itself and shrinks the question.
-- Write one feedback block per question, covering the correct option and why each distractor fails, saying why rather than whether
-- Give feedback after the attempt, never alongside the question
-
-One feedback block reads as an explanation where a block per option reads as four verdicts, and only the explanation names what separates a wrong option from the answer.
-
-### The markup
-
-The quiz shape is a contract rather than a convention. `canon teach nav` splices a stepper into the lesson that gates on exactly these class names and this nesting, so a quiz written in any other shape renders with every question on screen at once and nothing reports it.
-
-```html
-<div class="quiz">
-<h2>Retrieval check</h2>
-
-<div class="q"><p class="q-stem">1. <stem></p>
-<label class="opt" data-k="A"><input type="radio" name="q1"><span><the option text></span></label>
-<label class="opt" data-k="B"><input type="radio" name="q1" data-a="1"><span><the option text></span></label>
-<div class="fb"><b>Correct: <the answer in a few words>.</b> <why each distractor fails.></div></div>
-</div>
-```
-
-- Give every option in one question the same `name`, and a different `name` per question. Options sharing a name across two questions let one answer clear another.
-- Mark the correct option with `data-a="1"` and leave the others without the attribute
-- Carry `data-k` on the `label`, since the workspace stylesheet renders the key letter from it
-
-### Structure and the legacy button
-
-The nesting matters as much as the class names.
-
-- Keep `.fb` the last child of its `.q`. The stepper reveals it as a direct child, and a feedback block nested deeper stays hidden.
-- Put the option text in a `<span>` inside the label rather than bare beside the input, so the workspace can lay the two out
-- Never write a `<button class="opt">` in a new lesson. That is the shape written before the stepper, and it is kept working by an injected script the presence of a button is what still triggers.
-
-The stepper hides and shows and sets nothing else, so how a selected option looks, and whether a wrong one is marked as wrong, is the workspace stylesheet's to grow. Name the correct option in the feedback text for that reason: it is what a learner reads to find out whether they were right.
-
-## Teach back
-
-A quiz is recognition and a teach-back is production, which is the form retrieval practice prefers. Carry both: the quiz places the learner against options someone could hold, and the teach-back is where the learner finds out what they cannot say without help.
-
-- Ask for an explanation to a named audience rather than for an answer. Telling a non-programmer why a lazy quantifier is not an optional one has a floor, and "explain lazy quantifiers" has none.
-- Ask about the thing the lesson was for, not a detail beside it. A teach-back on a footnote tests attention rather than the material.
-- Carry a self-check as a closed `<details>` listing what a complete explanation covers. A learner with no session in the room otherwise cannot grade the ask, and closed leaks nothing.
-- Write the self-check as what the explanation has to cover rather than as the explanation itself. A model answer is read instead of produced, which turns the block back into reading.
-
-```html
-<div class="teach-back">
-<h2>Explain it back</h2>
-<p>Without looking above: <the ask, naming who it is for.></p>
-<details><summary>What a complete explanation covers</summary>
-<ul>
-<li><a point the explanation has to reach></li>
-</ul>
-</details>
-</div>
-```
-
-It needs no styles of its own beyond what the workspace already gives a section and a `<details>`.
-
-## 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/teach-workspace/references/promotion-fold.md

@@ -1,35 +0,0 @@
----
-title: Fold promoted pages
-description: How teach-workspace's fold mode lands each page a teach promotion handoff carries from a branch, deletes the handoff, and reports what it landed or left unfolded
----
-
-# Fold promoted pages
-
-The fold mode of `teach-workspace`, run from a branch in a worktree. The session reads this file when the invocation asks to fold confirmed promotions in.
-
-## Read the handoff
-
-Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root.
-
-- `teach-workspace` writes it, one H2 per destination naming the path, a source line under the heading, and the page body fenced below that
-- Read the body out of the fence rather than off the heading level, since a reference page carries headings of its own and only the fence separates them from the next destination
-- Stop when the file is absent, reporting `❌ No promotion handoff at .canon/tmp/handoff/teach-promotion/<slug>.md. Run the promotion step from the workspace first.`
-
-## Land each block
-
-Each block is a page an operator already confirmed a destination for, so this step lands it rather than judging it again. Write to the destination the heading names at `pwd` rather than the main root, since every destination is a tracked file that commits with the branch.
-
-- A wiki page and a public doc arrive as a whole file. Write it as the block gives it, and leave the block unfolded when the destination holds a file, since overwriting another's page is not a fold.
-- A context entry is merged into rather than created. Fold the body into the sections it belongs under, and never add an entry the catalog does not already carry.
-
-Then delete the handoff file so a later run does not fold it twice, and regenerate the index of any folder that carries one.
-
-## Output
-
-One line per page landed, one naming the handoff when one was consumed, and one per block left unfolded rather than dropped.
-
-```plaintext
-✅ Promoted: <destination path>
-🧹 Folded: .canon/tmp/handoff/teach-promotion/<slug>.md
-⚠ Skipped: <destination path> already exists. Merge by hand.
-```