@erclx/canon 4.112.0 → 4.114.0

package/src/records/backup.ts

@@ -1,8 +1,9 @@
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, lstatSync, readdirSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
-import { RECORD_ROOTS, recordRoot } from '@/record-root'
+import { RECORD_ROOTS, recordRoot, SCRATCH } from '@/record-root'
+import { type BlockedPath, guardPayload } from '@/records/push-guard'
 
 /**
  * The legacy `.claude`-root allowlist, read only when a project has not moved
@@ -81,6 +82,11 @@ const RECORDS_GIT_NAME = '.records.git'
  * every entry already keeps a pull's `README.md` out, so this is the one name
  * that still has to be said: without it a listing would stage the history
  * into itself.
+ *
+ * The list bounds the records index as well as the disk. `scopedFolders`
+ * filters the names the index tracks through `isExcluded`, so a name an older
+ * binary committed is removed from the history once rather than re-staged on
+ * every push by the `-f` that carries the payload.
  */
 export const EXCLUDED_ENTRIES = [
   'tmp',
@@ -88,6 +94,20 @@ export const EXCLUDED_ENTRIES = [
   RECORDS_GIT_NAME,
 ] as const
 
+/**
+ * Whether a top-level name stays out of every push, at either root.
+ *
+ * `SCRATCH` is the legacy `.tmp` spelling, which a records index opened before
+ * the move can still carry and which `EXCLUDED_ENTRIES` names at its `.canon`
+ * spelling only.
+ */
+function isExcluded(name: string): boolean {
+  return (
+    name === SCRATCH ||
+    EXCLUDED_ENTRIES.includes(name as (typeof EXCLUDED_ENTRIES)[number])
+  )
+}
+
 /**
  * The record folders sitting at `dir` right now, at either root spelling.
  *
@@ -112,10 +132,7 @@ function foldersAt(dir: string): string[] {
   return entries
     .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
-    .filter(
-      (name) =>
-        !EXCLUDED_ENTRIES.includes(name as (typeof EXCLUDED_ENTRIES)[number]),
-    )
+    .filter((name) => !isExcluded(name))
 }
 
 /**
@@ -197,6 +214,7 @@ export const BACKUP_REFUSALS = [
   'no-remote-records',
   'local-changes',
   'local-ahead',
+  'unsafe-payload',
   'git-failed',
 ] as const
 
@@ -206,6 +224,8 @@ export interface BackupRefused {
   readonly ok: false
   readonly reason: BackupRefusal
   readonly message: string
+  /** Every pending path the payload guard refused, carried on `unsafe-payload` only. */
+  readonly blocked?: readonly BlockedPath[]
 }
 
 export interface PushReport {
@@ -214,6 +234,10 @@ export interface PushReport {
   readonly folders: readonly string[]
   /** A folder in scope this push found on disk but the records index had never tracked. */
   readonly firstSeen: readonly string[]
+  /** Every file this push stages that the records history has never carried. */
+  readonly added: readonly string[]
+  /** An excluded name the records index still tracked, removed from the history going forward. */
+  readonly dropped: readonly string[]
   readonly changed: number
   readonly commit?: string
   readonly pushed: boolean
@@ -450,10 +474,14 @@ function refuseSplitRoots(root: string): BackupRefused | undefined {
   )
 }
 
-/** A pathspec-safe subset, plus which of it never entered the records index before. */
+/**
+ * A pathspec-safe subset, which of it never entered the records index before,
+ * and which excluded names the index still tracks.
+ */
 interface FolderScope {
   readonly scope: readonly string[]
   readonly firstSeen: readonly string[]
+  readonly dropped: readonly string[]
 }
 
 /**
@@ -476,12 +504,19 @@ interface FolderScope {
  * tracked, which is the read a caller reports rather than acts on: a folder
  * `.canon` picked up that should have been excluded is visible in the push
  * report instead of entering the payload silently.
+ *
+ * The index half passes through `isExcluded` before the union, since the index
+ * is the one side an excluded name can still reach the pathspec through. A
+ * name it drops is returned as `dropped` rather than silently forgotten, so the
+ * push can remove it from the history once and say so.
  */
 async function scopedFolders(root: string): Promise<FolderScope> {
   const tracked = await records(root, ['ls-files'])
-  const indexed = new Set(
+  const everIndexed = new Set(
     tracked.ok ? tracked.text.split('\n').filter(Boolean).map(topSegment) : [],
   )
+  const indexed = new Set([...everIndexed].filter((name) => !isExcluded(name)))
+  const dropped = [...everIndexed].filter(isExcluded).sort()
 
   const present = new Set(foldersAt(workTree(root)))
   const retired = RETIRED_FOLDERS.filter(
@@ -492,7 +527,7 @@ async function scopedFolders(root: string): Promise<FolderScope> {
     (folder) => present.has(folder) && !indexed.has(folder),
   )
 
-  return { scope, firstSeen }
+  return { scope, firstSeen, dropped }
 }
 
 function topSegment(path: string): string {
@@ -531,12 +566,105 @@ function countLines(text: string): number {
   return text.split('\n').filter(Boolean).length
 }
 
+function splitNul(text: string): string[] {
+  return text.split('\0').filter(Boolean)
+}
+
+/**
+ * The files `add -A -f` is about to stage from `scope`, split into those the
+ * history has never carried and every pending one.
+ *
+ * `ls-files -o` without `--exclude-standard` lists ignored files too, which is
+ * what `-f` stages. `-m` also lists a deleted file and `-o` lists an embedded
+ * repository as a `dir/` entry, so both are filtered down to regular files,
+ * which is all a payload check has bytes to read.
+ */
+async function pendingFiles(
+  root: string,
+  scope: readonly string[],
+): Promise<{ added: string[]; pending: string[] } | BackupRefused> {
+  if (scope.length === 0) return { added: [], pending: [] }
+
+  const [others, modified] = await Promise.all([
+    records(root, ['ls-files', '-z', '-o', '--', ...scope]),
+    records(root, ['ls-files', '-z', '-m', '--', ...scope]),
+  ])
+  if (!others.ok) return failed('ls-files', others)
+  if (!modified.ok) return failed('ls-files', modified)
+
+  const tree = workTree(root)
+  const isRegularFile = (path: string): boolean => {
+    try {
+      return lstatSync(join(tree, path)).isFile()
+    } catch {
+      return false
+    }
+  }
+
+  const added = splitNul(others.text).filter(isRegularFile).sort()
+  const pending = [
+    ...new Set([...added, ...splitNul(modified.text).filter(isRegularFile)]),
+  ].sort()
+
+  return { added, pending }
+}
+
+function refuseBlocked(blocked: readonly BlockedPath[]): BackupRefused {
+  return {
+    ...refuse(
+      'unsafe-payload',
+      [
+        `${blocked.length} record(s) cannot be backed up, so nothing was staged or pushed:`,
+        ...blocked.map(
+          (finding) =>
+            `  ${finding.path} (${finding.cause}: ${finding.detail})`,
+        ),
+        'Move each out of the record folders, such as into .canon/tmp/, or remove the credential, then push again.',
+      ].join('\n'),
+    ),
+    blocked,
+  }
+}
+
+/**
+ * Puts HEAD and the index back where they stood before this run committed.
+ *
+ * A mixed reset to the recorded HEAD rather than `reset --soft HEAD~1`. A soft
+ * reset leaves a dropped name's deletion staged while the next run's index read
+ * no longer lists the name, so that run's diff never sees the deletion and it
+ * is never committed. The recorded HEAD also covers the root commit, where
+ * `HEAD~1` does not exist and only removing the ref restores an unborn branch.
+ *
+ * Returns an error sentence when the undo itself failed, so the caller appends
+ * it rather than reporting a clean history that is not.
+ */
+async function undoCommit(
+  root: string,
+  priorHead: string,
+): Promise<string | undefined> {
+  if (priorHead.length > 0) {
+    const reset = await records(root, ['reset', '--quiet', priorHead])
+    return reset.ok ? undefined : `Undoing it failed: ${reset.stderr}.`
+  }
+
+  const unref = await records(root, ['update-ref', '-d', 'HEAD'])
+  if (!unref.ok) return `Undoing it failed: ${unref.stderr}.`
+  const reset = await records(root, ['reset', '--quiet'])
+  return reset.ok ? undefined : `Undoing it failed: ${reset.stderr}.`
+}
+
 /**
  * Stages the backed folders, commits when any of them changed, and pushes.
  *
- * The push runs whether or not this call committed, because a previous run can
- * have committed and then failed to reach the network. Skipping it would leave
- * that commit on one disk, which is the state the whole verb exists to end.
+ * The payload guard reads every pending file ahead of the stage, so a refusal
+ * leaves the index and the object store exactly as it found them. It reads what
+ * this run would add, never a commit already in the history.
+ *
+ * The push runs whether or not this call committed, because an older binary
+ * can have committed and then failed to reach the network. Skipping it would
+ * leave that commit on one disk, which is the state the whole verb exists to
+ * end. A commit this call made is undone when the push fails, so a remote that
+ * rejects the payload is not handed the same commit again on every later run.
  */
 export async function pushRecords(root: string): Promise<PushOutcome> {
   const split = refuseSplitRoots(root)
@@ -546,27 +674,56 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   const remote = await resolveRemote(root, enclosing)
   if (typeof remote !== 'string') return remote
 
-  const { scope, firstSeen } = await scopedFolders(root)
+  const { scope, firstSeen, dropped } = await scopedFolders(root)
+
+  const files = await pendingFiles(root, scope)
+  if ('ok' in files) return files
+
+  const blocked = await guardPayload(workTree(root), files.pending)
+  if (blocked.length > 0) return refuseBlocked(blocked)
 
   if (scope.length > 0) {
     // `-f` is what carries the payload: every backed folder is ignored by the
     // enclosing repository, and the pathspecs are the whole list, so nothing
-    // outside them can enter the index however the ignore rules read.
+    // outside them can enter the index however the ignore rules read. An
+    // excluded name never reaches the list, whatever the records index holds.
     const staged = await records(root, ['add', '-A', '-f', '--', ...scope])
     if (!staged.ok) return failed('add', staged)
   }
 
+  if (dropped.length > 0) {
+    const removed = await records(root, [
+      'rm',
+      '-r',
+      '--cached',
+      '--quiet',
+      '--',
+      ...dropped,
+    ])
+    if (!removed.ok) return failed('rm', removed)
+  }
+
+  // Scope alone would miss the dropped deletions, which sit outside it.
   const diff = await records(root, [
     'diff',
     '--cached',
     '--name-only',
     '--',
     ...scope,
+    ...dropped,
   ])
   if (!diff.ok) return failed('diff', diff)
 
   const changed = countLines(diff.text)
 
+  const prior = await records(root, [
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    'HEAD',
+  ])
+  const priorHead = prior.ok ? prior.text : ''
+
   if (changed > 0) {
     const stamp = new Date().toISOString().replace('T', ' ').slice(0, 16)
     const commit = await records(root, [
@@ -579,11 +736,17 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
     if (!commit.ok) return failed('commit', commit)
   }
 
-  const folders = presentFolders(root)
+  const report = {
+    ok: true,
+    root,
+    folders: presentFolders(root),
+    firstSeen,
+    added: files.added,
+    dropped,
+    changed,
+  } as const
   const head = await records(root, ['rev-parse', '--short', 'HEAD'])
-  if (!head.ok) {
-    return { ok: true, root, folders, firstSeen, changed, pushed: false }
-  }
+  if (!head.ok) return { ...report, pushed: false }
 
   const branch = await projectBranch(root, enclosing)
   const pushed = await records(root, [
@@ -591,17 +754,24 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
     'origin',
     `HEAD:refs/heads/${branch}`,
   ])
-  if (!pushed.ok) return failed('push', pushed)
+  if (!pushed.ok) {
+    const refused = failed('push', pushed)
+    if (changed === 0) return refused
 
-  return {
-    ok: true,
-    root,
-    folders,
-    firstSeen,
-    changed,
-    commit: head.text,
-    pushed: true,
+    const undoError = await undoCommit(root, priorHead)
+    return refuse(
+      'git-failed',
+      [
+        refused.message,
+        'The commit this run made was undone, and the records are still on disk.',
+        undoError,
+      ]
+        .filter(Boolean)
+        .join(' '),
+    )
   }
+
+  return { ...report, commit: head.text, pushed: true }
 }
 
 /**

package/src/records/push-guard.ts

@@ -0,0 +1,71 @@
+import { lstat, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { isBinary } from '@/binary'
+import { scanText } from '@/secrets/scan'
+
+/**
+ * The largest single record a push carries, in bytes.
+ *
+ * A constant rather than a flag. The largest record measured in this
+ * repository is a 6.7 MB git pack under a groundwork fixture and GitHub
+ * rejects a blob at 100 MB, so this sits well clear of both, and an override
+ * is one nobody remembers to pass the first time a backup tarball lands in a
+ * record folder.
+ */
+export const MAX_RECORD_BYTES = 25 * 1024 * 1024
+
+export interface BlockedPath {
+  readonly path: string
+  readonly cause: 'oversized' | 'credential'
+  /** A size or `<label> at line <n>`, never the matched value or a preview of it. */
+  readonly detail: string
+}
+
+function megabytes(bytes: number): string {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * Every pending path a push must not carry, in the order given.
+ *
+ * Reads the size off `lstat` first so an oversized file is never opened, and
+ * skips anything that is not a regular file, since `add` stages a symlink as
+ * its target path rather than the bytes it points at. The credential half is
+ * `scanText` unchanged, so the patterns and the `canon-allow-secret` marker
+ * answer here exactly as they do in `canon secrets scan`.
+ */
+export async function guardPayload(
+  tree: string,
+  paths: readonly string[],
+): Promise<BlockedPath[]> {
+  const blocked: BlockedPath[] = []
+
+  for (const path of paths) {
+    const full = join(tree, path)
+    const stats = await lstat(full).catch(() => undefined)
+    if (!stats?.isFile()) continue
+
+    if (stats.size > MAX_RECORD_BYTES) {
+      blocked.push({
+        path,
+        cause: 'oversized',
+        detail: `${megabytes(stats.size)}, over the ${megabytes(MAX_RECORD_BYTES)} ceiling`,
+      })
+      continue
+    }
+
+    const text = await readFile(full, 'utf8').catch(() => undefined)
+    if (text === undefined || isBinary(text)) continue
+
+    const [first] = scanText(path, text)
+    if (first) {
+      blocked.push({
+        path,
+        cause: 'credential',
+        detail: `${first.label} at line ${first.line}`,
+      })
+    }
+  }
+
+  return blocked
+}

package/src/teach/nav.ts

@@ -18,6 +18,7 @@ import {
   TEACH_MISSION,
   TEACH_REFERENCE,
   TEACH_STYLESHEET,
+  TEACH_STYLESHEET_BASE,
   teachDir,
   type TeachRefused,
   type WorkspaceDetail,
@@ -35,12 +36,23 @@ const BRAND_MARK = 'assets/brand/mark.svg'
  */
 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, '')
+/**
+ * The stylesheet link lessons used to carry by hand outside every region. The
+ * `style` region now links the base sheet itself, so keeping this one would
+ * load the base twice.
+ */
+const HAND_WRITTEN_STYLESHEET = `<link rel="stylesheet" href="../${TEACH_ASSETS}/${TEACH_STYLESHEET}" />`
+
+const HAND_WRITTEN_HEAD = [HAND_WRITTEN_ICON, HAND_WRITTEN_STYLESHEET]
+
+function dropHandWrittenHead(html: string): string {
+  return HAND_WRITTEN_HEAD.reduce(
+    (text, link) => text.replaceAll(link, ''),
+    html
+      .split('\n')
+      .filter((line) => !HAND_WRITTEN_HEAD.includes(line.trim()))
+      .join('\n'),
+  )
 }
 
 /**
@@ -504,6 +516,11 @@ function titleCase(slug: string): string {
   ].join(' ')
 }
 
+/** The mission's own title, falling back to the slug where it names none. */
+function workspaceLabel(workspace: WorkspaceSummary): string {
+  return workspace.title ?? titleCase(workspace.topic)
+}
+
 interface JumpEntry {
   readonly ordinal: string
   readonly label: string
@@ -629,7 +646,7 @@ function renderSidebar(sidebar: Sidebar): string {
 
   return `<aside class="sb">
   <div class="sb-top">
-    <details class="sb-ws" name="mast"><summary><span class="ws-name">${escapeHtml(sidebar.heading)}</span><span class="car">${CARET}</span></summary><div class="sb-wl"><ul class="jump-list">${renderJumpList(sidebar.switcher)}</ul></div></details>
+    <details class="sb-ws" name="mast"><summary><span class="ws-name" title="${escapeHtml(sidebar.heading)}">${escapeHtml(sidebar.heading)}</span><span class="car">${CARET}</span></summary><div class="sb-wl"><ul class="jump-list">${renderJumpList(sidebar.switcher)}</ul></div></details>
   </div>
   <div class="sb-scroll">
     <div class="sb-meta">${escapeHtml(sidebar.meta)}</div>
@@ -724,7 +741,7 @@ function workspaceJumpEntries(
 ): JumpEntry[] {
   return workspaces.map((workspace) => ({
     ordinal: ordinalOf(workspace),
-    label: titleCase(workspace.topic),
+    label: workspaceLabel(workspace),
     href: hrefForWorkspace(workspace, prefix),
     at: workspace.slug === currentSlug,
     trailing: String(workspace.lessons),
@@ -935,7 +952,7 @@ function renderRootPage(workspaces: readonly WorkspaceSummary[]): string {
     meta: `${workspaces.length} workspace${workspaces.length === 1 ? '' : 's'}`,
     items: workspaces.map((workspace) => ({
       ordinal: ordinalOf(workspace),
-      label: titleCase(workspace.topic),
+      label: workspaceLabel(workspace),
       href: hrefForWorkspace(workspace, '') ?? '#',
       at: false,
     })),
@@ -951,7 +968,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}</span><span class="blurb">${blurb}</span>`
+      const inner = `<span class="num">${ordinalOf(workspace)}</span><b>${escapeHtml(workspaceLabel(workspace))}</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>`
@@ -1014,7 +1031,7 @@ async function renderContentsPage(
       )
     : undefined
 
-  const title = detail.title ?? titleCase(detail.topic)
+  const title = workspaceLabel(detail)
 
   const segments: CrumbSegment[] = [
     {
@@ -1026,7 +1043,7 @@ async function renderContentsPage(
       },
     },
     {
-      label: titleCase(detail.topic),
+      label: workspaceLabel(detail),
       jump: {
         ariaLabel: 'Jump to a lesson',
         entries: lessonJumpEntries(metas, '', undefined),
@@ -1035,7 +1052,7 @@ async function renderContentsPage(
   ]
 
   const sidebar: Sidebar = {
-    heading: titleCase(detail.topic),
+    heading: workspaceLabel(detail),
     switcher: workspaceJumpEntries(workspaces, '../', detail.slug),
     meta: `${metas.length} lesson${metas.length === 1 ? '' : 's'}`,
     items: metas.map((meta, index) => ({
@@ -1139,21 +1156,44 @@ interface LessonRefused {
   readonly missing: Region
 }
 
-/**
- * Splices the four chrome regions into one lesson file, in a fixed order so a
- * missing marker is always reported against the same region a session can
- * check first. Nothing is written when any region is missing, which is what
- * keeps a partially-spliced file off disk.
- */
 /**
  * A lesson embeds the workspace stylesheet, and an `@import` resolves against
  * the lesson's own folder there rather than the assets folder, so it never
- * loaded anything. The base sheet reaches the page through the `<link>`.
+ * loaded anything. The base sheet reaches the page through the `<link>` the
+ * `style` region carries ahead of the embedded rules.
  */
 function stripImports(css: string): string {
   return css.replace(/^@import[^;]*;[ \t]*\n?/gm, '')
 }
 
+const HEADER_CLOSE = '<!-- /canon:teach:header -->'
+const FOOTNAV_OPEN = '<!-- canon:teach:footnav -->'
+
+/**
+ * The authored body between the header and footnav regions, wrapped in
+ * `<main>` when it holds none. The skill has a session write the body bare,
+ * and the column width hangs off `main`. A body already holding one is left
+ * alone, which keeps a second run byte-identical.
+ */
+function wrapMain(html: string): string {
+  const start = html.indexOf(HEADER_CLOSE)
+  const end = html.indexOf(FOOTNAV_OPEN, start)
+  if (start === -1 || end === -1) return html
+
+  const bodyStart = start + HEADER_CLOSE.length
+  const body = html.slice(bodyStart, end)
+  if (/<main[\s>]/.test(body)) return html
+
+  return `${html.slice(0, bodyStart)}\n<main>\n${body.trim()}\n</main>\n${html.slice(end)}`
+}
+
+/**
+ * Splices the four chrome regions into one lesson file, in a fixed order so a
+ * missing marker is always reported against the same region a session can
+ * check first, then wraps the authored body in `<main>` where it holds none.
+ * Nothing is written when any region is missing, which is what keeps a
+ * partially-spliced file off disk.
+ */
 async function rewriteLesson(
   root: string,
   detail: WorkspaceDetail,
@@ -1164,7 +1204,7 @@ async function rewriteLesson(
 ): Promise<LessonRewritten | LessonRefused> {
   const file = metas[index].file
   const path = join(root, detail.path, TEACH_LESSONS, file)
-  let html = dropHandWrittenIcon(await readFile(path, 'utf8'))
+  let html = dropHandWrittenHead(await readFile(path, 'utf8'))
 
   const teachPrefix = '../../'
   const workspacePrefix = '../'
@@ -1180,7 +1220,7 @@ async function rewriteLesson(
         },
       },
       {
-        label: titleCase(detail.topic),
+        label: workspaceLabel(detail),
         href: `${workspacePrefix}index.html`,
         jump: {
           ariaLabel: 'Jump to a lesson',
@@ -1190,7 +1230,7 @@ async function rewriteLesson(
       { label: `Lesson ${index + 1} of ${metas.length}` },
     ],
     {
-      heading: titleCase(detail.topic),
+      heading: workspaceLabel(detail),
       switcher: workspaceJumpEntries(workspaces, teachPrefix, detail.slug),
       meta: `${metas.length} lesson${metas.length === 1 ? '' : 's'}`,
       items: metas.map((meta, i) => ({
@@ -1210,6 +1250,16 @@ async function rewriteLesson(
   // the class the script reveals feedback with.
   const legacy = html.includes(LEGACY_OPTION)
 
+  // Linked ahead of the embedded rules so those still win the cascade.
+  // Embedding it instead repeats a sheet carrying its fonts inline in every
+  // lesson. A workspace seeded before the pair has no base sheet to link.
+  const hasBase = existsSync(
+    join(root, detail.path, TEACH_ASSETS, TEACH_STYLESHEET_BASE),
+  )
+  const baseLink = hasBase
+    ? `<link rel="stylesheet" href="../${TEACH_ASSETS}/${TEACH_STYLESHEET_BASE}">\n`
+    : ''
+
   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.
@@ -1218,7 +1268,7 @@ async function rewriteLesson(
     // lesson would lack.
     [
       'style',
-      `${teachFavicon()}\n<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>\n${headScript('lesson')}`,
+      `${teachFavicon()}\n${baseLink}<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>\n${headScript('lesson')}`,
     ],
     ['header', header],
     ['footnav', `${renderFootNav(metas, index)}\n${PANE_CLOSE}`],
@@ -1231,7 +1281,7 @@ async function rewriteLesson(
     html = spliced
   }
 
-  await writeFile(path, html)
+  await writeFile(path, wrapMain(html))
   return { ok: true, file }
 }
 

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)