@erclx/canon 4.111.0 → 4.113.0

package/assets/brand/mark.svg

@@ -0,0 +1,10 @@
+<!-- A bound ledger: two pages fanned open around a spine, drawn as three
+     solid masses rather than thin strokes, so the shape survives being
+     rendered at favicon size instead of averaging into grey. The 10-unit
+     gap between each page and the spine, against an 80-unit frame, is what
+     keeps the split a visible channel at 16px; a first draft at half that
+     gap closed into an unreadable blob at the same size. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
+  <path d="M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z" fill="currentColor" />
+  <rect x="44" y="15" width="12" height="70" rx="2" fill="currentColor" />
+</svg>

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

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

package/claude/skills/auto-ship/REQUIREMENT.md

@@ -21,6 +21,7 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 - Own the review receipt's lifetime, since this chain writes it, cites it in its own closing block, and is the only body that can read whether the step keeping it is still using it
 - Delegate the ship sequence to `git-ship` rather than restating it, and name only what this chain adds to it
 - Open the pull request as a draft before the continuous integration watch begins, since a pull request marked after it is mergeable for the length of the run
+- Prove the draft target's head is the current branch and its state is open before marking it, and stop with nothing marked on a mismatch, since the number is retyped between steps and a draft mark on a release pull request holds that release
 - Name the recovery for the stop it took, since the value of stopping is that the user knows where to resume
 
 ## Must not

package/claude/skills/auto-ship/SKILL.md

@@ -190,14 +190,23 @@ This chain owns the receipt's lifetime, which is what makes the Output block's c
 
 Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, memory capture, both doc syncs, staging, the commit grouping, the branch rename, the pull request, and the CI watch, along with the reason each step sits where it does. This step used to restate that list and the two drifted apart with nothing comparing them, so read the order there and never here.
 
-One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch, then read the flag back:
+One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch. Run it as one command, where the shell proves the target before the mark and reads the flag back after it:
 
 ```bash
+target=$(gh pr view <number> --json headRefName,state --jq '"\(.headRefName) \(.state)"') || exit 1
+if [ "$target" != "$(git branch --show-current) OPEN" ]; then
+  printf '❌ #%s reads "%s", not "%s OPEN". The draft mark was not written.\n' "<number>" "$target" "$(git branch --show-current)" >&2
+  exit 1
+fi
 gh pr ready --undo <number>
 gh pr view <number> --json isDraft
 ```
 
-Name the number `git-ship`'s pull request step returned on both calls rather than leaving either to resolve by branch. `${CLAUDE_SKILL_DIR}/../git-pr/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
+Name the number `git-ship`'s pull request step returned in every position rather than leaving any to resolve by branch. `${CLAUDE_SKILL_DIR}/../git-pr/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
+
+A refusal is a stop. Report the line the shell printed, then resolve the number from the `number=` and `head=` lines of `git-pr`'s output and re-run the command by hand. The comparison sits in the shell rather than in the session's reading of a printed value, which is the same split `git-pr`'s `assert_own_pr` makes, because the judgment that picked a wrong number is the one that would read the check.
+
+The number crosses from that step's output into a command this session types, which is the one place a number gets authored rather than derived. A number misread there, or inferred from the newest pull request in view, would draft a stranger's pull request. A release pull request is the worst such target, since the mark holds the release and this role may not lift it again.
 
 Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state. A `true` reports a draft. A `false` reports the pull request as opened ready and unsupervised, and the chain stops there. Never re-issue the undo on a disagreeing read, which fights whoever readied it instead of guarding anything.
 
@@ -243,3 +252,4 @@ Every stop point leaves recoverable state. The user resumes manually from the ap
 | Inherited review findings                  | Fix findings, run `/git-ship`                                                                                                                   |
 | Self-introduced finding survived           | Read the receipt for what the one repair pass left open, fix it, run `/git-ship`                                                                |
 | git-ship fails                             | Inspect hook or remote error, run again                                                                                                         |
+| Draft target is not this branch's          | Nothing was marked. Read the number and `head=` from `git-pr`'s output, confirm they match, then run the mark by hand                           |

package/claude/skills/canon-feedback/SKILL.md

@@ -5,7 +5,7 @@ description: Format a report about something broken, missing, or off in canon an
 
 # Canon feedback
 
-Format a `## Toolkit feedback` block from the current session, then open it as a GitHub issue labeled `feedback` on the toolkit repo. `canon-feedback-triage` reads that queue.
+Format a `## Toolkit feedback` block from the current session, then open it as a GitHub issue on the toolkit repo, labeled `feedback` plus the domain label its surface type names. `canon-feedback-triage` reads that queue.
 
 ## Guards
 
@@ -18,7 +18,7 @@ Format a `## Toolkit feedback` block from the current session, then open it as a
 From the conversation so far, identify:
 
 - Target project name or kind, never its full path. The path names a folder on one machine and says nothing a triage session can route on, where the project's own name does. Name a private project by its kind instead, such as `a Next.js app`, since the report leaves the machine.
-- Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI)
+- Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI). The type leads the `### Surface` field, ahead of the first comma, because the CLI picks the issue's domain labels from that text alone.
 - Specific toolkit file or name when the session cites one
 - Observed behavior
 - Expected behavior, or `unclear`
@@ -81,7 +81,7 @@ cat <<'EOF' | canon feedback --github
 EOF
 ```
 
-The CLI opens a GitHub issue labeled `feedback` on the toolkit repo and prints the issue URL, which this skill reports back on its own line. It needs `gh` authenticated. `git-issue` is not the route, since it files on the current repository and this report belongs on the toolkit's.
+The CLI opens a GitHub issue on the toolkit repo, labeled `feedback` and each domain label the surface type names, such as `skills` for a plugin skill, and prints the issue URL, which this skill reports back on its own line. It needs `gh` authenticated. `git-issue` is not the route, since it files on the current repository and this report belongs on the toolkit's.
 
 From a toolkit checkout, a call that produces no URL falls back to `.canon/feedback/feedback-<slug>-<ts>.md` and prints the reason on stderr. Say so in the same reply, naming the file and the reason, since a silent fallback leaves the report where nothing reads it. A target project has no such folder, so a failed call there prints the block in chat.
 

package/claude/skills/git-pr/REQUIREMENT.md

@@ -23,6 +23,8 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - Detect an open pull request and edit it in place, so a follow-up push keeps the body in sync instead of failing
 - Scope that detection to an open pull request on the current head and the default base, so neither a reused branch name nor a second base resolves the wrong one
 - Resolve the pull request once and reuse what that resolution returned, so the number recorded never depends on how a lookup ranks two pull requests sharing a head
+- Prove before every write to an existing pull request that its head is the current branch and its state is open, and refuse with nothing written on a mismatch, so a wrong number reaching a write never lands on another branch's pull request
+- Print the head branch beside the number, so a caller writing to the pull request later has a value to check the number against
 - Label from the paths the branch changed, against a map the project declares, so the label set belongs to the project rather than to the skill
 - Apply labels after the pull request exists, so a label the remote does not carry costs a warning rather than the pull request
 - Report a refused label, since a warning nothing surfaces leaves the run indistinguishable from one that labelled

package/claude/skills/git-pr/SKILL.md

@@ -135,23 +135,41 @@ This command reuses `.canon/tmp/pr/body.md`, which the pre-publish scan above al
 
 ```bash
 pr_labels="<comma-separated labels, empty when the map resolves to nothing>"
+head_branch=$(git branch --show-current)
 git push -u origin HEAD || exit 1
 base_branch=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
-pr_number=$(gh pr list --head "$(git branch --show-current)" --base "$base_branch" --state open --json number --jq '.[0].number // empty')
+assert_own_pr() {
+  target=$(gh pr view "$1" --json headRefName,state --jq '"\(.headRefName) \(.state)"') || exit 1
+  if [ "$target" != "$head_branch OPEN" ]; then
+    printf 'Refused: #%s reads "%s", not "%s OPEN". Nothing was written to it.\n' "$1" "$target" "$head_branch" >&2
+    exit 1
+  fi
+}
+pr_number=$(gh pr list --head "$head_branch" --base "$base_branch" --state open --json number --jq '.[0].number // empty')
 if [ -n "$pr_number" ]; then
+  assert_own_pr "$pr_number"
   pr_url=$(gh pr edit "$pr_number" --title "<title>" --body-file .canon/tmp/pr/body.md) || exit 1
 else
   pr_url=$(gh pr create --title "<title>" --body-file .canon/tmp/pr/body.md) || exit 1
   pr_number=${pr_url##*/}
+  assert_own_pr "$pr_number"
 fi
 if [ -n "$pr_labels" ]; then
   gh pr edit "$pr_number" --add-label "$pr_labels" >/dev/null ||
     printf 'Label apply failed. Create a missing label with: gh label create <name>\n' >&2
 fi
 rm -rf .canon/tmp/pr/body
-printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
+printf 'number=%s\nurl=%s\nhead=%s\n' "$pr_number" "$pr_url" "$head_branch"
 ```
 
+### Binding every write to this branch's pull request
+
+`assert_own_pr` runs ahead of both writes this command makes to a pull request that already exists, the title and body edit and the label edit. It reads the target's head branch and state and refuses unless they are this branch and `OPEN`. A refusal exits before anything is written, so a wrong number costs the run rather than a stranger's pull request. The function lives only inside this command, so the steps below that post comments or record the task are covered by taking `<number>` from this output rather than by the check itself.
+
+The check compares a number against a branch and never derives a number from one, so it adds no lookup of the kind `### Resolving the pull request` retired. It holds whichever way a wrong number arrives. A number a session retyped by hand, or inferred from the newest pull request in view, reads as a foreign head here and stops.
+
+The last output line carries `head=` so a caller relaying the number holds a branch to compare it against rather than a bare integer. A caller that writes to the pull request itself, such as a draft mark, runs the same comparison in the shell first, reading `gh pr view <number> --json headRefName,state` and refusing unless it matches `head` and `OPEN`.
+
 ### Find the UI checklist
 
 `ui-checklist` writes a visual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and the two steps below each skip their checklist half.
@@ -238,7 +256,7 @@ canon pr evidence <number> --preview <url> --json
 
 ### Record the number on the task
 
-Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
+Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. A final command that refused on a head mismatch printed no number, so this step writes nothing on that run. `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
 
 The task is the one whose `Plan:` line names the plan this branch implemented. Name that plan by its file, which is `.canon/plans/feature-<slug>.md` at the main worktree root with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. `plan-feature` writes the plan under the branch slug, so the two correspond on any branch that came through the plan-to-execute path. When the session already knows which plan it implemented, because a caller read it earlier in the chain, use that filename instead of re-deriving.
 

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

@@ -18,7 +18,7 @@ The shape of the workspace is fixed by `${CLAUDE_SKILL_DIR}/../../standards/teac
 - 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.
-- Carry the toolkit's favicon on every page this skill writes, index and lesson alike, in the `<head>` verbatim: `<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='10 10 80 80'%3E%3Cpath d='M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z' fill='rgb(224,114,75)' /%3E%3Crect x='44' y='15' width='12' height='70' rx='2' fill='rgb(224,114,75)' /%3E%3C/svg%3E" />`
+- Never write a favicon link by hand. `canon teach nav` puts the toolkit's icon on every page it generates and inside a lesson's `style` region, so a hand-written one in a lesson's `<head>` gives the page two.
 
 ## Step 0: let the CLI resolve the workspace root
 

package/docs/agents/teach.md

@@ -172,7 +172,9 @@ canon teach nav regular-expressions --json
 
 With no topic it rewrites every workspace. The teach-root listing is always rewritten regardless, since it reports on every workspace and a scoped run leaving it stale would be a second kind of drift this verb exists to end.
 
-A lesson carries its chrome as four marker pairs the authoring skill writes empty: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. This verb splices each one from the current workspace state, embedding the shared stylesheet and the script that settles the course panel before the page paints, rebuilding the course sidebar, the breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts, and leaves the authored `<h1>`, lede, body, and quiz between the header and the footnav untouched.
+A lesson carries its chrome as four marker pairs the authoring skill writes empty: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. This verb splices each one from the current workspace state, embedding the toolkit's favicon, the shared stylesheet, and the script that settles the course panel before the page paints, rebuilding the course sidebar, the breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts, and leaves the authored `<h1>`, lede, body, and quiz between the header and the footnav untouched.
+
+It also deletes the one icon link the authoring skill used to have a session write by hand into a lesson's `<head>`, matched as that exact string, so the page keeps only the icon the `style` region carries. Any other link an author wrote stays.
 
 A workspace carrying no `course.css` gets its stylesheet pair seeded first, so the contents page it links is never unstyled, and an existing `course.css` is never overwritten. The embedded copy drops the seed's `@import` line, which resolved against the lesson's own folder and never loaded anything.
 
@@ -196,6 +198,8 @@ No `canon teach` verb serves the workspace. `canon serve` does, taking the teach
 canon serve .canon/teach --entry 03-fde-system-design/index.html --json
 ```
 
+`canon teach list <topic>` ends its human output with this line for that workspace, with the teach folder written relative to the cwd, or absolute when it sits outside it, since `canon serve` resolves its directory against the cwd while the list verb reads the main worktree root. The JSON record carries no such field.
+
 It stays general rather than becoming `canon teach serve`, because nothing about serving a directory is specific to a learning workspace, and the same verb carries a slide render and a design preview.
 
 Read `url` off the record rather than building one from the port that was asked for. The verb walks forward past a port already in use, which is routine when a second workspace is already open, and the port it took is the one thing a composed URL gets wrong.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.111.0",
+  "version": "4.113.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -17,6 +17,7 @@
     "claude",
     "docs",
     "tsconfig.json",
+    "assets/brand/mark.svg",
     "!scripts/sandbox",
     "!scripts/eval",
     "!**/*.test.ts",
@@ -48,6 +49,8 @@
     "web:previews": "bun scripts/core/regen-web-previews.ts",
     "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",
     "web:gallery": "cd web && astro build --config gallery.config.mjs",
+    "web:card": "cd web && astro dev --config card.config.mjs",
+    "web:card:check": "PROJECT_ROOT=web bash tooling/astro/configs/scripts/check-card-exclusion.sh",
     "web:preview": "cd web && astro preview",
     "web:e2e": "cd web && playwright test"
   },

package/src/claude/skills-audit.ts

@@ -1,10 +1,6 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import {
-  type Frontmatter,
-  parseFrontmatter,
-  readField,
-} from '@/indexes/frontmatter'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -149,7 +145,7 @@ async function readSkill(
       : Promise.resolve(undefined),
   ])
 
-  const fields = readFields(body)
+  const fields = parseFrontmatter(body)
 
   return {
     rel: join(rel, folder),
@@ -162,19 +158,6 @@ async function readSkill(
   }
 }
 
-/**
- * Returns undefined rather than throwing on unparseable YAML, so one malformed
- * body reports as missing its required fields instead of ending the audit
- * before it reaches the rest of the corpus.
- */
-function readFields(body: string): Frontmatter | undefined {
-  try {
-    return parseFrontmatter(body)
-  } catch {
-    return undefined
-  }
-}
-
 /**
  * A key carrying an empty value declares nothing, so blank reads as absent
  * rather than as a name that disagrees with every folder.

package/src/commands/feedback-format.ts

@@ -89,6 +89,30 @@ export function deriveSlug(body: string): string {
   return slug || SLUG_FALLBACK
 }
 
+/**
+ * Each label must exist on the toolkit repository, because `gh issue create`
+ * refuses the whole issue on an unknown label rather than dropping it.
+ */
+const DOMAIN_LABELS: readonly { pattern: RegExp; label: string }[] = [
+  { pattern: /\bskills?\b/, label: 'skills' },
+  { pattern: /\b(?:cli)s?\b/, label: 'cli' },
+  { pattern: /\b(?:tooling|seeds?)\b/, label: 'tooling' },
+  { pattern: /\b(?:governance)s?\b/, label: 'governance' },
+  { pattern: /\bsnippets?\b/, label: 'snippets' },
+]
+
+/**
+ * Reads only the surface type, the text before the first comma, so a path or
+ * name after it never adds a label.
+ */
+export function deriveDomainLabels(body: string): string[] {
+  const type = (surfaceField(body) ?? '').split(',')[0]?.toLowerCase() ?? ''
+  const labels = DOMAIN_LABELS.filter(({ pattern }) => pattern.test(type)).map(
+    ({ label }) => label,
+  )
+  return [...new Set(labels)]
+}
+
 export function deriveTitle(body: string): string {
   const surface = surfaceField(body)
   const title = surface ? `feedback: ${surface}` : 'toolkit feedback'

package/src/commands/feedback.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import {
+  deriveDomainLabels,
   deriveSlug,
   deriveTitle,
   missingField,
@@ -107,7 +108,7 @@ export function register(program: Command): void {
         const result = await createGithubIssue({
           title: deriveTitle(body),
           body,
-          labels: ['feedback'],
+          labels: ['feedback', ...deriveDomainLabels(body)],
         })
         if (result.ok) {
           frameSuccess('canon feedback', result.url)

package/src/commands/teach.ts

@@ -1,4 +1,4 @@
-import { relative } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavOutcome, generateNav } from '@/teach/nav'
@@ -18,6 +18,7 @@ import {
   type TeachRefused,
   type Term,
   type TermOutcome,
+  teachDir,
   type WorkspaceSummary,
   writeStylesheet,
 } from '@/teach/workspace'
@@ -91,6 +92,18 @@ export function register(program: Command): void {
     .command('teach')
     .description('Manage learning workspaces in .canon/teach/')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Opening a workspace:',
+        '  canon serve .canon/teach --entry <nn>-<topic>/index.html',
+        '',
+        'canon teach list <topic> prints the exact line, with the teach folder',
+        'written from where you stand rather than as this literal.',
+        '',
+      ].join('\n'),
+    )
 
   teach
     .command('list')
@@ -118,6 +131,9 @@ export function register(program: Command): void {
         'A workspace not named NN-<topic> is still listed. It sorts last and',
         'moves no ordinal, since dropping it hides the folder needing a fix.',
         '',
+        'The human output ends with the canon serve line that opens a',
+        'workspace, a template with no topic and the exact line with one.',
+        '',
         'Examples:',
         '  canon teach list',
         '  canon teach list regular-expressions --json',
@@ -852,6 +868,22 @@ function describe(workspace: WorkspaceSummary): string {
   return `${workspace.slug}: ${workspace.lessons} lesson(s), ${workspace.records} record(s), ${workspace.reference} reference page(s), ${workspace.terms} term(s)`
 }
 
+/**
+ * `canon serve` resolves its folder against the caller's cwd, while the list
+ * verb reads the teach folder at the main worktree root, so the line carries
+ * the folder actually read. A literal `.canon/teach` serves an absent folder
+ * from a linked worktree.
+ */
+function serveLine(root: string, entry: string): string {
+  const dir = resolve(teachDir(root))
+  const fromCwd = relative(process.cwd(), dir)
+  const isOutsideCwd =
+    fromCwd === '..' || fromCwd.startsWith(`..${sep}`) || isAbsolute(fromCwd)
+  const printed = fromCwd === '' ? '.' : isOutsideCwd ? dir : fromCwd
+
+  return `canon serve ${printed} --entry ${entry}`
+}
+
 function reportList(
   outcome: ListOutcome,
   emitJson: boolean,
@@ -890,6 +922,12 @@ function reportList(
 
   logStep('Next ordinal')
   logInfo(outcome.next)
+
+  if (outcome.workspaces.length > 0) {
+    logStep('Open')
+    logInfo(serveLine(root, '<nn>-<topic>/index.html'))
+  }
+
   outro()
 
   return 0
@@ -940,6 +978,8 @@ function reportWorkspace(
     logWarn(`no ${workspace.missing.join(' and no ')}`)
   }
 
+  logStep('Open')
+  logInfo(serveLine(root, `${workspace.slug}/index.html`))
   outro()
 
   return 0

package/src/design/components.ts

@@ -291,7 +291,7 @@ body {
   color: var(--color-text-body);
   font-family: var(--teach-sans);
   font-size: var(--t3);
-  line-height: 1.62;
+  line-height: 1.55;
   -webkit-font-smoothing: antialiased;
 }
 
@@ -393,10 +393,9 @@ html.sb-shut .pane { border-left: 0; }
 
 .nav .lbl {
   display: block;
-  font-size: 0.6563rem;
+  font-size: var(--t6);
   font-weight: 700;
-  letter-spacing: 0.09em;
-  text-transform: uppercase;
+  letter-spacing: 0;
   color: var(--color-muted);
   margin-bottom: 0.15rem;
 }
@@ -991,6 +990,9 @@ const TEACH_ARTICLE: Component = {
     '--color-accent',
     '--teach-hand',
     '--teach-mono',
+    '--t1',
+    '--t2',
+    '--t3',
     '--t4',
     '--t5',
     '--t6',
@@ -998,8 +1000,8 @@ const TEACH_ARTICLE: Component = {
   rules: `/* ---- Type ---- */
 
 h1 {
-  font-size: 2.15rem;
-  line-height: 1.14;
+  font-size: var(--t1);
+  line-height: 1.1;
   font-weight: 800;
   letter-spacing: -0.022em;
   margin: 0 0 0.55rem;
@@ -1007,19 +1009,20 @@ h1 {
 }
 
 h2 {
-  font-size: 1.3rem;
+  font-size: var(--t2);
+  line-height: 1.3;
   font-weight: 700;
   letter-spacing: -0.012em;
   margin: 3rem 0 0.85rem;
 }
 
-h3 { font-size: 1.03rem; font-weight: 700; margin: 1.9rem 0 0.4rem; }
+h3 { font-size: var(--t3); line-height: 1.55; font-weight: 700; margin: 1.9rem 0 0.4rem; }
 
 p { margin: 0 0 1.15rem; }
 
 .lede {
-  font-size: 1.1875rem;
-  line-height: 1.5;
+  font-size: var(--t3);
+  line-height: 1.55;
   color: var(--color-text-secondary);
   margin-bottom: 2rem;
 }
@@ -1031,8 +1034,8 @@ em { font-style: italic; }
 /* ---- Panels ---- */
 
 .assumes, .progress {
-  font-size: 0.8438rem;
-  line-height: 1.7;
+  font-size: var(--t5);
+  line-height: 1.6;
   color: var(--color-text-secondary);
   background: var(--color-surface);
   border-radius: 7px;
@@ -1044,8 +1047,7 @@ em { font-style: italic; }
   display: block;
   color: var(--color-muted);
   font-weight: 700;
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
+  letter-spacing: 0;
   font-size: var(--t6);
   margin-bottom: 0.2rem;
 }
@@ -1063,7 +1065,7 @@ code {
 pre {
   font-family: var(--teach-mono);
   font-size: var(--t5);
-  line-height: 1.7;
+  line-height: 1.6;
   background: var(--color-surface);
   padding: 1.15rem 1.3rem;
   border-radius: 7px;
@@ -1084,7 +1086,7 @@ pre code { background: none; padding: 0; font-size: 1em; }
 
 .hard-label {
   font-family: var(--teach-hand);
-  font-size: 1.0625rem;
+  font-size: var(--t3);
   color: var(--color-accent);
   display: block;
   margin-bottom: 0.35rem;
@@ -1094,15 +1096,14 @@ pre code { background: none; padding: 0; font-size: 1em; }
 
 /* ---- Tables ---- */
 
-table { width: 100%; border-collapse: collapse; font-size: 0.875rem; margin: 0 0 1.5rem; }
+table { width: 100%; border-collapse: collapse; font-size: var(--t4); margin: 0 0 1.5rem; }
 th, td { text-align: right; padding: 0.55rem 0.7rem; border-bottom: 1px solid var(--color-border); }
 th:first-child, td:first-child { text-align: left; }
 
 th {
   font-weight: 700;
-  font-size: 0.75rem;
-  letter-spacing: 0.04em;
-  text-transform: uppercase;
+  font-size: var(--t5);
+  letter-spacing: 0;
   color: var(--color-muted);
   border-bottom-color: var(--color-border);
 }
@@ -1127,26 +1128,22 @@ tbody tr.mark td { background: var(--color-teach-accent-bg); }
 }
 
 .toc a:hover { background: var(--color-surface); }
-.toc .num { font-family: var(--teach-mono); font-size: var(--t5); color: var(--color-accent); }
-.toc b { font-size: 1.0625rem; font-weight: 700; letter-spacing: -0.012em; }
+.toc .num { font-family: var(--teach-mono); font-size: var(--t5); color: var(--color-muted); }
+.toc b { font-size: var(--t3); font-weight: 700; letter-spacing: -0.012em; }
 
 .toc .blurb {
   grid-column: 2;
   font-size: var(--t4);
-  line-height: 1.5;
+  line-height: 1.55;
   color: var(--color-text-secondary);
   margin-top: 0.1rem;
 }
 
-/* A dot and a word, not a pill. The jump menus already say written and
-   planned with a filled or hollow dot, so the bordered uppercase badge was a
-   second vocabulary for a fact the design system already had one for. Sentence
-   case and no tracking, per the UI copy rule. */
+/* A word, not a pill and not a dot. A mark reading the same on every live row
+   reports nothing, so the dot retired here as it did from the jump menus.
+   Sentence case and no tracking, per the UI copy rule. */
 .toc .state {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.42rem;
-  font-size: 0.75rem;
+  font-size: var(--t5);
   font-weight: 500;
   letter-spacing: 0;
   text-transform: none;
@@ -1154,24 +1151,10 @@ tbody tr.mark td { background: var(--color-teach-accent-bg); }
   white-space: nowrap;
 }
 
-.toc .state::before {
-  content: "";
-  width: 6px;
-  height: 6px;
-  border-radius: 99px;
-  background: var(--color-border);
-  flex: none;
-}
-
-.toc .state.done { color: var(--color-text-secondary); }
-.toc .state.done::before { background: var(--color-accent); }
-.toc .state.next { color: var(--color-text-secondary); }
-.toc .state.next::before { background: var(--color-accent); }
-
 /* A link leaving the page says so with a mark beside it rather than with a
    badge spelling out the sentence. */
 .toc .ext {
-  font-size: 0.875rem;
+  font-size: var(--t4);
   color: var(--color-muted);
   margin-left: 0.35rem;
 }
@@ -1182,7 +1165,7 @@ ol.succ {
   margin: 0 0 2.5rem;
   padding-left: 1.35rem;
   font-size: var(--t4);
-  line-height: 1.6;
+  line-height: 1.55;
   color: var(--color-text-secondary);
 }
 
@@ -1205,10 +1188,6 @@ ol.succ li { margin-bottom: 0.4rem; }
    accent. Suppressing it only where the token above replaces it. */
 :where(a, button, summary, input, .opt):focus:not(:focus-visible) { outline: none; }
 
-@media (max-width: 640px) {
-  body { font-size: 1.0625rem; }
-}
-
 /* The week plan. Its markup shipped with no rule matching any of its five
    classes, so it rendered as a run of inline spans with the ordinal, the
    title, the description, and the duration all touching. */
@@ -1238,7 +1217,7 @@ ol.succ li { margin-bottom: 0.4rem; }
 
 .road-t {
   font-family: var(--teach-mono);
-  font-size: 0.75rem;
+  font-size: var(--t5);
   color: var(--color-muted);
   white-space: nowrap;
 }
@@ -1273,6 +1252,7 @@ const TEACH_QUIZ: Component = {
     '--color-teach-accent-bg',
     '--t4',
     '--t5',
+    '--t6',
   ],
   rules: `/* ---- Quiz ---- */
 
@@ -1304,7 +1284,7 @@ const TEACH_QUIZ: Component = {
 .opt::before {
   content: attr(data-k);
   font-family: var(--teach-mono);
-  font-size: 0.7188rem;
+  font-size: var(--t6);
   color: var(--color-muted);
   border: 1px solid var(--color-border);
   border-radius: 5px;
@@ -1329,23 +1309,21 @@ const TEACH_QUIZ: Component = {
 }
 
 .opt[data-state="chosen"]::after {
-  content: "your answer";
+  content: "Your answer";
   margin-left: auto;
-  font-size: 0.6563rem;
+  font-size: var(--t6);
   font-weight: 700;
-  letter-spacing: 0.07em;
-  text-transform: uppercase;
+  letter-spacing: 0;
   color: var(--color-muted);
   align-self: center;
 }
 
 .opt[data-state="right"]::after {
-  content: "correct";
+  content: "Correct";
   margin-left: auto;
-  font-size: 0.6563rem;
+  font-size: var(--t6);
   font-weight: 700;
-  letter-spacing: 0.07em;
-  text-transform: uppercase;
+  letter-spacing: 0;
   color: var(--color-accent);
   align-self: center;
 }
@@ -1394,34 +1372,37 @@ const TEACH_GLOSSARY: Component = {
   ],
   rules: `/* ---- Glossary view, generated from the markdown source ---- */
 
-h2 .count {
-  font-family: var(--teach-mono);
-  font-size: 0.75rem;
-  font-weight: 400;
-  color: var(--color-muted);
-  border: 1px solid var(--color-border);
-  border-radius: 99px;
-  padding: 0.1rem 0.5rem;
-  margin-left: 0.5rem;
-  vertical-align: middle;
+/* No border, sitting on the page ground, with the count beside it. The border and the
+   reading surface are what made the control look like something to fill in,
+   and the count is what says it filters the list under it. */
+.filter-row {
+  display: flex;
+  align-items: baseline;
+  gap: 1rem;
+  margin: 0 0 1rem;
 }
 
 .filter {
-  width: 100%;
+  flex: 1;
+  min-width: 0;
   font-family: var(--teach-sans);
   font-size: var(--t4);
   color: var(--color-text-body);
-  background: var(--color-background);
-  border: 1px solid var(--color-border);
-  border-radius: 7px;
-  padding: 0.55rem 0.8rem;
-  margin: 0 0 1rem;
+  background: transparent;
+  border: 0;
+  padding: 0.3rem 0;
 }
 
-/* Scoped to pointer focus. Written as \`.filter:focus\` it outranked the
-   \`:where(...)\` focus token, whose specificity is zero, and the filter was the
-   one control on the page that a keyboard reached with no ring at all. */
-.filter:focus { border-color: var(--color-accent); }
+.filter-count {
+  font-family: var(--teach-mono);
+  font-size: var(--t5);
+  color: var(--color-muted);
+  white-space: nowrap;
+}
+
+/* The \`:where(...)\` focus token has zero specificity, so a \`.filter:focus\`
+   rule outranks it and leaves a keyboard reaching the control with no ring.
+   The ring stays the token's and only the pointer ring is dropped. */
 .filter:focus:not(:focus-visible) { outline: none; }
 .filter::placeholder { color: var(--color-muted); }
 
@@ -1469,8 +1450,7 @@ h2 .count {
   font-size: var(--t5);
   font-weight: 600;
   color: var(--color-muted);
-  text-transform: uppercase;
-  letter-spacing: 0.02em;
+  letter-spacing: 0;
 }
 
 .gloss-group:first-of-type { margin-top: 0; }
@@ -1489,7 +1469,7 @@ ol.succ {
   margin: 0 0 2.5rem;
   padding-left: 1.35rem;
   font-size: var(--t4);
-  line-height: 1.6;
+  line-height: 1.55;
   color: var(--color-text-secondary);
 }
 
@@ -1499,7 +1479,7 @@ ol.succ li { margin-bottom: 0.4rem; }
 /* A filter that matches nothing needs a way back, not just a sentence. */
 .gloss .empty .clear {
   font-family: var(--teach-sans);
-  font-size: 0.875rem;
+  font-size: var(--t4);
   color: var(--color-accent);
   background: none;
   border: 0;
@@ -1554,6 +1534,7 @@ const TEACH_REFERENCES: Component = {
     '--teach-mono',
     '--color-teach-accent-bg',
     '--t5',
+    '--t6',
   ],
   rules: `footer {
   margin-top: 4rem;
@@ -1568,7 +1549,7 @@ const TEACH_REFERENCES: Component = {
 
 sup.cite {
   font-family: var(--teach-mono);
-  font-size: 0.6875em;
+  font-size: var(--t6);
   line-height: 0;
   margin-left: 0.1em;
 }
@@ -1589,7 +1570,7 @@ ol.refs {
   padding: 0;
   margin: 0.9rem 0 1.1rem;
   font-size: var(--t5);
-  line-height: 1.55;
+  line-height: 1.6;
 }
 
 ol.refs li {

package/src/design/favicon.ts

@@ -31,3 +31,11 @@ export function renderFavicon(mark: string, colors: FaviconColors): string {
 </svg>
 `
 }
+
+/**
+ * The `<link rel="icon">` a page carries the rendered favicon in, inlined so a
+ * generated page needs no sibling file and no href that varies with its depth.
+ */
+export function faviconLink(svg: string): string {
+  return `<link rel="icon" href="data:image/svg+xml,${encodeURIComponent(svg)}">`
+}

package/src/design/tokens.ts

@@ -381,7 +381,7 @@ export const TOKENS: DesignTokens = {
   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 ships in six independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+    'The same mark ships in five independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`, which teach pages also take by rendering the live mark. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
   ].join('\n'),
 }
 

package/src/indexes/frontmatter.ts

@@ -11,12 +11,21 @@ export interface Frontmatter {
  * `raw` keeps the delimiters so an index can be rewritten with its own
  * frontmatter untouched, including comments and key order that a parse and
  * re-emit would lose.
+ *
+ * A block that will not parse reads as absent rather than throwing, so one
+ * malformed file reports through the path a caller already takes for a
+ * missing block instead of ending the caller's whole run.
  */
 export function parseFrontmatter(source: string): Frontmatter | undefined {
   const match = source.match(FRONTMATTER)
   if (!match) return undefined
 
-  const parsed = Bun.YAML.parse(match[1])
+  let parsed: unknown
+  try {
+    parsed = Bun.YAML.parse(match[1])
+  } catch {
+    return undefined
+  }
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     return undefined
   }

package/src/pr/evidence.ts

@@ -106,8 +106,10 @@ export async function groupEvidence(
   return { kind: 'read', states }
 }
 
+// The raw host serves nothing to a private repository's browser, while the
+// blob form redirects to the bytes carrying the viewer's session.
 function rawUrl(repo: string, sha: string, path: string): string {
-  return `https://raw.githubusercontent.com/${repo}/${sha}/${path}`
+  return `https://github.com/${repo}/blob/${sha}/${path}?raw=true`
 }
 
 export function evidenceMarker(head: string): string {

package/src/teach/nav.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import {
@@ -6,7 +6,9 @@ import {
   TEACH_STYLESHEET_COMPONENTS,
 } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
+import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import { PROJECT_ROOT } from '@/project-root'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
 import {
   listWorkspaces,
@@ -23,7 +25,33 @@ import {
   writeStylesheet,
 } from '@/teach/workspace'
 
-const FAVICON = `<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='10 10 80 80'%3E%3Cpath d='M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z' fill='rgb(224,114,75)' /%3E%3Crect x='44' y='15' width='12' height='70' rx='2' fill='rgb(224,114,75)' /%3E%3C/svg%3E" />`
+const BRAND_MARK = 'assets/brand/mark.svg'
+
+/**
+ * The link `teach-workspace` once had a session write by hand into every page.
+ * A lesson keeps whatever sits outside its marked regions, so the old icon
+ * would stay beside the spliced one. Matching the exact string the skill
+ * mandated removes it without touching a link an author chose on purpose.
+ */
+const HAND_WRITTEN_ICON = `<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='10 10 80 80'%3E%3Cpath d='M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z' fill='rgb(224,114,75)' /%3E%3Crect x='44' y='15' width='12' height='70' rx='2' fill='rgb(224,114,75)' /%3E%3C/svg%3E" />`
+
+function dropHandWrittenIcon(html: string): string {
+  return html
+    .split('\n')
+    .filter((line) => line.trim() !== HAND_WRITTEN_ICON)
+    .join('\n')
+    .replaceAll(HAND_WRITTEN_ICON, '')
+}
+
+/**
+ * Built from the brand mark and the favicon's own pair, the same two inputs
+ * `web/public/favicon.svg` is generated from, so every teach page carries the
+ * icon the landing page does rather than a copy of its own.
+ */
+function teachFavicon(): string {
+  const mark = readFileSync(join(PROJECT_ROOT, BRAND_MARK), 'utf8')
+  return faviconLink(renderFavicon(mark, FAVICON_COLORS))
+}
 
 /**
  * Narrower and steeper than the mark it replaces, with round caps and joins.
@@ -164,6 +192,7 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
 (function () {
   var input = document.getElementById("gfilter");
   var list = document.getElementById("gloss");
+  var count = document.getElementById("gloss-count");
   if (!input || !list) return;
   function updateGroups() {
     list.querySelectorAll(".gloss-group").forEach(function (heading) {
@@ -186,6 +215,10 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
     });
     list.classList.toggle("none", n === 0);
     updateGroups();
+    if (count) {
+      var total = list.querySelectorAll(".gterm").length;
+      count.textContent = (n === total ? total : n + " of " + total) + (total === 1 ? " term" : " terms");
+    }
   });
   var clear = list.querySelector(".clear");
   if (clear) {
@@ -657,7 +690,7 @@ function pageHead(
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
-${FAVICON}
+${teachFavicon()}
 ${style}
 ${headScript('index')}
 </head>
@@ -861,6 +894,12 @@ function renderGlossaryGroup(group: GlossaryGroup): string {
   return `<h3 class="gloss-group">${escapeHtml(group.heading)}</h3>${entries}`
 }
 
+function termCount(shown: number, total: number): string {
+  const noun = total === 1 ? 'term' : 'terms'
+
+  return shown === total ? `${total} ${noun}` : `${shown} of ${total} ${noun}`
+}
+
 function renderGlossarySection(
   entries: readonly string[],
   metas: readonly LessonMeta[],
@@ -869,8 +908,8 @@ function renderGlossarySection(
     .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">
+  return `<h2>Glossary</h2>
+<div class="filter-row"><input class="filter" type="search" id="gfilter" aria-label="Filter glossary terms" aria-controls="gloss" placeholder="Filter terms"><span class="filter-count" id="gloss-count" aria-live="polite">${termCount(entries.length, entries.length)}</span></div>
 <div class="gloss" id="gloss"><p class="empty">No term matches that. <button type="button" class="clear">Clear the filter</button></p>${rendered}</div>
 `
 }
@@ -912,7 +951,7 @@ function renderRootPage(workspaces: readonly WorkspaceSummary[]): string {
           ? 'Live'
           : 'Open'
       const blurb = `${workspace.lessons} lesson(s) &middot; ${workspace.reference} reference page(s) &middot; ${workspace.terms} term(s)`
-      const inner = `<span class="num">${ordinalOf(workspace)}</span><b>${escapeHtml(titleCase(workspace.topic))}</b><span class="state${state === 'Live' ? ' done' : ''}">${state}</span><span class="blurb">${blurb}</span>`
+      const inner = `<span class="num">${ordinalOf(workspace)}</span><b>${escapeHtml(titleCase(workspace.topic))}</b><span class="state">${state}</span><span class="blurb">${blurb}</span>`
 
       return href === undefined
         ? `<li class="soon"><a href="#" aria-disabled="true" tabindex="-1">${inner}</a></li>`
@@ -1011,7 +1050,7 @@ async function renderContentsPage(
   const lessonRows = metas
     .map(
       (meta, index) =>
-        `<li><a href="${TEACH_LESSONS}/${meta.file}"><span class="num">${String(index + 1).padStart(2, '0')}</span><b>${escapeHtml(meta.title)}</b><span class="state done">Written</span><span class="blurb">${escapeHtml(meta.lede)}</span></a></li>`,
+        `<li><a href="${TEACH_LESSONS}/${meta.file}"><span class="num">${String(index + 1).padStart(2, '0')}</span><b>${escapeHtml(meta.title)}</b><span class="blurb">${escapeHtml(meta.lede)}</span></a></li>`,
     )
     .join('')
 
@@ -1125,7 +1164,7 @@ async function rewriteLesson(
 ): Promise<LessonRewritten | LessonRefused> {
   const file = metas[index].file
   const path = join(root, detail.path, TEACH_LESSONS, file)
-  let html = await readFile(path, 'utf8')
+  let html = dropHandWrittenIcon(await readFile(path, 'utf8'))
 
   const teachPrefix = '../../'
   const workspacePrefix = '../'
@@ -1174,11 +1213,12 @@ async function rewriteLesson(
   const regions: ReadonlyArray<readonly [Region, string]> = [
     // The stepper follows the workspace stylesheet so it wins the cascade at
     // equal specificity, which is what reaches a workspace seeded before it.
-    // The head script settles the panel before first paint, so it rides in the
-    // one region that sits inside `<head>`.
+    // The icon and the head script both belong in `<head>`, so they ride in the
+    // one region that sits there rather than a fifth marker every seeded
+    // lesson would lack.
     [
       'style',
-      `<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>\n${headScript('lesson')}`,
+      `${teachFavicon()}\n<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>\n${headScript('lesson')}`,
     ],
     ['header', header],
     ['footnav', `${renderFootNav(metas, index)}\n${PANE_CLOSE}`],

package/src/teach/workspace.ts

@@ -579,8 +579,8 @@ function missionText(
 
   return [
     '---',
-    `title: ${title}`,
-    `description: ${request.subject}`,
+    `title: ${yamlValue(title)}`,
+    `description: ${yamlValue(request.subject)}`,
     `date: ${date}`,
     '---',
     '',
@@ -606,8 +606,8 @@ function missionText(
 function resourcesText(title: string): string {
   return [
     '---',
-    `title: Sources for ${title}`,
-    `description: Sources read for ${title}, and leads found but not opened`,
+    `title: ${yamlValue(`Sources for ${title}`)}`,
+    `description: ${yamlValue(`Sources read for ${title}, and leads found but not opened`)}`,
     '---',
     '',
     `# Sources for ${title}`,
@@ -628,8 +628,8 @@ function resourcesText(title: string): string {
 function glossaryText(title: string): string {
   return [
     '---',
-    `title: Glossary for ${title}`,
-    `description: Terms ${title} defines, one entry each`,
+    `title: ${yamlValue(`Glossary for ${title}`)}`,
+    `description: ${yamlValue(`Terms ${title} defines, one entry each`)}`,
     '---',
     '',
     `# Glossary for ${title}`,
@@ -641,6 +641,14 @@ function glossaryText(title: string): string {
   ].join('\n')
 }
 
+/**
+ * Serializes a frontmatter value, quoting only what YAML would otherwise read
+ * as something other than the string, so a plain title stays byte-identical.
+ */
+function yamlValue(value: string): string {
+  return Bun.YAML.stringify(value)
+}
+
 /** Today as `YYYY-MM-DD`, which is the one field the mission dates. */
 function today(): string {
   return new Date().toISOString().slice(0, DATE_LENGTH)

package/tooling/base/seeds/cspell.json

@@ -16,5 +16,5 @@
     }
   ],
   "dictionaries": ["project-terms", "tech-stack"],
-  "ignorePaths": [".cspell/**", ".git/**"]
+  "ignorePaths": [".cspell/**", ".git/**", ".claude/rules/canon/**"]
 }

package/tooling/claude/seeds/.claude/hooks/silent-turn.sh

@@ -49,19 +49,18 @@ paths=$(tail -n +"$line_start" "$transcript_path" | jq -r '
 
 # Two written paths can share a basename, and a bare basename match would then
 # read one mention as covering both. Counting first is what lets a collision
-# fall back to the full path, which the ordinary case never needs.
-declare -A base_count
-while IFS= read -r path; do
+# fall back to the full path, which the ordinary case never needs. The count
+# avoids an associative array, since macOS ships bash 3.2.
+colliding=$(while IFS= read -r path; do
   [ -n "$path" ] || continue
-  base=$(basename "$path")
-  base_count["$base"]=$((${base_count["$base"]:-0} + 1))
-done <<<"$paths"
+  printf '%s\n' "${path##*/}"
+done <<<"$paths" | sort | uniq -d)
 
 unmentioned=()
 while IFS= read -r path; do
   [ -n "$path" ] || continue
-  base=$(basename "$path")
-  if [ "${base_count[$base]}" -gt 1 ]; then
+  base=${path##*/}
+  if [ -n "$colliding" ] && printf '%s\n' "$colliding" | grep -Fxq -- "$base"; then
     needle="$path"
   else
     needle="$base"

package/tooling/nextjs/configs/vitest.config.ts

@@ -5,7 +5,7 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, 'src'),
+      '@': path.resolve(import.meta.dirname, 'src'),
     },
   },
   test: {

package/tooling/python/manifest.toml

@@ -2,7 +2,7 @@
 name = "python"
 extends = "base"
 runtime = "uv"
-scaffold = "uv init --app {{name}}"
+scaffold = "uv init --package {{name}}"
 
 [scripts]
 "lint" = "uv run ruff check . && uv run ruff format --check ."

package/tooling/python/reference.md

@@ -10,14 +10,13 @@ Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coverage
 
 ## Scaffold checklist
 
-1. Scaffold with `uv init --app <name>`. This creates `pyproject.toml`, `.python-version` pinned to 3.14, `src/<name>/`, and a starter `main.py`. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
+1. Scaffold with `uv init --package <name>`. This creates `pyproject.toml` with a `uv_build` backend, `.python-version` pinned to 3.14, and `src/<name with underscores>/__init__.py` holding an annotated `def main() -> None:`, so source lands under `src/` where `mypy.ini`, `pytest.ini`, and `.coveragerc` look for it. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
 2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`. Without this the sync drops base configs but skips the dep install, since `resolve_missing_deps` short-circuits when `package.json` is absent.
 3. Install base tooling: `canon tooling sync base . --write`
 4. Install python tooling: `canon tooling sync python . --write`
 5. Install Python tooling deps: `uv add --dev ruff mypy pytest pytest-cov`. v1 of this stack does not declare these in `[dependencies.dev]` because manifest injection hardcodes `bun add -D`, which can not install Python packages. Until the injector branches on `runtime`, this step is manual.
 6. Sync the lockfile and create the venv: `uv sync`.
-7. Annotate `main()` in the scaffold-generated `main.py` with `-> None`. `uv init --app` ships an unannotated `main()` that fails strict mypy on the first run.
-8. Run `bun run lint:fix` then `bun run check`.
+7. Run `bun run lint:fix` then `bun run check`.
 
 The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest` collects at least one test on first run, so `bun run test:run` exits 0 instead of the empty-collection exit code 5. Delete or replace the smoke test with real tests.
 
@@ -27,7 +26,7 @@ The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest`
 - `mypy.ini`: strict mode, `python_version = 3.14`, `mypy_path = src`, excludes `tests/` and `docs/`.
 - `pytest.ini`: tests live under `tests/`, source under `src/`.
 - `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
-- `.python-version`: pinned to `3.14` to match `uv init --app` defaults.
+- `.python-version`: pinned to `3.14` to match `uv init` defaults.
 - `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases.
 
 ## Hybrid project shape

package/tooling/vite-react/configs/vite.config.ts

@@ -9,7 +9,7 @@ export default defineConfig({
   plugins: [react(), tailwindcss()],
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, './src'),
+      '@': path.resolve(import.meta.dirname, './src'),
     },
   },
   base: process.env.VITE_BASE_URL ?? '/',