@erclx/canon 4.48.1 → 4.50.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.48.1",
+  "version": "4.50.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -43,6 +43,8 @@ A topic the listing already carries is a resume, and anything else is a new work
 
 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.
 
+It also carries `due`, what the learning records schedule, soonest first. Each entry names the item, its date, the rung it has reached, whether it is `overdue`, and the two dates the next record could write. Read it here rather than later: it is the input to what this session opens on, and `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:
@@ -75,13 +77,15 @@ A claim nothing was read for is the failure this step exists against. Where no s
 
 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.
+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, and moving on anyway buys fluency that decays.
+
+Reading the last record alone is what the schedule replaces. A topic missed three sessions ago and never revisited is invisible to that read and sits in `due` with a date already past, which is the whole reason the field exists.
 
 ## 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 embeds one shared stylesheet rather than restating styles, and it is disposable and never promoted.
+- A lesson is a self-contained page carrying its own quiz, a teach-back block, and the feedback for each question. It embeds 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:
@@ -101,6 +105,14 @@ It writes nothing and reports three things:
 
 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.
 
+### The quiz and the teach-back block
+
+The quiz markup is a contract rather than a convention. `canon teach nav` splices a stepper into the lesson that gates on exactly the class names and nesting `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` states under `## Quiz construction`, so a quiz in any other shape shows every question at once and nothing reports it. That is the leak this shape closes: a later stem naming what an earlier question asked for answers it while both sit on screen.
+
+Write each option as a `<label class="opt" data-k="<letter>">` holding a radio `<input>` and a `<span>`, every option in one question sharing a `name` and each question taking a different one, the correct option carrying `data-a="1"`, and one `.fb` block as the last child of the `.q`. Never write a `<button class="opt">` in a new lesson. That is the shape written before the stepper, kept working by an injected script the button itself still triggers, and a lesson mixing the two gets both mechanisms.
+
+Then carry a teach-back block beside the quiz. A quiz is recognition and the pedagogy prefers production, so a lesson offering only a quiz tests the weak form. Ask for an explanation to a named audience, and carry a `<details>` listing what a complete explanation covers, closed by default, so a learner reading with no session in the room can grade themselves. The reference states both shapes in full.
+
 Write the chrome as four empty marker pairs rather than composing it by hand: `<!-- canon:teach:style -->`/`<!-- /canon:teach:style -->` inside `<head>`, and `<!-- canon:teach:header -->`, `<!-- canon:teach:footnav -->`, and `<!-- canon:teach:scripts -->` each with its own close marker, in that order in `<body>`. Write the authored `<h1>`, lede, body, and quiz between the header's close marker and the footnav's open marker, and nothing else anywhere in the file. Then run:
 
 ```bash
@@ -145,10 +157,26 @@ Do this on every run that opens or resumes a workspace, including one that write
 
 ## 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.
+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. A produced answer and a selected one are both retrieval failures the next session places from, so a second heading would split one input across two sections.
+
+Then write `## Revisit`, one bullet per item, in the shape `${CLAUDE_SKILL_DIR}/../../standards/teach.md` fixes:
+
+```markdown
+## Revisit
+
+- **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
+```
+
+Take both the date and the rung from the `due` entry Step 1 already read, copying `hit` for an item the learner retrieved unaided and `miss` for one they did not, with the rung stepped the same way. Do not compute a date from the ladder. A session told to widen a gap still picks the number by judgment, which is the reason the verb reports both dates at all.
+
+An item the records have never scheduled has no `due` entry to copy from. Open it at rung 1, dated the day after this session, which is the ladder's floor and the one number this body states. Every later date for it comes from the verb.
+
+An entry outside this shape schedules nothing and nothing reports that it was skipped, so write the shape exactly. A later record naming the same item supersedes an earlier entry, so revise a schedule by writing the new bullet rather than editing the record it was set in.
+
 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

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

@@ -49,9 +49,56 @@ The quiz is the retrieval, so a leak in its construction turns it into a reading
 - 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
+- Write one feedback block per question, covering the correct option and why each distractor fails, saying why rather than whether. One 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.
 - Give feedback after the attempt, never alongside the question
 
+### 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
+- 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. Asking the learner to explain to somebody who has never written a pattern why a lazy quantifier is not an optional one gives the explanation a floor, where asking them to explain lazy quantifiers gives it 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 the learner can open, as a `<details>` listing what a complete explanation covers, closed by default. A learner reading with no session in the room otherwise gets an ask they cannot grade, 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.

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

@@ -25,13 +25,23 @@ Pulling an answer out of memory strengthens it far more than reading it again. R
 - 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.
 
+The teach-back block is the production form this section prefers, and it is why a lesson carries one beside its quiz rather than a quiz alone. A quiz is recognition, so a lesson offering only one tests the weak form and reports it as retrieval. Asking the learner to explain the material to somebody who does not have it makes them produce the whole structure rather than pick from four, and what the explanation leaves out is the gap the next session places from.
+
+- Carry a teach-back block in every lesson, asking for an explanation rather than an answer
+- Name the audience the explanation is for, since an explanation with no reader has no floor to sit above
+- Record what the explanation left out under what the learner got wrong. A produced answer and a selected one are both retrieval failures, and splitting them across two sections splits one placement input.
+
 ## 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
+- Name what to revisit and when in the learning record, so the next session has a schedule rather than a guess
+
+The ladder is 1, 3, 7, 16, and 35 days. A topic retrieved unaided moves up a rung and a miss drops it back one, held inside the ladder at either end, so a topic the learner keeps missing stays on the shortest gap rather than restarting a sequence.
+
+Do not compute a date from that ladder by hand. `canon teach list <topic> --json` reports the schedule with both dates already resolved for every item, which is what turns the ladder into a number to copy rather than a rule to apply. An author told to widen a gap still picks the gap by judgment, and this is the same reason quiz option order is drawn by a verb rather than stated here.
 
 ## Interleaving
 

package/docs/agents/commands.md

@@ -37,7 +37,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon tasks validate`        | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`)                                                                                                                        |
 | `canon intake list`           | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                                                                                                              |
 | `canon intake answer`         | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                                                                                                                     |
-| `canon teach list`            | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                                                                                                                 |
+| `canon teach list`            | Report learning workspaces and the ordinal a new one takes, or what one workspace holds and what its records schedule (`--json`)                                                                                                   |
 | `canon teach open`            | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                                                                                                    |
 | `canon teach resource`        | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                                                                                                              |
 | `canon teach glossary`        | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                                                                                                                |

package/docs/agents/index.md

@@ -44,6 +44,6 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
-- [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, rewriting the root listing, a contents page, and each lesson's chrome from its marker regions, the refusal reasons, and why every write here runs through a verb
+- [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
 - [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

package/docs/agents/teach.md

@@ -1,6 +1,6 @@
 ---
 title: Teach
-description: Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, rewriting the root listing, a contents page, and each lesson's chrome from its marker regions, the refusal reasons, and why every write here runs through a verb
+description: Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions, the refusal reasons, and why every write here runs through a verb
 ---
 
 # Teach
@@ -29,6 +29,12 @@ A folder not named `NN-<topic>` is still listed rather than dropped, since dropp
 
 The listing also names the required files a workspace does not carry, which is `MISSION.md`, `RESOURCES.md`, and `GLOSSARY.md`. That is a report rather than a refusal, because a workspace missing one is still a workspace a session can resume.
 
+Every record carries `due`, read from the `## Revisit` sections of the workspace's learning records and sorted soonest first. Each entry names the `item`, its `date`, the `rung` it has reached on the spacing ladder, `overdue` once that date has arrived or passed, and the `record` the surviving entry was written in. A later record supersedes an earlier entry for the same item, matched without regard to case, since the schedule is the state of one topic rather than a log of every time it was set.
+
+Each entry also carries `hit` and `miss`, the two dates the next record could write. The ladder is 1, 3, 7, 16, and 35 days, a retrieval the learner passed unaided moving up a rung and a miss dropping back one, both held inside the ladder at either end. Reporting both dates is what lets a session copy one rather than compute it, on the same reasoning that put quiz option order in `canon teach lesson`.
+
+The field rides on the listing rather than on `canon teach lesson`, because a session needs the schedule before it has chosen what to teach and that verb takes a `--slug` naming a choice already made. An entry not written in the shape the standard fixes is skipped rather than reported, since a note carrying no date has no date to schedule.
+
 ## Open
 
 `canon teach open` creates a workspace at the next ordinal and writes all three required files.
@@ -152,6 +158,14 @@ A lesson carries its chrome as four marker pairs the authoring skill writes empt
 
 A lesson missing one of the four marker pairs is refused by name rather than rewritten, and every other lesson in the run still rewrites. The record's `skipped` list carries the refused files and which marker each is missing.
 
+The `style` region carries the quiz stepper after the workspace stylesheet, for every lesson but the one shape named three paragraphs down, so it wins the cascade at equal specificity and reaches a workspace seeded before it existed. The stepper is CSS over the radio inputs a quiz is written from: it hides every question that follows one holding no checked input, and hides a question's feedback until that question does. The general sibling combinator is what keeps that from depending on the markup contract holding, since it selects the same questions as the adjacent one for a quiz written correctly and goes on gating when anything sits between two of them, where the adjacent one matches nothing and shows them all at once. Gating there rather than in a script is what keeps a later stem from answering an earlier question with nothing to bind, and the whole block sits inside `@supports selector(:has(*))`, so an engine without `:has()` renders every question rather than a stepper showing nothing. Feedback there follows the workspace stylesheet, shown by one that says nothing about `.fb` and hidden by one grown under the retired script.
+
+The block hides and shows and sets nothing else, which leaves a workspace's own layout for a question and its own appearance for an option and a feedback panel. The one value it names is `display: block` on revealed feedback, since every stylesheet grown under the retired script carries `.fb { display: none }` and nothing adds the class that used to reveal it.
+
+One detector decides both regions. A lesson carrying `<button class="opt"`, the shape written before the stepper, takes the feedback script and no stepper, and every other lesson takes the stepper and no script. That is a detector rather than a mode, since a lesson has one shape or the other, and removing the script outright would leave the lessons already written showing no feedback at all.
+
+Splicing the stepper into a lesson of either shape was measured against a browser and reverted. Its rules match a button question, which can never hold a checked radio, so a lesson given both hides every question past the first for good and outranks the class the script reveals feedback with. Nothing else caught that: the markup is valid, the splice succeeds, and the page renders.
+
 ## Opening a workspace
 
 No `canon teach` verb serves the workspace. `canon serve` does, taking the teach root as its directory and the workspace contents page as its entry:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.48.1",
+  "version": "4.50.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/teach.ts

@@ -11,6 +11,7 @@ import {
   type ReadOutcome,
   readWorkspace,
   recordSources,
+  type RevisitItem,
   type Source,
   type SourceOutcome,
   type TeachRefused,
@@ -104,6 +105,11 @@ export function register(program: Command): void {
         'With no topic it reports one line per workspace and the ordinal an',
         'open would take. With one it reports the files behind each count.',
         '',
+        'Every record carries due, what the learning records schedule, each',
+        'entry with its date, its rung, and the date to write on a hit and',
+        'on a miss, so a session picks the next lesson from the schedule',
+        'rather than from the last session alone.',
+        '',
         'A workspace not named NN-<topic> is still listed. It sorts last and',
         'moves no ordinal, since dropping it hides the folder needing a fix.',
         '',
@@ -711,6 +717,17 @@ function reportRefusal(
   return 1
 }
 
+/**
+ * One scheduled revisit, carrying both ladder dates rather than the rung alone.
+ * A session copies the date the outcome names instead of computing one from a
+ * ladder stated in prose.
+ */
+function describeRevisit(item: RevisitItem): string {
+  const when = item.overdue ? `due ${item.date}` : item.date
+
+  return `${item.item}: ${when}, rung ${item.rung} (hit ${item.hit}, miss ${item.miss}), from ${item.record}`
+}
+
 function describe(workspace: WorkspaceSummary): string {
   return `${workspace.slug}: ${workspace.lessons} lesson(s), ${workspace.records} record(s), ${workspace.reference} reference page(s), ${workspace.terms} term(s)`
 }
@@ -795,6 +812,9 @@ function reportWorkspace(
   )
   for (const line of workspace.success) logInfo(line)
 
+  logStep(workspace.due.length > 0 ? 'Revisit' : 'Revisit (nothing scheduled)')
+  for (const item of workspace.due) logInfo(describeRevisit(item))
+
   if (workspace.missing.length > 0) {
     logStep('Missing a required file')
     logWarn(`no ${workspace.missing.join(' and no ')}`)

package/src/design/base.css

@@ -28,14 +28,22 @@
   --space-frame-top: 44px;
   --space-frame-inline: 52px;
   --space-frame-bottom: 38px;
+  --type-display-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-display-size: 34px;
   --type-display-lh: 1.3;
+  --type-page-display-family: Noto Sans, DejaVu Sans, sans-serif;
+  --type-page-display-size: 52px;
+  --type-page-display-lh: 1.1;
+  --type-heading-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-heading-size: 19px;
   --type-heading-lh: 1.3;
+  --type-body-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-body-size: 16px;
   --type-body-lh: 1.65;
+  --type-label-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-label-size: 12px;
   --type-label-lh: 1.45;
+  --type-code-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-code-size: 14.5px;
   --type-code-lh: 1.3;
   --radius-frame: 12px;

package/src/design/css.ts

@@ -76,6 +76,7 @@ function tokenProperties(tokens: DesignTokens): string[] {
   }
 
   for (const role of tokens.typography) {
+    lines.push(`  --type-${slug(role.role)}-family: ${role.family};`)
     lines.push(`  --type-${slug(role.role)}-size: ${role.size};`)
     lines.push(`  --type-${slug(role.role)}-lh: ${role.lineHeight};`)
   }

package/src/design/tokens.ts

@@ -68,9 +68,21 @@ export interface DesignTokens {
   readonly preamble: string
 }
 
-/** The one monospace stack every surface that renders text declares. */
+/** The monospace stack every surface but the landing page hero declares. */
 const MONO = 'Noto Sans Mono, DejaVu Sans Mono, monospace'
 
+/**
+ * The proportional stack the landing page hero declares and nothing else does.
+ * Noto Sans is the proportional sibling of the mono above rather than a face
+ * picked for taste, so the pairing is one superfamily rather than two systems.
+ *
+ * The stack stops at two names and a generic because `src/design/base.css` is
+ * written by `canon design regen` and formatted by prettier, and a declaration
+ * past 80 columns is wrapped by the second and flattened by the first. Every
+ * emitted line stays inside the width so the two writers never disagree.
+ */
+const SANS = 'Noto Sans, DejaVu Sans, sans-serif'
+
 const DARK_GROUNDS = ['background', 'surface'] as const
 const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
 
@@ -87,6 +99,8 @@ export const TOKENS: DesignTokens = {
 
   personality: [
     'Warm neutrals carry the frame under a single rust accent, rendered in the same monospace the terminal uses. The subject picks the register rather than taste: a toolkit whose primary surface is a shell has no proportional voice available, so the rendered surfaces match the terminal instead of the reverse. One accent carries every count, link, and primary action. Promoting a second and third into structural roles is what reads as a generated interface, so the palette stays at one.',
+    '',
+    'One surface is carved out of the sentence above, and it is the landing page hero. A rendered surface here shows a reader what the terminal did, so matching the terminal is what makes it legible. A public page addresses somebody who has never opened the terminal at all, and the shell has no voice available for that, which is the reverse of the case the rule was written for. The `page-display` role below is the whole of the carve-out. Every other role on that page stays monospace, including its body, its controls, and every frame it embeds, so the page reads as two families rather than as a second design system.',
   ].join('\n'),
 
   colorNote: [
@@ -193,7 +207,9 @@ export const TOKENS: DesignTokens = {
   ],
 
   typographyNote: [
-    'One family covers every role. The size scale runs from 11.5 to 34 pixels across ten values, and five of them map onto a role. The other five are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
+    'One family covers every role but `page-display`, which is the landing page hero and takes the proportional sibling of the same superfamily. The size scale runs from 11.5 to 52 pixels, and six values map onto a role. Five further values are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
+    '',
+    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches. A hero headline set at the display cap reads as a section heading rather than an opening, which four rendered arms measured on 2026-09-04 before the step was added.',
     '',
     'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
     '',
@@ -208,6 +224,14 @@ export const TOKENS: DesignTokens = {
       size: '34px',
       lineHeight: '1.3',
     },
+    {
+      role: 'page-display',
+      family: SANS,
+      weight: '700',
+      size: '52px',
+      lineHeight: '1.1',
+      verify: ['family', 'size', 'lineHeight'],
+    },
     {
       role: 'heading',
       family: MONO,

package/src/tasks/archive.ts

@@ -400,7 +400,8 @@ export async function planCitations(
 
   const stems = await listTaskStems(dir)
   if (!stems.includes(stem)) {
-    return refuse('no-match', `No task named ${stem} on the board.`, stems)
+    const unmatched = describeUnmatchedStem(stems, stem)
+    return refuse(unmatched.reason, unmatched.message, unmatched.detail)
   }
 
   const target = readPlanTarget(await readFile(join(dir, `${stem}.md`), 'utf8'))
@@ -488,6 +489,45 @@ function refuse(
   return { ok: false, reason, message, detail }
 }
 
+export interface UnmatchedStem {
+  readonly reason: 'no-match' | 'ambiguous'
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/**
+ * The three-way refusal a bare stem earns once it fails an exact match:
+ * exactly one task starts with it, several do, or none does. `archive.ts`'s
+ * own `resolveStem`, `planCitations`, and `record.ts`'s `resolveStem` all
+ * refuse a stem this way, so the wording lives once rather than three times.
+ */
+export function describeUnmatchedStem(
+  stems: readonly string[],
+  name: string,
+): UnmatchedStem {
+  const prefixed = stems.filter((stem) => stem.startsWith(name))
+  if (prefixed.length === 1) {
+    const [match] = prefixed
+    return {
+      reason: 'no-match',
+      message: `${name} does not name a task by itself. One task starts with it: ${match}. Pass the full name instead.`,
+      detail: [match],
+    }
+  }
+  if (prefixed.length > 1) {
+    return {
+      reason: 'ambiguous',
+      message: `${name} does not name a task by itself. ${prefixed.length} tasks start with it. Pass the full name instead.`,
+      detail: prefixed,
+    }
+  }
+  return {
+    reason: 'no-match',
+    message: `No task named ${name} on the board.`,
+    detail: stems,
+  }
+}
+
 async function resolveStem(
   dir: string,
   selector: TaskSelector,
@@ -496,27 +536,11 @@ async function resolveStem(
 
   if (selector.kind === 'stem') {
     if (!stems.includes(selector.stem)) {
-      const prefixed = stems.filter((stem) => stem.startsWith(selector.stem))
-      if (prefixed.length === 1) {
-        const [match] = prefixed
-        return refuse(
-          'no-match',
-          `${selector.stem} does not name a task by itself. One task starts with it: ${match}. Pass the full name to archive it.`,
-          [match],
-        )
-      }
-      if (prefixed.length > 1) {
-        return refuse(
-          'ambiguous',
-          `${selector.stem} does not name a task by itself. ${prefixed.length} tasks start with it. Pass the full name to archive one.`,
-          prefixed,
-        )
-      }
-      return refuse(
-        'no-match',
-        `No task named ${selector.stem} on the board.`,
+      const { reason, message, detail } = describeUnmatchedStem(
         stems,
+        selector.stem,
       )
+      return refuse(reason, message, detail)
     }
     return selector.stem
   }

package/src/tasks/record.ts

@@ -3,6 +3,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
 import { planCandidates } from '@/tasks/answers'
 import {
+  describeUnmatchedStem,
   fenceMask,
   linkTo,
   listTaskStems,
@@ -241,11 +242,11 @@ async function resolveStem(
 
   if (selector.kind === 'stem') {
     if (!stems.includes(selector.stem)) {
-      return refuse(
-        'no-match',
-        `No task named ${selector.stem} on the board.`,
+      const { reason, message, detail } = describeUnmatchedStem(
         stems,
+        selector.stem,
       )
+      return refuse(reason, message, detail)
     }
     return selector.stem
   }

package/src/teach/nav.ts

@@ -50,6 +50,55 @@ const CLOSE_OUTSIDE_CLICK_SCRIPT = `<script>
 })();
 </script>`
 
+/**
+ * The stepper, as CSS over the radio inputs a lesson's quiz is written from.
+ *
+ * A quiz showing every question at once lets a later stem answer an earlier
+ * question, which is a leak no wording of the questions closes. Gating on
+ * `:has()` rather than on a script keeps the page working with nothing to bind,
+ * and the radio input is what records an answer with no handler in the loop.
+ *
+ * The general sibling combinator is what keeps the gate from depending on the
+ * markup contract holding. It selects the same questions as `+` for a quiz
+ * written correctly, and it goes on gating when anything sits between two of
+ * them, where `+` matches nothing and shows every later question at once. That
+ * is the leak this block exists to close, arriving through a shape nothing
+ * rejects.
+ *
+ * The two hide rules select the unanswered state alone, so a workspace's own
+ * `display` for a question survives being stepped through. Feedback has to be
+ * shown by a rule naming a value, because every stylesheet grown under the
+ * retired script carries `.fb { display: none }` and nothing adds the class
+ * that revealed it. Appearance stays the workspace's: this block hides and
+ * shows and sets nothing else.
+ *
+ * `@supports` wraps every rule, so an engine without `:has()` renders every
+ * question rather than a stepper showing nothing. Feedback there follows the
+ * workspace: a fresh stylesheet shows it and one grown under the retired script
+ * keeps it hidden. Showing it unconditionally outside the wrapper was measured
+ * and reverted, since that rule outranks `.fb { display: none }` on every
+ * engine and would reveal the feedback in the button-shape lessons the script
+ * still drives.
+ */
+const QUIZ_CSS = `@supports selector(:has(*)) {
+  .quiz .q:not(:has(input[type="radio"]:checked)) ~ .q { display: none; }
+  .quiz .q:not(:has(input[type="radio"]:checked)) .fb { display: none; }
+  .quiz .q:has(input[type="radio"]:checked) > .fb { display: block; }
+}`
+
+/**
+ * The button shape a lesson written before the stepper carries. It is a
+ * detector rather than a mode: a lesson has one shape or the other, and which
+ * one it has decides both the style and the scripts region.
+ */
+const LEGACY_OPTION = '<button class="opt"'
+
+/**
+ * What reveals feedback in a lesson written against `LEGACY_OPTION`. The radio
+ * shape needs none of it, so a lesson carrying no button option gets no script,
+ * and removing this outright would leave the lessons already written showing no
+ * feedback at all.
+ */
 const QUIZ_SCRIPT =
   '<script>document.querySelectorAll(".q").forEach(function(q){var f=q.querySelector(".fb");q.querySelectorAll(".opt").forEach(function(b){b.addEventListener("click",function(){if(f.classList.contains("show"))return;q.querySelectorAll(".opt").forEach(function(o){o.dataset.state=o.dataset.a==="1"?"right":(o===b?"chosen":"wrong");});f.classList.add("show");});});});</script>'
 
@@ -662,11 +711,20 @@ async function rewriteLesson(
     metas.map<TrackState>((_, i) => (i === index ? 'here' : 'done')),
   )
 
+  // One detector decides both mechanisms, because a lesson carries one quiz
+  // shape or the other and the two cannot share a page. The stepper's rules
+  // match a button question that can never hold a checked radio, so a lesson
+  // given both would hide every question past the first for good and outrank
+  // the class the script reveals feedback with.
+  const legacy = html.includes(LEGACY_OPTION)
+
   const regions: ReadonlyArray<readonly [Region, string]> = [
-    ['style', `<style>\n${css}\n</style>`],
+    // The stepper follows the workspace stylesheet so it wins the cascade at
+    // equal specificity, which is what reaches a workspace seeded before it.
+    ['style', `<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>`],
     ['header', header],
     ['footnav', renderFootNav(metas, index)],
-    ['scripts', renderScripts(html.includes('class="quiz"'), false)],
+    ['scripts', renderScripts(legacy, false)],
   ]
 
   for (const [region, content] of regions) {

package/src/teach/workspace.ts

@@ -75,6 +75,44 @@ const ORDINAL_WIDTH = 2
 
 const DATE_LENGTH = 'YYYY-MM-DD'.length
 
+const MS_PER_DAY = 24 * 60 * 60 * 1000
+
+/** The heading a learning record schedules its revisits under. */
+const REVISIT_HEADING = '## Revisit'
+
+/**
+ * The gaps a revisit item moves through, in days. A rung is a one-based index
+ * into this list, widening after a retrieval the learner passed unaided and
+ * narrowing after a miss, which is the spacing rule the pedagogy reference
+ * states. The values are here rather than in a skill body because a session
+ * told to widen a gap still picks the number by judgment.
+ */
+const REVISIT_LADDER = [1, 3, 7, 16, 35] as const
+
+/**
+ * One scheduled entry, as a learning record spells it. The rung is carried in
+ * the record rather than derived from how many records name the item, since a
+ * miss drops it back and a count only ever climbs.
+ */
+const REVISIT_ENTRY =
+  /^-\s+\*\*(.+?)\*\*:\s*due\s+(\d{4}-\d{2}-\d{2}),\s*rung\s+([1-9]\d*)\s*$/
+
+export interface RevisitItem {
+  /** What comes back up, as the record names it. */
+  readonly item: string
+  /** The day it comes back up, as `YYYY-MM-DD`. */
+  readonly date: string
+  readonly rung: number
+  /** True once that day has arrived or passed. */
+  readonly overdue: boolean
+  /** The date to schedule when the learner retrieves it unaided. */
+  readonly hit: string
+  /** The date to schedule when they miss it. */
+  readonly miss: string
+  /** The record the surviving entry was written in. */
+  readonly record: string
+}
+
 export interface WorkspaceSummary {
   readonly slug: string
   /** `NaN` when the folder name carries no ordinal, which a listing reports. */
@@ -99,6 +137,12 @@ export interface WorkspaceDetail extends WorkspaceSummary {
   readonly glossary: readonly string[]
   /** The mission's success lines, which a session reports progress against. */
   readonly success: readonly string[]
+  /**
+   * What the learning records schedule, soonest first. A session reads this
+   * before it has chosen what to teach, which is why it rides on the listing
+   * rather than on the verb that resolves a lesson already picked.
+   */
+  readonly due: readonly RevisitItem[]
 }
 
 export interface WorkspacesListed {
@@ -242,6 +286,103 @@ function successLines(text: string): string[] {
   )
 }
 
+/**
+ * Whether a `YYYY-MM-DD` string names a real day.
+ *
+ * The entry pattern admits `2026-13-45`, since it counts digits rather than
+ * reading a calendar, and `addDays` throws on a date that names no day, so a
+ * single mistyped record would take down every listing that reads the
+ * workspace. Every date reaching `addDays` passes here first.
+ */
+function isDay(date: string): boolean {
+  return !Number.isNaN(Date.parse(`${date}T00:00:00Z`))
+}
+
+/** A day offset from a real `YYYY-MM-DD` date, back out in the same form. */
+function addDays(date: string, days: number): string {
+  const start = Date.parse(`${date}T00:00:00Z`)
+  return new Date(start + days * MS_PER_DAY).toISOString().slice(0, DATE_LENGTH)
+}
+
+/** A rung moved by one step, held inside the ladder at both ends. */
+function stepRung(rung: number, step: number): number {
+  return Math.min(REVISIT_LADDER.length, Math.max(1, rung + step))
+}
+
+function gapFor(rung: number, step: number): number {
+  return REVISIT_LADDER[stepRung(rung, step) - 1]
+}
+
+export interface RecordText {
+  readonly file: string
+  readonly text: string
+}
+
+/**
+ * Every revisit a workspace's learning records schedule, soonest first.
+ *
+ * Records arrive in read order and a later one supersedes an earlier entry for
+ * the same item, since the schedule is the state of one topic rather than a log
+ * of every time it was set. Matching is case-insensitive on the item, so a
+ * session that capitalized differently in a later record still supersedes
+ * rather than opening a second schedule beside the first.
+ *
+ * An entry not in the recorded shape is skipped rather than reported. A note
+ * carrying no date schedules nothing, which is what the standard's anti-pattern
+ * names, and this reader has no date to put on it. A date naming no real day is
+ * skipped on the same footing, since a schedule nothing can order is a note.
+ */
+export function readRevisits(
+  records: readonly RecordText[],
+  today: string,
+): RevisitItem[] {
+  if (!isDay(today)) return []
+
+  const scheduled = new Map<
+    string,
+    { item: string; date: string; rung: number; record: string }
+  >()
+
+  for (const record of records) {
+    const lines = record.text.split('\n')
+    const section = sectionRange(
+      unfenced(record.text),
+      REVISIT_HEADING,
+      lines.length,
+    )
+
+    if (!section) continue
+
+    for (const block of bulletBlocks(lines.slice(section.start, section.end))) {
+      const match = REVISIT_ENTRY.exec(block.join(' ').replace(/\s+/g, ' '))
+      if (!match || !isDay(match[2])) continue
+
+      scheduled.set(match[1].toLowerCase(), {
+        item: match[1],
+        date: match[2],
+        rung: Number(match[3]),
+        record: record.file,
+      })
+    }
+  }
+
+  return [...scheduled.values()]
+    .map((entry) => ({
+      item: entry.item,
+      date: entry.date,
+      rung: entry.rung,
+      overdue: entry.date <= today,
+      hit: addDays(today, gapFor(entry.rung, 1)),
+      miss: addDays(today, gapFor(entry.rung, -1)),
+      record: entry.record,
+    }))
+    .sort(
+      (left, right) =>
+        left.date.localeCompare(right.date) ||
+        left.item.localeCompare(right.item),
+    )
+}
+
 /** The ordinal a folder name carries, or `NaN` when it carries none. */
 function ordinalOf(slug: string): number {
   const match = WORKSPACE_NAME.exec(slug)
@@ -272,6 +413,15 @@ async function summarize(
     filesIn(dir, TEACH_REFERENCE, '.md'),
   ])
 
+  // Read order is filename order, which is record order, so a later record
+  // supersedes an earlier schedule for the same item.
+  const records = await Promise.all(
+    recordFiles.map(async (file) => ({
+      file,
+      text: await readFile(join(dir, TEACH_RECORDS, file), 'utf8'),
+    })),
+  )
+
   return {
     slug,
     ordinal: match ? Number(match[1]) : Number.NaN,
@@ -291,6 +441,7 @@ async function summarize(
     referenceFiles,
     glossary,
     success: mission === undefined ? [] : successLines(mission),
+    due: readRevisits(records, today()),
   }
 }
 

package/standards/teach.md

@@ -90,11 +90,27 @@ One record per session the learner worked through, holding what happened rather
 
 - The lessons covered, by number
 - What the learner retrieved correctly without help
-- What they got wrong, and what the wrong answer was
-- What to revisit, and roughly when
+- What they got wrong, and what the wrong answer was, including what an explanation the learner produced left out
+- A `## Revisit` section scheduling what comes back up
 
 Record the wrong answer rather than the fact of an error. A wrong answer names the misconception, and the count alone names nothing.
 
+A produced explanation and a selected option are both retrieval, so a gap in an explanation goes under what the learner got wrong rather than under a heading of its own. Name the concept and where the explanation broke. Splitting the two puts one input to the next session's placement across two sections, and the placement reads both or neither.
+
+### The revisit section
+
+Write one bullet per item, in this shape and no other:
+
+```markdown
+## Revisit
+
+- **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
+```
+
+The rung is where the item sits on the spacing ladder, and it travels in the record rather than being counted from how many records name the item, since a miss drops it back and a count only climbs. A later record naming the same item supersedes an earlier one, so revise the schedule by writing the new entry rather than editing the old record.
+
+Take the date and the rung from what the surface driving the workspace reports rather than picking either. An entry outside this shape schedules nothing, and nothing reports that it was skipped.
+
 ## GLOSSARY.md
 
 Required in every workspace, holding one entry per term the subject defines. The glossary reference the `canon:claude-teach` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
@@ -122,6 +138,7 @@ A source found and not read is listed as a lead because a link attached to a pag
 - **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
 - **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
 - **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
+- **The revisit note with no date.** A line naming what to come back to and not when is read by nothing and schedules nothing, so the next session picks from the last record alone, which is the state the section exists to end.
 - **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
 - **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
 

package/tooling/astro/configs/playwright.config.ts

@@ -22,5 +22,6 @@ export default defineConfig({
     command: 'bun run build && bun run preview',
     url: baseURL,
     reuseExistingServer: false,
+    env: { ASTRO_PREVIEW_BACKGROUND: '0' },
   },
 })