@erclx/aitk 0.102.0 → 0.103.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.103.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,7 +38,7 @@ 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.
 
@@ -102,6 +103,42 @@ Record the wrong answer rather than the count. The next session places the learn
 
 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.
 
+## 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
 
 ```plaintext
@@ -113,3 +150,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/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/teach.md

@@ -5,7 +5,7 @@ description: Listing learning workspaces and the ordinal a new one takes, openin
 
 # 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.
 

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.103.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

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