@erclx/aitk 0.102.0 → 0.104.0

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

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

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

@@ -11,6 +11,8 @@ Without this skill, the planning docs describe the scope the session opened with
 
 A decision's verification anchor has the same shape of gap in the other direction. The reasoning keeps reading as current while the number it cites moves underneath, and an amendment written without an anchor leaves nothing recording which numbers were checked and which nobody has read since.
 
+A handoff file has the same shape of gap as an unmarked outcome. A page a learning workspace produced and an operator already picked a destination for sits in gitignored scratch until something lands it, and the session that produced it is gone by the time a branch exists to carry the write. Left unfolded it reads as promoted while the destination holds nothing.
+
 The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
 
 ## Must
@@ -24,6 +26,8 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 - Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
 - Anchor a decision entry this run writes or amends whose reasoning cites a measured number, re-reading the number against the tree before writing the marker
 - Report an anchored decision whose cited path the diff touched, since the number was read before the branch moved what it counted
+- Land each block of a promotion handoff at the destination its heading names, then delete the file so a later run does not fold it twice
+- Take a promotion destination as already decided, since the operator confirmed it where the page was produced
 
 ## Must not
 
@@ -32,6 +36,7 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 - Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
 - Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
 - Create a context entry or delete a plan
+- Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.
 - Write an anchor onto a decision the run did not amend, or refresh one without re-reading the number. A date from a pass that measured nothing is the false confidence the marker exists to prevent.
 - Anchor an entry written before the rule, which dates it by blame rather than by a read
 
@@ -43,7 +48,8 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 ## Out of scope
 
 - Creating a task file or moving one off the board, which `claude-tasks` owns
-- Public-facing docs, which `docs-sync` owns. This skill reconciles the `.claude/` planning surface, and both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
+- Public-facing docs, which `docs-sync` owns, apart from landing a page a promotion handoff already carries a confirmed destination for. This skill reconciles the `.claude/` planning surface, and both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
+- Deciding where a promoted page belongs, which is settled with the operator by the surface that produced the page
 - Regenerating the task index, owned by a hook
 - Redrawing diagrams, which `claude-diagram` owns. This skill flags staleness and leaves the re-run to the author.
 - Re-measuring an architecture claim to decide whether its number moved. The sweep keys on a cited path entering the diff, so a claim whose number moved with no cited path in the diff goes unflagged.

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

@@ -51,7 +51,7 @@ Read these in parallel from the current worktree root (`pwd`), not the main work
 
 Read the task board from the main worktree root instead, per Worktrees in `CLAUDE.md`. It is gitignored scratch and never commits with the branch:
 
-- `.claude/tasks/index.md` first, then the task files this session touched. That narrow read serves the marking step. Step 9 reads every file in the folder for its plans sweep and states that where it gives the instruction.
+- `.claude/tasks/index.md` first, then the task files this session touched. That narrow read serves the marking step. The scratch sweep reads every file in the folder for its plans sweep and states that where it gives the instruction.
 
 ## Step 2: identify what changed
 
@@ -85,7 +85,7 @@ The steps that follow reach past the session, so each earns the reach separately
 - Steps 4 and 5 stub against the diff. These are why the skip is not a stop. A session that changed no docs is exactly when an uncovered surface or diagram kind goes unnoticed.
 - Step 6 reads the architecture record against the diff. A run that amended no decision is the one where an anchored number moves under a reasoning nobody reread, which is the case the marker exists to surface.
 - Step 8 rewrites context entries against the diff and against the facts `claude-memory-capture` routed. The Diff baseline section above groups its diff half with Steps 4 and 5 as a scoped-set step, so a quiet session is no different from any other for it. The routed half reads a named file and runs whatever the diff shows.
-- Step 9 reads the board rather than the session. Its board-wide scan exists to clear a plan an earlier run stranded, and a run that stops at Step 2 can never reach one.
+- The scratch sweep reads the board rather than the session. Its board-wide scan exists to clear a plan an earlier run stranded, and a run that stops at Step 2 can never reach one.
 
 This changes which steps the skill reaches. It does not widen what any of them reads. Steps 4, 5, 6, and 8 still take the same scoped set the Diff baseline section defines, and that section's rule is about the input a step is handed rather than about which steps run.
 
@@ -184,7 +184,30 @@ Add a line naming the handoff when one was consumed:
 
 The base lint-staged config runs `aitk indexes regen` on every committed `*.md`, so `.claude/context/index.md` refreshes automatically on commit. No manual step needed.
 
-## Step 9: sweep consumed scratch
+## Step 9: fold promoted pages
+
+Derive `<slug>` per `.claude/standards/slug.md`, falling back to `latest` on an empty result, and read `.claude/.tmp/teach-promotion/<slug>.md` at the main worktree root. `claude-teach` writes it, one H2 per destination naming the path, with a source line under the heading and the page body in a fenced block 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. Skip this step silently when the file is absent, which is every run where nothing was promoted.
+
+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 at the main root, since every destination here 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 stop with the block unfolded when the destination path already holds a file, since overwriting a page someone else wrote is not a fold.
+- A context entry is merged into rather than created. Fold the body into the sections it belongs under, the same way the routed facts above are folded, 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:
+
+`✅ Promoted: <destination path>`
+
+Add a line naming the handoff when one was consumed:
+
+`🧹 Folded: .claude/.tmp/teach-promotion/<slug>.md`
+
+Report a block left unfolded rather than dropping it:
+
+`⚠ Skipped: <destination path> already exists. Merge by hand.`
+
+## Step 10: sweep consumed scratch
 
 Sweep reviews this session consumed, and sweep plans across the whole board. Resolve all paths at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
 

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

@@ -13,6 +13,8 @@ It also produces one output where two are needed. A page written to be worked th
 
 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 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
@@ -26,21 +28,26 @@ Two failures land specifically on where the folder sits. A workspace resolved ag
 - 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
+- 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 outside the workspace folder, which is what a promotion pass owns rather than this skill
+- 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
 
-- Promoting a durable page out of the workspace, which is a judgment about public prose and belongs to a separate surface
+- 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

@@ -1,22 +1,23 @@
 ---
 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. Use when asked to "teach me X", "open a learning workspace", "I want to learn X", "quiz me on this", "continue the lesson", or "resume my workspace on X". 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.
+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 the workspace to resume>
+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/standards/teach.md`, or `${CLAUDE_SKILL_DIR}/../../standards/teach.md` when the project does not have that file. Read it before writing anything into the folder. The pedagogy sits in `${CLAUDE_SKILL_DIR}/references/pedagogy.md` and the lesson craft in `${CLAUDE_SKILL_DIR}/references/lesson-craft.md`.
+The shape of the workspace is fixed by `.claude/standards/teach.md`, or `${CLAUDE_SKILL_DIR}/../../standards/teach.md` when the project does not have that file. Read it before writing anything into the folder. The glossary answers to `.claude/standards/glossary.md`, or `${CLAUDE_SKILL_DIR}/../../standards/glossary.md` when the project does not have it. 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. A durable page stays in `reference/` until a promotion pass moves it, and this skill runs no promotion.
+- 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
 
@@ -37,9 +38,9 @@ From a linked worktree the file-editing tools refuse every path under the main r
 
 ## Step 1: open or resume
 
-A topic the listing already carries is a resume, and anything else is a new workspace.
+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 `aitk teach list <topic> --json` for the files behind each count, then read `MISSION.md`, the highest-numbered learning record, and `GLOSSARY.md`. Those three carry where the learner stopped and what they got wrong. Report the mission's success lines with what is already met before teaching anything.
+On a resume, run `aitk 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.
 
@@ -79,9 +80,27 @@ Open with retrieval on what the last session got wrong, before anything new. A l
 
 Two outputs with two lifetimes, and the split decides the format.
 
-- A lesson goes to `lessons/<nnnn>-<slug>.html`, self-contained, carrying its own quiz and the feedback for each answer. It links the shared stylesheet under `assets/` rather than restating styles, and the first lesson in a workspace writes that stylesheet before linking it. A lesson is disposable and is never promoted.
+- 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
+aitk 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
@@ -100,7 +119,43 @@ Write `learning-records/<nnnn>-<slug>.md` before the session ends, carrying the
 
 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. A mission whose lines are all met is finished, and saying so is what closes a workspace.
+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/standards/slug.md`, or `${CLAUDE_SKILL_DIR}/../../standards/slug.md` when the project does not have it. 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
 
@@ -113,3 +168,12 @@ Progress:  <n> of <m> success lines met
 ```
 
 Omit the reference line where the lesson produced no durable page. 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

@@ -13,6 +13,7 @@ A workspace accumulates lessons over weeks. The learner reads them as one body o
 
 - 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.
 
@@ -39,11 +40,17 @@ Every element competes with the material for attention.
 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.
-- Vary which position holds the correct answer, and never let the order follow the order the material was taught in
+- 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.

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 aitk 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.

package/docs/agents/index.md

@@ -26,4 +26,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [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, the refusal reasons, and why every write here runs through a verb
+- [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, the refusal reasons, and why every write here runs through a verb

package/docs/agents/teach.md

@@ -1,11 +1,11 @@
 ---
 title: Teach
-description: Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, the refusal reasons, and why every write here runs through a verb
+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, the refusal reasons, and why every write here runs through a verb
 ---
 
 # Teach
 
-Learning workspaces sit under `.claude/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats. Every verb here resolves that folder against the main worktree root rather than against the working directory, so a session standing in a linked worktree reaches the one workspace the learner has rather than opening a second.
+Learning workspaces sit under `.claude/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats, apart from the glossary, whose shape `standards/glossary.md` fixes so it travels with the file wherever a promotion lands it. Every verb here resolves that folder against the main worktree root rather than against the working directory, so a session standing in a linked worktree reaches the one workspace the learner has rather than opening a second.
 
 That root resolution is also why the writing verbs exist at all. The file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead, and a caller naming only the destination reports a success that did not happen. A whole-file create still goes out as a shell heredoc. Changing a line inside a file that already exists has no shell route, because the stream editors are banned, so `resource` and `glossary` are the route for the two files a running workspace edits.
 
@@ -102,6 +102,33 @@ A term already defined is refused rather than replaced. A definition the subject
 
 The entry lands as the standard's shape, leading with the term as a bolded span. A definition not ending in sentence punctuation is terminated before the citation is appended, so a bare phrase does not run into the sentence naming where the term first appears.
 
+## Lesson
+
+`aitk teach lesson` resolves what the next lesson needs before it is written. It reads and never writes.
+
+```bash
+aitk teach lesson regular-expressions \
+  --slug capture-groups \
+  --questions 3 \
+  --options 4
+```
+
+| Option            | Behavior                                                  |
+| ----------------- | --------------------------------------------------------- |
+| `--slug <kebab>`  | The lesson's own topic, required                          |
+| `--questions <n>` | How many questions the quiz carries, required             |
+| `--options <n>`   | How many options each question carries, defaulting to `4` |
+| `--json`          | Emit a machine-readable record on stdout                  |
+| `--root <path>`   | Teach root, defaulting to the main worktree               |
+
+It reports four things. `lesson` is the numbered path the lesson takes, derived from the highest ordinal already in `lessons/` the way an open derives a workspace ordinal. `stylesheet` names the one file every lesson in the workspace links, with `stylesheetExists` saying whether it is on disk yet and `stylesheetHref` carrying what the lesson's own link element holds. `success` carries the mission's success lines, so a session reports progress against the exit criteria without a second read of `MISSION.md`. `quiz` carries one entry per question.
+
+The stylesheet is reported rather than written. A verb that wrote it on every lesson would discard whatever the last lesson added, and the second lesson in a workspace is the one that needs the file the first one left.
+
+Each `quiz` entry carries `order`, the authored option indices in presentation order where index `0` is the correct answer, and `answer`, the one-based position that answer lands in. Both travel together because a caller deriving the position itself is a caller that can derive it wrongly.
+
+The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.
+
 ## Refusal reasons
 
 | Reason         | Raised when                                                     |
@@ -116,4 +143,4 @@ The entry lands as the standard's shape, leading with the term as a bolded span.
 | `defined`      | A term already carries a glossary entry                         |
 | `bad-input`    | The command line is malformed, before any folder is read        |
 
-A `bad-input` refusal reports the working directory as its root rather than the resolved one, since the command line is rejected before the root is worth resolving.
+A `bad-input` refusal reports the working directory as its root rather than the resolved one, since the command line is rejected before the root is worth resolving. `lesson` raises it for a slug that is not kebab-case, for a quiz carrying no question, and for a question carrying fewer than two options, since a question with one option has nothing to confuse the right answer with.

package/docs/ai-workflow.md

@@ -282,6 +282,8 @@ This section is the corpus the coverage claim is measured against: every name `a
 
 Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 
+A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `aitk:claude-teach` to promote sorts each durable page by who owns its subject, sending an outside subject to the wiki, an internal one to the matching context entry, and consumer-facing material to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `aitk:claude-docs` folds in from a branch. A project with no wiki folder gets a refusal naming `aitk wiki init` rather than a folder it never asked for.
+
 ## Feedback routing
 
 ```plaintext

package/package.json

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

package/src/commands/teach.ts

@@ -1,5 +1,6 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
+import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import {
   defineTerms,
   type ListOutcome,
@@ -57,6 +58,14 @@ interface ResourceCommandOptions {
   readonly root?: string
 }
 
+interface LessonCommandOptions {
+  readonly json?: boolean
+  readonly options?: string
+  readonly questions?: string
+  readonly root?: string
+  readonly slug?: string
+}
+
 interface GlossaryCommandOptions {
   readonly firstSeen?: string
   readonly json?: boolean
@@ -231,6 +240,42 @@ export function register(program: Command): void {
     .action(async (topic: string, opts: GlossaryCommandOptions) => {
       process.exitCode = await runGlossary(topic, opts)
     })
+
+  teach
+    .command('lesson')
+    .description('Resolve what the next lesson needs before it is written')
+    .argument('<topic>', 'Workspace folder or topic, as in regular-expressions')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--slug <kebab>', "The lesson's own topic, as in capture-groups")
+    .option('--questions <n>', 'How many questions the quiz carries')
+    .option('--options <n>', 'How many options each question carries', '4')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Teach root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the lesson was planned',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It writes nothing. It reports the numbered path the lesson takes, the',
+        'shared stylesheet with whether that file exists yet, the mission',
+        'success lines to report progress against, and one option order per',
+        'question.',
+        '',
+        'Write the correct option first and present the options in the order',
+        'reported. Position is drawn here rather than chosen, so an answer',
+        'cannot settle into the first slot.',
+        '',
+        'Examples:',
+        '  aitk teach lesson regular-expressions --slug capture-groups --questions 3 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (topic: string, opts: LessonCommandOptions) => {
+      process.exitCode = await runLesson(topic, opts)
+    })
 }
 
 function collect(value: string, previous: string[]): string[] {
@@ -435,6 +480,43 @@ async function runGlossary(
   )
 }
 
+async function runLesson(
+  topic: string,
+  opts: LessonCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!opts.slug) {
+    return reportRefusal(
+      'aitk teach lesson',
+      badInput('No lesson slug. Pass --slug <kebab>.'),
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  if (!opts.questions) {
+    return reportRefusal(
+      'aitk teach lesson',
+      badInput('No question count. Pass --questions <n>.'),
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = await rootFor(opts.root)
+
+  return reportLesson(
+    await planLesson(root, topic, {
+      slug: opts.slug,
+      questions: Number(opts.questions),
+      options: Number(opts.options ?? '4'),
+    }),
+    emitJson,
+    root,
+  )
+}
+
 function reportRefusal(
   title: string,
   refused: TeachRefused,
@@ -545,6 +627,11 @@ function reportWorkspace(
   logStep(workspace.glossary.length > 0 ? 'Glossary' : 'Glossary (empty)')
   for (const entry of workspace.glossary) logInfo(entry)
 
+  logStep(
+    workspace.success.length > 0 ? 'Exit criteria' : 'Exit criteria (none)',
+  )
+  for (const line of workspace.success) logInfo(line)
+
   if (workspace.missing.length > 0) {
     logStep('Missing a required file')
     logWarn(`no ${workspace.missing.join(' and no ')}`)
@@ -648,3 +735,52 @@ function reportGlossary(
 
   return 0
 }
+
+function reportLesson(
+  outcome: LessonOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk teach lesson', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        path: outcome.path,
+        lesson: outcome.lesson,
+        stylesheet: outcome.stylesheet,
+        stylesheetHref: outcome.stylesheetHref,
+        stylesheetExists: outcome.stylesheetExists,
+        success: outcome.success,
+        quiz: outcome.quiz,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk teach lesson')
+  logStep('Lesson')
+  logInfo(outcome.lesson)
+
+  logStep(outcome.stylesheetExists ? 'Stylesheet' : 'Stylesheet (to write)')
+  logInfo(`${outcome.stylesheet} linked as ${outcome.stylesheetHref}`)
+
+  logStep(outcome.success.length > 0 ? 'Exit criteria' : 'Exit criteria (none)')
+  for (const line of outcome.success) logInfo(line)
+
+  logStep('Option order')
+  for (const question of outcome.quiz) {
+    logInfo(
+      `question ${question.question}: present ${question.order.join(', ')}, correct answer in position ${question.answer}`,
+    )
+  }
+
+  outro()
+
+  return 0
+}

package/src/records/validate.ts

@@ -9,6 +9,7 @@ import {
   TEACH_RECORDS,
   TEACH_REFERENCE,
   TEACH_RESOURCES,
+  TEACH_SUCCESS_HEADING,
   WORKSPACE_NAME,
 } from '@/teach/workspace'
 
@@ -576,7 +577,6 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
   return [...findings, ...perCluster.flat()]
 }
 
-const TEACH_SUCCESS = /^##[ \t]+Success looks like[ \t]*$/
 const NUMBERED_RECORD = /^\d{4}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
 /**
  * A kebab slug that does not open with an ordinal. The lookahead rejects a
@@ -705,13 +705,15 @@ async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
     }
 
     if (
-      !linesOutsideFences(text).some((line) => TEACH_SUCCESS.test(line.trim()))
+      !linesOutsideFences(text).some(
+        (line) => line.trim() === TEACH_SUCCESS_HEADING,
+      )
     ) {
       findings.push(
         finding(
           'section-missing',
           slug,
-          '## Success looks like',
+          TEACH_SUCCESS_HEADING,
           'is absent, so the mission names no observable thing the learner will be able to do.',
         ),
       )

package/src/sandbox/expect.ts

@@ -209,23 +209,35 @@ export function countMechanicalAssertions(expectation: Expectation): number {
   )
 }
 
+/**
+ * An entry carrying `*` is matched as a glob, so an arm can assert a file whose
+ * name a run derives. Reports the matched path rather than the pattern, since a
+ * pass on `lessons/0001-*.html` says nothing until the name it found is named.
+ */
 function checkPaths(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
-  return expectation.paths.map((path) =>
-    existsSync(join(sandboxDir, path))
-      ? { ok: true, message: `exists: ${path}` }
-      : { ok: false, message: `missing: ${path}` },
-  )
+  return expectation.paths.map((path) => {
+    const written = writtenUnder(path, sandboxDir)
+
+    return written
+      ? { ok: true, message: `exists: ${written}` }
+      : { ok: false, message: `missing: ${path}` }
+  })
 }
 
 /**
- * An entry carrying `*` is matched as a glob, which is what lets an arm forbid
- * a file whose name a run derives rather than fixes. Pinning one spelling of a
- * derived name passes vacuously against every other spelling, which reads as
- * coverage the arm does not have. Returns the offending path so a failure names
- * the file the run wrote rather than the pattern that caught it.
+ * The first file an entry matches, or undefined when it matches none. An entry
+ * carrying `*` is matched as a glob, which is what lets an arm name a file whose
+ * name a run derives rather than fixes. Pinning one spelling of a derived name
+ * passes vacuously against every other spelling, which reads as coverage the arm
+ * does not have.
+ *
+ * Returning the match rather than a boolean is what lets a result name the file
+ * the run wrote instead of the pattern that found it. A glob matching several
+ * files answers with one of them in no fixed order, so an arm asserting content
+ * through a glob seeds a folder holding one.
  */
 function writtenUnder(pattern: string, sandboxDir: string): string | undefined {
   if (!pattern.includes('*')) {
@@ -260,14 +272,18 @@ function checkAbsent(
  * throwing, since an arm may assert content without also listing the path. A
  * pattern that does not compile is a defect in the declaration, so it fails the
  * assertion it belongs to rather than aborting the whole verdict.
+ *
+ * A path carrying `*` resolves to the file it matched, and falls back to itself
+ * when it matched none so the miss is reported against the entry as written.
  */
 function checkContent(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
   return expectation.content.map(({ path, pattern }) => {
-    const full = join(sandboxDir, path)
-    const label = `${path} =~ ${pattern}`
+    const matched = writtenUnder(path, sandboxDir) ?? path
+    const full = join(sandboxDir, matched)
+    const label = `${matched} =~ ${pattern}`
 
     let matcher: RegExp
     try {
@@ -279,6 +295,7 @@ function checkContent(
     if (!existsSync(full) || !statSync(full).isFile()) {
       return { ok: false, message: `no file to match: ${path}` }
     }
+
     if (matcher.test(readFileSync(full, 'utf8'))) {
       return { ok: true, message: `matches: ${label}` }
     }

package/src/teach/lesson.ts

@@ -0,0 +1,180 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  readWorkspace,
+  refuse,
+  TEACH_ASSETS,
+  TEACH_LESSONS,
+  TEACH_STYLESHEET,
+  type TeachRefused,
+} from '@/teach/workspace'
+
+/** Four digits inside a workspace, per the standard, because one holds many. */
+const LESSON_WIDTH = 4
+
+/** The ordinal a lesson filename opens with, which fixes its read order. */
+const LESSON_NUMBER = /^(\d{4})-/
+
+const LESSON_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+/** A quiz needs a right answer and at least one thing to confuse it with. */
+const MIN_OPTIONS = 2
+
+export interface QuizOrder {
+  /** One-based, so a report reads the same way the lesson numbers them. */
+  readonly question: number
+  /**
+   * Authored indices in the order the lesson presents them, where the authored
+   * index `0` is the correct answer. The author writes the correct option first
+   * and reads its position back off this list.
+   */
+  readonly order: readonly number[]
+  /** Where the correct answer lands, one-based, so no caller derives it. */
+  readonly answer: number
+}
+
+export interface LessonPlanned {
+  readonly ok: true
+  readonly slug: string
+  /** Relative to the root, so a caller prints a path a reader can open. */
+  readonly path: string
+  readonly lesson: string
+  readonly stylesheet: string
+  /** What the lesson's own `link` element carries, resolved from `lessons/`. */
+  readonly stylesheetHref: string
+  /** False on the first lesson in a workspace, which writes the stylesheet. */
+  readonly stylesheetExists: boolean
+  /** The mission's success lines, reported as the exit criteria they are. */
+  readonly success: readonly string[]
+  readonly quiz: readonly QuizOrder[]
+}
+
+export type LessonOutcome = LessonPlanned | TeachRefused
+
+export interface LessonRequest {
+  readonly slug: string
+  readonly questions: number
+  readonly options: number
+  /**
+   * Injected so a test can assert the shape of an order against a generator it
+   * controls. Every caller outside a test takes the default, which is what
+   * keeps the position of a correct answer off the author's judgment.
+   */
+  readonly random?: () => number
+}
+
+/**
+ * A uniform permutation of `0 .. count - 1` by Fisher-Yates.
+ *
+ * The bias this exists against is the authored order surviving into the
+ * lesson, which puts the correct answer first whenever the author wrote it
+ * first. Drawing the permutation here rather than in a prompt is what makes the
+ * position unguessable from the outside.
+ */
+function shuffled(count: number, random: () => number): number[] {
+  const order = Array.from({ length: count }, (_, index) => index)
+
+  for (let index = count - 1; index > 0; index -= 1) {
+    const pick = Math.floor(random() * (index + 1))
+    const held = order[index]
+    order[index] = order[pick]
+    order[pick] = held
+  }
+
+  return order
+}
+
+/**
+ * One presentation order per question, each carrying where the correct answer
+ * landed. Both halves travel together because a caller deriving the position
+ * itself is a caller that can derive it wrongly.
+ */
+export function orderQuiz(
+  questions: number,
+  options: number,
+  random: () => number = Math.random,
+): QuizOrder[] {
+  return Array.from({ length: questions }, (_, index) => {
+    const order = shuffled(options, random)
+
+    return {
+      question: index + 1,
+      order,
+      answer: order.indexOf(0) + 1,
+    }
+  })
+}
+
+/**
+ * The number the next lesson takes, read off the filenames already there.
+ *
+ * A file whose name carries no ordinal moves nothing, the way a workspace
+ * folder with no ordinal moves no workspace number. Numbering past it would
+ * renumber nothing and skipping it would hide it.
+ */
+function nextLesson(files: readonly string[]): string {
+  const highest = files
+    .map((file) => LESSON_NUMBER.exec(file)?.[1])
+    .filter((ordinal): ordinal is string => ordinal !== undefined)
+    .reduce((carry, ordinal) => Math.max(carry, Number(ordinal)), 0)
+
+  return String(highest + 1).padStart(LESSON_WIDTH, '0')
+}
+
+/**
+ * Everything a lesson needs resolved before it is written: where it goes, which
+ * stylesheet it links and whether that file is already on disk, the mission's
+ * exit criteria, and the order each quiz presents its options in.
+ *
+ * The stylesheet is reported rather than written. Every lesson after the first
+ * reads the one the first wrote, so a verb that rewrote it on every lesson
+ * would discard whatever the last one added.
+ */
+export async function planLesson(
+  root: string,
+  selector: string,
+  request: LessonRequest,
+): Promise<LessonOutcome> {
+  if (!LESSON_SLUG.test(request.slug)) {
+    return refuse('bad-input', `Not a kebab-case slug: ${request.slug}.`, [
+      request.slug,
+    ])
+  }
+
+  if (!Number.isInteger(request.questions) || request.questions < 1) {
+    return refuse(
+      'bad-input',
+      'A lesson carries at least one question. Pass --questions <n>.',
+    )
+  }
+
+  if (!Number.isInteger(request.options) || request.options < MIN_OPTIONS) {
+    return refuse(
+      'bad-input',
+      `A question carries at least ${MIN_OPTIONS} options. Pass --options <n>.`,
+    )
+  }
+
+  const found = await readWorkspace(root, selector)
+  if (!found.ok) return found
+
+  const workspace = found.workspace
+  const lesson = join(
+    workspace.path,
+    TEACH_LESSONS,
+    `${nextLesson(workspace.lessonFiles)}-${request.slug}.html`,
+  )
+  const stylesheet = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+
+  return {
+    ok: true,
+    slug: workspace.slug,
+    path: workspace.path,
+    lesson,
+    stylesheet,
+    stylesheetHref: `../${TEACH_ASSETS}/${TEACH_STYLESHEET}`,
+    stylesheetExists: existsSync(join(root, stylesheet)),
+    success: workspace.success,
+    quiz: orderQuiz(request.questions, request.options, request.random),
+  }
+}

package/src/teach/workspace.ts

@@ -32,6 +32,22 @@ export const TEACH_GLOSSARY = 'GLOSSARY.md'
 export const TEACH_REFERENCE = 'reference'
 export const TEACH_RECORDS = 'learning-records'
 export const TEACH_LESSONS = 'lessons'
+export const TEACH_ASSETS = 'assets'
+
+/**
+ * The one stylesheet every lesson in a workspace links. The name is fixed here
+ * rather than chosen per lesson, because the second lesson has to reach the
+ * file the first one wrote and a name composed twice is a name that can differ.
+ */
+export const TEACH_STYLESHEET = 'course.css'
+
+/**
+ * The mission heading whose list a session reads as exit criteria. The writer,
+ * the reader below, and the record validator all match this one spelling, so a
+ * heading none of them can find fails the validator rather than reading as an
+ * empty list.
+ */
+export const TEACH_SUCCESS_HEADING = '## Success looks like'
 
 /**
  * A workspace folder as the standard names it, capturing the ordinal and the
@@ -79,6 +95,8 @@ export interface WorkspaceDetail extends WorkspaceSummary {
   readonly recordFiles: readonly string[]
   readonly referenceFiles: readonly string[]
   readonly glossary: readonly string[]
+  /** The mission's success lines, which a session reports progress against. */
+  readonly success: readonly string[]
 }
 
 export interface WorkspacesListed {
@@ -141,7 +159,7 @@ export interface OpenRequest {
   readonly date?: string
 }
 
-function refuse(
+export function refuse(
   reason: TeachRefusal,
   message: string,
   detail: readonly string[] = [],
@@ -198,6 +216,30 @@ function glossaryTerms(text: string): string[] {
     .map((line) => line.trim().slice('- '.length))
 }
 
+/**
+ * The mission's success lines, each one an observable thing the learner will be
+ * able to do. A session reads them as exit criteria, so a wrapped entry is
+ * joined back into one line rather than reported as two criteria.
+ *
+ * A mission carrying no such heading yields nothing rather than refusing. The
+ * record validator is what reports the absent section, and a listing that
+ * refused would take the whole workspace down with it.
+ */
+function successLines(text: string): string[] {
+  const lines = text.split('\n')
+  const section = sectionRange(
+    unfenced(text),
+    TEACH_SUCCESS_HEADING,
+    lines.length,
+  )
+
+  if (!section) return []
+
+  return bulletBlocks(lines.slice(section.start, section.end)).map((block) =>
+    block.join(' ').trim().slice('- '.length).replace(/\s+/g, ' ').trim(),
+  )
+}
+
 /** The ordinal a folder name carries, or `NaN` when it carries none. */
 function ordinalOf(slug: string): number {
   const match = WORKSPACE_NAME.exec(slug)
@@ -211,9 +253,11 @@ async function summarize(
 ): Promise<WorkspaceDetail> {
   const match = WORKSPACE_NAME.exec(slug)
   const missionPath = join(dir, TEACH_MISSION)
-  const frontmatter = existsSync(missionPath)
-    ? parseFrontmatter(await readFile(missionPath, 'utf8'))
+  const mission = existsSync(missionPath)
+    ? await readFile(missionPath, 'utf8')
     : undefined
+  const frontmatter =
+    mission === undefined ? undefined : parseFrontmatter(mission)
 
   const glossaryPath = join(dir, TEACH_GLOSSARY)
   const glossary = existsSync(glossaryPath)
@@ -244,6 +288,7 @@ async function summarize(
     recordFiles,
     referenceFiles,
     glossary,
+    success: mission === undefined ? [] : successLines(mission),
   }
 }
 

package/standards/glossary.md

@@ -0,0 +1,75 @@
+---
+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 `.claude/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 and word choice: `prose.md`
+- Headings, punctuation, 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.
+- 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.
+
+## 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/standards/index.md

@@ -11,6 +11,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
+- [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
@@ -26,6 +27,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
-- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
+- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/teach.md

@@ -1,6 +1,6 @@
 ---
 title: Teach reference
-description: Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
+description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 ---
 
 # Teach reference
@@ -11,10 +11,11 @@ The folder is gitignored. Its markdown half is written in a format the authoring
 
 ## Scope
 
-Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats.
+Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
 
 Does not govern:
 
+- The frontmatter, entry shape, and ordering of the glossary the workspace holds: `glossary.md`
 - What a lesson teaches, how it sequences difficulty, and what makes one worth returning to, which belong to the surface driving the workspace
 - Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
 - One question measured in depth before anyone can plan against it: `groundwork.md`
@@ -96,12 +97,9 @@ Record the wrong answer rather than the fact of an error. A wrong answer names t
 
 ## GLOSSARY.md
 
-One entry per term the subject defines, sorted alphabetically.
+Required in every workspace, holding one entry per term the subject defines. `glossary.md` 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.
 
-- Lead each entry with the term as a bolded span, then the definition in one or two sentences
-- Define the term without using it
-- Name the lesson or reference page where the term first appears
-- Keep an entry to the meaning. Worked detail belongs on a reference page.
+Name the lesson or reference page a term first appears in as that standard requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.
 
 ## RESOURCES.md