@erclx/canon 4.67.0 → 4.69.0

package/src/commands/sandbox.ts

@@ -78,6 +78,7 @@ interface CheckOptions {
   readonly writes?: string
   readonly escapes?: string
   readonly escapesWatched?: boolean
+  readonly concurrentSessions?: string
   readonly json?: boolean
   readonly strict?: boolean
 }
@@ -349,7 +350,7 @@ function runCheck(
 
   const parsed = parseTarget(target)
   if (parsed === undefined) {
-    logError('Invalid target. Use <category>:<command>, e.g. claude:docs.')
+    logError('Invalid target. Use <category>:<command>, e.g. claude:docs-fold.')
     outro()
     process.exitCode = 1
     return
@@ -376,6 +377,7 @@ function runCheck(
         options.escapes === undefined
           ? undefined
           : options.escapesWatched === true,
+      concurrentSessions: readPathList(options.concurrentSessions),
       envelope: readEnvelope(options.envelope),
     },
   )
@@ -414,7 +416,10 @@ export function register(program: Command): void {
   sandbox
     .command('check')
     .description('Check a provisioned sandbox against a scenario expectation')
-    .argument('<target>', 'Scenario as <category>:<command>, e.g. claude:docs')
+    .argument(
+      '<target>',
+      'Scenario as <category>:<command>, e.g. claude:docs-fold',
+    )
     .argument('[arm]', 'Named scenario arm, e.g. drift')
     .helpOption('-h, --help', 'Show this help message')
     .option('--envelope <file>', 'Run envelope JSON from claude -p')
@@ -427,6 +432,10 @@ export function register(program: Command): void {
       '--escapes-watched',
       'At least one watched root held a target this run, so a zero-escape file is a clean watch rather than one with nothing to watch',
     )
+    .option(
+      '--concurrent-sessions <file>',
+      'Newline-delimited sessions live in the registry both before and after this run, a witness for an unbounded escape',
+    )
     .option('--json', 'Emit the verdict as JSON on stdout')
     .option('--strict', 'Exit non-zero when the arm declares no expectation')
     .addHelpText(
@@ -434,8 +443,8 @@ export function register(program: Command): void {
       [
         '',
         'Examples:',
-        '  canon sandbox check claude:docs drift',
-        '  canon sandbox check claude:docs drift --envelope run.json --json',
+        '  canon sandbox check claude:docs-fold drift',
+        '  canon sandbox check claude:docs-fold drift --envelope run.json --json',
         '',
         'Exit codes: 0 on pass or unchecked, 1 on failure.',
         'With --strict, unchecked exits 1 as well.',

package/src/commands/sync.ts

@@ -265,7 +265,7 @@ function renderTooling(report: CheckReport): void {
 /**
  * Seeds print their own section because no sync command applies them. A `stale`
  * seed is safe to take whole and a `drifted` one holds edits, which is the split
- * `claude-seed-sync` reads to decide what needs a section-level merge.
+ * `seed-sync` reads to decide what needs a section-level merge.
  */
 function renderSeeds(report: CheckReport): void {
   const notable = report.seeds.entries.filter(
@@ -283,7 +283,7 @@ function renderSeeds(report: CheckReport): void {
     logWarn(`${entry.rel} (${entry.state})`)
   }
 
-  logInfo('Run /canon:claude-seed-sync to reconcile these section by section.')
+  logInfo('Run /canon:seed-sync to reconcile these section by section.')
 }
 
 /**
@@ -399,7 +399,7 @@ async function runSync(target: string): Promise<number> {
 
   if (existsSync(join(resolved, '.claude'))) {
     process.stderr.write(
-      `${GREY}Tip: run \`/claude-seed-sync\` to audit seed drift per section, preserving local customizations.${NC}\n`,
+      `${GREY}Tip: run \`/seed-sync\` to audit seed drift per section, preserving local customizations.${NC}\n`,
     )
   }
 

package/src/design/components.ts

@@ -998,6 +998,18 @@ h2 .count {
   line-height: 1.55;
 }
 
+.gloss-group {
+  margin: 1.1rem 0 0.4rem;
+  font-family: var(--teach-sans);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--color-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+}
+
+.gloss-group:first-of-type { margin-top: 0; }
+
 .gterm b { font-weight: 700; }
 /* The markdown source separates a term from its definition with a colon,
    and the house standard bans an em dash outright, so the view mirrors

package/src/design/tokens.ts

@@ -354,7 +354,7 @@ export const TOKENS: DesignTokens = {
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
 
   iconography:
-    "No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing. The same mark also ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift: `regen-hero.sh` derives one from the live SVG colored with whatever `--color-accent` (`#e0724b`) the fetched token CSS carries, `src/design/render.ts` carries the path data as a hardcoded literal colored via `colorValue('light-accent')` (`#a4471c`), since a data URI has no CSS context and that page renders on light chrome, and `claude-teach`'s `SKILL.md` names one in prose colored `rgb(224,114,75)`, the same value as the dark accent written as decimal rather than hex to clear the shipped-references gate's commit-sha check. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for.",
+    "No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing. The same mark also ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift: `regen-hero.sh` derives one from the live SVG colored with whatever `--color-accent` (`#e0724b`) the fetched token CSS carries, `src/design/render.ts` carries the path data as a hardcoded literal colored via `colorValue('light-accent')` (`#a4471c`), since a data URI has no CSS context and that page renders on light chrome, and `teach-workspace`'s `SKILL.md` names one in prose colored `rgb(224,114,75)`, the same value as the dark accent written as decimal rather than hex to clear the shipped-references gate's commit-sha check. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for.",
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */

package/src/gate/measures.ts

@@ -110,6 +110,17 @@ export const GOV_EXPECTED_UNREFERENCED = ['260-shadcn', '320-tanstack-query']
  */
 export const SANDBOX_UNDECLARED_CEILING = 47
 
+/**
+ * Skills the sandbox skill census reports `asserted`, taken from `canon
+ * sandbox coverage --skills` against a clean tree. A dropped pairing lowers
+ * this directly, unlike the ceiling above, which a rename can starve without
+ * moving: fourteen arms drifted off their skill's name in one branch and the
+ * scenario-level ceiling stayed green throughout, since it counts scenarios
+ * declaring an expectation rather than skills a scenario reaches. Lowering
+ * this floor is a deliberate edit that says which skill lost its arm and why.
+ */
+export const SANDBOX_ASSERTED_FLOOR = 26
+
 /**
  * The retained counts the audit stage compares each run against. Spelled here
  * rather than derived, because this stage only ever names the file in a remedy
@@ -740,10 +751,45 @@ export const sandboxCoverage: Measure = async (ctx) => {
     }
   }
 
+  const scenarioEmission = info(
+    `${armed} of ${total} scenarios declare expectations, ${undeclared} undeclared against a ceiling of ${SANDBOX_UNDECLARED_CEILING}`,
+  )
+
+  const skillsRun = await ctx.cli(['sandbox', 'coverage', '--skills', '--json'])
+
+  if (skillsRun.exitCode !== 0) {
+    return {
+      emissions: [scenarioEmission],
+      unmeasured: `The skill census did not report (exit ${skillsRun.exitCode}). It ships in the checkout beside the scenario report, so a run that does not report is a broken command rather than an absent census.`,
+    }
+  }
+
+  const skillsRecord = parseJson(skillsRun.stdout) as
+    | { asserted?: unknown; totalSkills?: unknown }
+    | undefined
+  const asserted = skillsRecord?.asserted
+  const totalSkills = skillsRecord?.totalSkills
+
+  if (typeof asserted !== 'number' || typeof totalSkills !== 'number') {
+    return {
+      emissions: [scenarioEmission],
+      failure:
+        'The skill census carried no asserted total, so the stage measured nothing. Run bun src/cli.ts sandbox coverage --skills --json.',
+    }
+  }
+
+  if (asserted < SANDBOX_ASSERTED_FLOOR) {
+    return {
+      emissions: [scenarioEmission],
+      failure: `${asserted} of ${totalSkills} skills asserted, under the floor of ${SANDBOX_ASSERTED_FLOOR}. A rename or a moved arm likely dropped a skill's pairing; repair the arm's filename against its skill and say which skill lost its arm, or lower SANDBOX_ASSERTED_FLOOR in src/gate/measures.ts.`,
+    }
+  }
+
   return {
     emissions: [
+      scenarioEmission,
       info(
-        `${armed} of ${total} scenarios declare expectations, ${undeclared} undeclared against a ceiling of ${SANDBOX_UNDECLARED_CEILING}`,
+        `${asserted} of ${totalSkills} skills asserted, against a floor of ${SANDBOX_ASSERTED_FLOOR}`,
       ),
     ],
   }

package/src/gov/restated.ts

@@ -24,7 +24,7 @@ export const RULES_REL = join('governance', 'rules')
 /**
  * Path pairs whose duplication is deliberate and already recorded.
  *
- * The seed is authored from the always-loaded file and `claude-seed-sync`
+ * The seed is authored from the always-loaded file and `seed-sync`
  * exists to reconcile the two, so a bullet appearing in both is the design
  * rather than a defect. Excluding by pair rather than by content is what the
  * plan settled on: the duplication is a location fact this repository already
@@ -574,7 +574,7 @@ function authorityFor(
   if (candidate.kind === 'seed') {
     return {
       authority: 'claude-md',
-      reason: `${INSTRUCTIONS_REL} is authored first and the seed carries it to a target, so an edit starts there and reaches the seed through claude-seed-sync`,
+      reason: `${INSTRUCTIONS_REL} is authored first and the seed carries it to a target, so an edit starts there and reaches the seed through seed-sync`,
     }
   }
 

package/src/markdown/structure.ts

@@ -26,7 +26,7 @@ const HEADING = /^#{1,6}\s/
  * run and a false one shortens every run around it until the measure stops
  * reporting, which is the dearer of the two.
  *
- * A colon ends most markers and not all of them. `claude-pr-review` writes
+ * A colon ends most markers and not all of them. `review-pr` writes
  * three colon-less ones into every body it posts and a bold path heading for
  * each file it reviews, so requiring the colon held a real seam out. Two
  * signals stand in where the colon is absent, because the shape a marker has to

package/src/migrate/rename.ts

@@ -46,8 +46,9 @@ export interface RenameRuleSpec {
    * A rename whose tokens are whole names wants this, and one whose tokens are
    * word stems cannot have it. `aitk` is a stem that legitimately carries a
    * suffix, as in `aitk-allow-superseded`, so requiring a boundary there would
-   * leave every hyphenated form behind. A skill name is not a stem, and
-   * `claude-worktree` inside `claude-worktrees` is a different subject: the
+   * leave every hyphenated form behind. A skill name is not a stem, and the
+   * spelling below is the pre-rename one on purpose (canon-keep-retired):
+   * `claude-worktree` inside `claude-worktrees` is a different subject, the
    * wiki page about the harness feature, which the rename must not move.
    */
   readonly wholeToken?: boolean
@@ -88,7 +89,7 @@ const NEVER_MATCHES = '(?!)'
  *
  * A plain word boundary rejects a following letter and accepts a following
  * hyphen, since `\b` reads a hyphen as the end of a word. That leaves
- * `claude-intake` matching inside `claude-intake-answer`, with the ordering of
+ * `plan-intake` matching inside `plan-intake-answer`, with the ordering of
  * the alternation the only thing standing between them. Naming the characters
  * that continue an identifier holds on both, so the ordering and the boundary
  * each cover what the other could miss, and a slash, a dot, or a backtick

package/src/pr/bijection.ts

@@ -99,7 +99,7 @@ function owesNoBullet(path: string): boolean {
  * names.
  *
  * An unanchored claim matches on a segment-anchored suffix, which is what lets
- * `claude-worker/SKILL.md` credit `claude/skills/claude-worker/SKILL.md`. That
+ * `role-worker/SKILL.md` credit `claude/skills/role-worker/SKILL.md`. That
  * asymmetry is deliberate: a partial spelling can confirm a changed file was
  * named and never accuse one of being absent, because nothing here separates a
  * path written short from a path written wrong.

package/src/pr/paths.ts

@@ -20,7 +20,7 @@ export interface PathClaim {
    * True when the first segment names an entry the tree actually holds.
    *
    * An unanchored claim is a path written partially, such as
-   * `claude-worker/SKILL.md` for a file under `claude/skills/`. It can confirm
+   * `role-worker/SKILL.md` for a file under `claude/skills/`. It can confirm
    * that a changed file was named and can never accuse one of being absent,
    * because the comparison has no way to tell a partial spelling from a
    * genuinely wrong one.
@@ -145,7 +145,7 @@ function maskSpans(text: string): string {
  * that came out. A path past the comma was left out of the claim set entirely
  * and fell to the unnamed direction, accepted here on the ground that the
  * direction reports without grading. It graded anyway, one consumer removed:
- * `claude-pr-review` reads `unnamed` as a question to put to the branch author,
+ * `review-pr` reads `unnamed` as a question to put to the branch author,
  * and on 2026-09-01 the question went to three pull requests over bullets that
  * had named the files all along, with `#1329` gaining bullets it did not need.
  *

package/src/sandbox/expect.ts

@@ -78,6 +78,14 @@ export interface CheckInput {
    * nothing to watch, both of which produce the same empty `escapes` list.
    */
   readonly escapesWatched?: boolean
+  /**
+   * Names of sessions the client's own registry carried both before and after
+   * the run, so present rather than dispatched by it. Undefined when the
+   * caller supplied none, which is not the same as a run that had no witness:
+   * the registry carries no contract, so a client that stops writing a record
+   * per session makes this list empty regardless of who else was live.
+   */
+  readonly concurrentSessions?: readonly string[]
   readonly envelope?: RunEnvelope
 }
 
@@ -386,11 +394,19 @@ function checkWriteScope(
  * empty `escapes` list. `watched` is what tells them apart: a run that had
  * nothing to watch reports unmeasured rather than passing on a diff it never
  * had the target to take.
+ *
+ * A witnessed concurrent session never softens the verdict. `concurrentSessions`
+ * is evidence a reader can act on without a second lookup, appended to the
+ * message on an unbounded escape, never a reason to pass or skip one: a session
+ * merely alive throughout the run proves someone else was busy, not that a
+ * given file is theirs, and a real dispatch escape reads identically to an
+ * innocent sibling's write either way.
  */
 function checkEscapeScope(
   expectation: Expectation,
   escapes: readonly string[] | undefined,
   watched: boolean | undefined,
+  concurrentSessions: readonly string[] | undefined,
 ): KindOutcome {
   if (expectation.escapeScope === undefined) return { results: [], skipped: [] }
 
@@ -416,12 +432,20 @@ function checkEscapeScope(
   }
 
   const globs = expectation.escapeScope.map((glob) => new Bun.Glob(glob))
+  const witnessCount = concurrentSessions?.length ?? 0
+  const witnessSuffix =
+    witnessCount > 0
+      ? ` (${witnessCount} session${witnessCount === 1 ? '' : 's'} live throughout the run)`
+      : ''
 
   return {
     results: escapes.map((path) =>
       globs.some((glob) => glob.match(path))
         ? { ok: true, message: `declared escape: ${path}` }
-        : { ok: false, message: `unbounded escape: ${path}` },
+        : {
+            ok: false,
+            message: `unbounded escape: ${path}${witnessSuffix}`,
+          },
     ),
     skipped: [],
   }
@@ -514,6 +538,7 @@ export function checkExpectation(
     expectation,
     input.escapes,
     input.escapesWatched,
+    input.concurrentSessions,
   )
   const reply = checkReply(expectation, input.envelope)
   const envelope = checkEnvelope(expectation, input.envelope)

package/src/shipped/references.ts

@@ -61,7 +61,7 @@ export const REFERENCE_MARKER = 'canon-allow-reference'
  * The leading boundary is what excludes the repair form by construction rather
  * than by exemption, and that is load bearing. A lookbehind rejecting a word
  * character before `#` never matches `erclx/canon#1299`, so a qualified
- * reference passes with no marker, and `claude/skills/claude-worktree/SKILL.md`
+ * reference passes with no marker, and `claude/skills/session-worktree/SKILL.md`
  * already ships `anthropics/claude-code#58345` in exactly that form.
  *
  * The trailing boundary is what the first shape of this pattern lacked, and it

package/src/sync/seeds-report.ts

@@ -34,7 +34,7 @@ export interface SeedsReport {
  * Classifies every seed the toolkit ships against the target's copy, and never
  * returns a change. Seeds are copy-once files a project is expected to edit, so
  * the engine's copy path would overwrite `CLAUDE.md` wholesale. Reporting alone
- * is what lets `claude-seed-sync` merge one section at a time instead.
+ * is what lets `seed-sync` merge one section at a time instead.
  *
  * Attribution reuses the history reader rather than the engine's own recovery
  * pass, which is private and takes a `SyncAdapter` seeds have no way to supply.

package/src/targets/pulls.ts

@@ -7,8 +7,8 @@ const GH_TIMEOUT_MS = 30_000
 /**
  * The two headings a review pass posts under.
  *
- * Owned by `claude-pr-review`, which states the full set once, and pinned here
- * the way `claude-orchestrate/scripts/poll.sh` pins them. All three surfaces
+ * Owned by `review-pr`, which states the full set once, and pinned here
+ * the way `role-orchestrator/scripts/poll.sh` pins them. All three surfaces
  * ship separately, so a heading added in that skill goes stale here with
  * nothing comparing the copies.
  */

package/src/tasks/answers.ts

@@ -186,7 +186,7 @@ export function resolvePlanReference(
   }
 
   // An archived plan answers every question and would report as launchable, so
-  // the name would clear a dispatch that `claude-autoship` Step 1 then refuses
+  // the name would clear a dispatch that `auto-ship` Step 1 then refuses
   // as already-shipped work. Catching it here is a step earlier than the worker.
   // Both roots, for the reason `resolveLivePlan` carries: the reference is a
   // string a caller wrote, and one spelling the root this tree has since left is

package/src/tasks/archive.ts

@@ -269,7 +269,7 @@ function isRowFor(line: string, target: string): boolean {
 
 /**
  * Resolves the `Plan:` target against the board and against the project root
- * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`
+ * both, which is how `docs-fold` reads the same line. It accepts `../plans/x.md`
  * and `.canon/plans/x.md` as one file, so a gate reading only the first form
  * would pass the second and strand the plan this exists to protect.
  *
@@ -323,7 +323,7 @@ function atOneRoot(path: string, plans: string[], root: string): string {
 
 /**
  * Names the other live tasks whose `Plan:` line lands on the same file. This is
- * the rule `claude-docs` applies before it archives a plan, held here so one
+ * the rule `docs-fold` applies before it archives a plan, held here so one
  * question has one implementation: a plan another live task still cites is a
  * plan the sweep is correct to leave, and a guard that read the folder instead
  * refused every task sharing one plan and deadlocked the board against the
@@ -380,7 +380,7 @@ export type CitationOutcome = PlanCitations | ArchiveRefused
 
 /**
  * Answers where one task's plan sits and who else holds it, which is the whole
- * of the last-live-citation rule. `claude-docs` reads this rather than scanning
+ * of the last-live-citation rule. `docs-fold` reads this rather than scanning
  * the board itself, so the sweep that moves a plan and the gate that refuses a
  * task archive cannot drift into disagreeing about which plan is free.
  *
@@ -564,7 +564,7 @@ async function resolveStem(
 
 /**
  * Archives one task as a single unit: the move, the ordering-row removal, and
- * the index regen. The hook and `claude-tasks` both call this, so every gate
+ * the index regen. The hook and `task-board` both call this, so every gate
  * refuses rather than reports. A caller with nobody watching cannot act on a
  * warning, and two callers gating differently is the drift this exists to stop.
  */

package/src/tasks/record.ts

@@ -311,7 +311,7 @@ export async function recordPullRequest(
 
 /**
  * Records a plan's path on the task it belongs to, as the task's `Plan:` line.
- * `claude-feature` runs this right after the plan file lands, resolving the
+ * `plan-feature` runs this right after the plan file lands, resolving the
  * reference the same two ways `canon tasks plan-answers` does, through
  * `planCandidates`, so a bare slug and a board-relative path both resolve.
  *
@@ -346,7 +346,7 @@ export async function recordPlan(
 }
 
 /**
- * Marks the named outcomes `[x]` in place. `claude-docs` runs this against a
+ * Marks the named outcomes `[x]` in place. `docs-fold` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions
  * come from the read it already made.
  */

package/src/tasks/validate.ts

@@ -557,7 +557,7 @@ async function listTaskStems(dir: string): Promise<string[]> {
 
 /**
  * Resolves a pointer against the board and against the project root both, the
- * way `claude-docs` reads the same line. A fragment is dropped first, since an
+ * way `docs-fold` reads the same line. A fragment is dropped first, since an
  * anchor is part of the link and never part of the path.
  */
 function resolves(target: string, dir: string, root: string): boolean {

package/src/teach/nav.ts

@@ -109,6 +109,17 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
   var input = document.getElementById("gfilter");
   var list = document.getElementById("gloss");
   if (!input || !list) return;
+  function updateGroups() {
+    list.querySelectorAll(".gloss-group").forEach(function (heading) {
+      var el = heading.nextElementSibling;
+      var any = false;
+      while (el && !el.classList.contains("gloss-group")) {
+        if (el.style.display !== "none") any = true;
+        el = el.nextElementSibling;
+      }
+      heading.style.display = any ? "" : "none";
+    });
+  }
   input.addEventListener("input", function () {
     var q = input.value.toLowerCase();
     var n = 0;
@@ -118,6 +129,7 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
       if (match) n++;
     });
     list.classList.toggle("none", n === 0);
+    updateGroups();
   });
   var clear = list.querySelector(".clear");
   if (clear) {
@@ -457,8 +469,90 @@ function renderGlossaryEntry(entry: string): string {
   return `<div class="gterm"><b>${escapeHtml(term)}</b><span>${escapeHtml(definition)}</span></div>`
 }
 
-function renderGlossarySection(entries: readonly string[]): string {
-  const rendered = entries.map(renderGlossaryEntry).join('')
+const FIRST_SEEN_PATTERN = / First seen in (.+)\.$/
+
+/**
+ * The lesson or reference page an entry's own "First seen in" sentence
+ * names, absent when the entry predates that citation convention.
+ */
+function firstSeenFile(entry: string): string | undefined {
+  return FIRST_SEEN_PATTERN.exec(entry)?.[1]
+}
+
+/**
+ * `firstSeenFile` names a page free-form, per the `--first-seen` flag it
+ * comes from, so it may carry a directory prefix a lesson's own `file` does
+ * not. Comparing basenames is what keeps `lessons/0001-x.html` and
+ * `0001-x.html` resolving to the same lesson without a suffix match risking
+ * a false hit across two differently-prefixed filenames.
+ */
+function matchingLesson(
+  file: string,
+  metas: readonly LessonMeta[],
+): LessonMeta | undefined {
+  const basename = file.split('/').pop()
+  return metas.find((meta) => meta.file === basename)
+}
+
+interface GlossaryGroup {
+  readonly heading: string
+  readonly entries: readonly string[]
+}
+
+const OTHER_TERMS_HEADING = 'Other terms'
+
+/**
+ * Groups already-alphabetical glossary entries by the lesson their own
+ * "First seen in" sentence names, in lesson order. An entry naming a
+ * reference page instead, or carrying no citation at all, cannot be
+ * attributed to a lesson and trails in its own group, keeping the
+ * alphabetical order the source entries already carry.
+ */
+function groupGlossaryEntries(
+  entries: readonly string[],
+  metas: readonly LessonMeta[],
+): readonly GlossaryGroup[] {
+  const byLesson = new Map<string, string[]>()
+  const other: string[] = []
+
+  for (const entry of entries) {
+    const file = firstSeenFile(entry)
+    const lesson = file ? matchingLesson(file, metas) : undefined
+
+    if (lesson) {
+      const list = byLesson.get(lesson.file) ?? []
+      list.push(entry)
+      byLesson.set(lesson.file, list)
+    } else {
+      other.push(entry)
+    }
+  }
+
+  const groups: GlossaryGroup[] = []
+  for (const meta of metas) {
+    const list = byLesson.get(meta.file)
+    if (list) groups.push({ heading: meta.title, entries: list })
+  }
+  if (other.length > 0) {
+    groups.push({ heading: OTHER_TERMS_HEADING, entries: other })
+  }
+
+  return groups
+}
+
+function renderGlossaryGroup(group: GlossaryGroup): string {
+  const entries = group.entries.map(renderGlossaryEntry).join('')
+
+  return `<h3 class="gloss-group">${escapeHtml(group.heading)}</h3>${entries}`
+}
+
+function renderGlossarySection(
+  entries: readonly string[],
+  metas: readonly LessonMeta[],
+): string {
+  const rendered = groupGlossaryEntries(entries, metas)
+    .map(renderGlossaryGroup)
+    .join('')
 
   return `<h2>Glossary <span class="count">${entries.length}</span></h2>
 <input class="filter" type="search" id="gfilter" aria-label="Filter glossary terms" aria-controls="gloss" placeholder="term">
@@ -610,7 +704,7 @@ async function renderContentsPage(
     referenceRows
       ? `<h2>Reference pages</h2>\n<ul class="toc">${referenceRows}</ul>`
       : '',
-    renderGlossarySection(detail.glossary),
+    renderGlossarySection(detail.glossary, metas),
   ]
     .filter((section) => section !== '')
     .join('\n\n')

package/standards/glossary.md

@@ -58,6 +58,14 @@ A glossary failing these is non-conforming even when it satisfies every shape ru
 - Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
 - State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
 
+## Rendered grouping
+
+Applies to a rendered glossary page, never to the source file above, which stays the flat alphabetical list the `## Grouping` rules above govern.
+
+- Group a rendered glossary by the lesson its own "First seen in" citation names, ordered by lesson order, under a sub-heading naming the lesson's title rather than its filename.
+- Trail with an "Other terms" group holding any entry the citation cannot attribute to a lesson, whether it names a reference page instead or carries no citation at all. Keep it in the alphabetical order the source file already carries.
+- Keep the workspace-wide term filter matching against every group, and drop a group's own heading once filtering leaves nothing under it.
+
 ## Template
 
 ```markdown

package/standards/groundwork.md

@@ -156,7 +156,7 @@ A lean is weaker than the suggestion a plan file carries. It records the current
 ## Conventions
 
 - State a number with what it settles. The strongest sections are the ones where a measurement answers a named question and says so.
-- Route a finding that would change an existing standard or rule through `claude-intake`. Only a demonstrated failure changes one.
+- Route a finding that would change an existing standard or rule through `plan-intake`. Only a demonstrated failure changes one.
 - Let the file count follow the number of genuinely separable questions, not the importance of the topic. A large topic with one question is a small folder.
 
 ## Anti-patterns

package/standards/snippets.md

@@ -38,7 +38,7 @@ Overlapping a skill that does the same job is not disqualifying on its own. A sn
 ## Use patterns
 
 - Run-as-is: invoke and send immediately. The snippet is self-contained and needs no extra context.
-- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `claude-feature`, then add the feature name or extra constraints)
+- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `plan-feature`, then add the feature name or extra constraints)
 - Invoke-on-history: invoke after a discussion. The snippet uses prior conversation as implicit context with no additional input needed (e.g. invoke `claude-figma` after discussing a design).
 
 ## Authoring

package/standards/tasks.md

@@ -47,7 +47,7 @@ The handoff takes one file per session for the reason a task does. A single shar
 
 The catalog is the one reader that filters nothing, so it carries a row per sibling alongside the tasks. That is what a folder catalog is for, and the handoffs are what make it worth stating: a board accumulates one row per session that ever wrote one, with nothing pruning them. Anything reading the catalog as the backlog therefore does its own filtering, and a reader that takes every row as a task reports the handoffs as queued work.
 
-The `claude-tasks` skill creates and archives task files, and the archive carries the task's plan with it. `claude-docs` marks outcomes `[x]` in an existing file. Neither does the other's job.
+The `task-board` skill creates and archives task files, and the archive carries the task's plan with it. `docs-fold` marks outcomes `[x]` in an existing file. Neither does the other's job.
 
 ## Ordering
 
@@ -219,9 +219,9 @@ A project that archived plans before the folder nested under `.canon/plans/` hol
 
 One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
 
-`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, mirroring how `canon tasks pull-request` writes its own. `claude-feature` calls it right after the plan file lands, when an existing task names the feature, so the line is a mechanical write rather than hand-edited markdown.
+`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, mirroring how `canon tasks pull-request` writes its own. `plan-feature` calls it right after the plan file lands, when an existing task names the feature, so the line is a mechanical write rather than hand-edited markdown.
 
-`Groundwork:` points at `../groundwork/<slug>/`, the folder `claude-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
+`Groundwork:` points at `../groundwork/<slug>/`, the folder `plan-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
 
 `Intake:` points at `../intake/<slug>/`, the folder an intake pass fills. Use it rather than `Groundwork:`, because a groundwork track measures one question in depth while an intake dispositions many across a tree, and one key covering both loses which kind of pass produced the task. The line names the folder rather than an item inside it. A task routinely promotes several items at once, so an anchored line would name one and drop the rest, and the item numbers belong in that task's `## Findings`.
 

package/standards/teach.md

@@ -15,7 +15,7 @@ Governs a learning workspace under `.canon/teach/<nn>-<topic>/`: folder layout,
 
 Does not govern:
 
-- The frontmatter, entry shape, and ordering of the glossary the workspace holds: the `claude-teach` skill, which carries that reference
+- The frontmatter, entry shape, and ordering of the glossary the workspace holds: the `teach-workspace` skill, which carries that reference
 - 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`
@@ -113,7 +113,7 @@ Take the date and the rung from what the surface driving the workspace reports r
 
 ## GLOSSARY.md
 
-Required in every workspace, holding one entry per term the subject defines. The glossary reference the `canon:claude-teach` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
+Required in every workspace, holding one entry per term the subject defines. The glossary reference the `canon:teach-workspace` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
 
 Name the lesson or reference page a term first appears in as that reference requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.