@erclx/canon 5.1.0 → 5.3.0

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

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

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

@@ -7,7 +7,9 @@ description: Scope boundary for learning a subject across sessions, and the spli
 
 ## Gap
 
-Without this skill, a session asked to teach a subject answers in the conversation, so everything it produced dies with the session and the next one starts from nothing. It teaches from recall rather than from a source, so the learner is handed claims nothing was read for and cannot tell which ones. It picks the next topic from the subject's own order rather than from what the learner got wrong, so it teaches past a gap it never measured. It asks nothing about what the learner already knows, so difficulty has no floor and the session lands either below or far above them.
+Without this skill, a session asked to teach a subject answers in the conversation, so everything it produced dies with the session and the next one starts from nothing. It teaches from recall rather than from a source, so the learner is handed claims nothing was read for and cannot tell which ones. When it does read, it takes whatever a search returned first, so a course rests on a few thin sources, and it cites the learner's own projects or an employer's material as proof of a general concept.
+
+It picks the next topic from the subject's own order rather than from what the learner got wrong, so it teaches past a gap it never measured. It asks nothing about what the learner already knows, so difficulty has no floor and the session lands either below or far above them.
 
 It also produces one output where two are needed. A page written to be worked through once and a page written to be looked up later have different lifetimes and different readers, and merging them yields material that is disposable and gets kept, or durable and carries a quiz nobody can promote. Writing the durable half in a format the authoring gates do not read costs a conversion at the moment it matters most, which is the moment someone tries to promote it.
 
@@ -25,7 +27,7 @@ Two failures land specifically on where the folder sits. A workspace resolved ag
 - Name the write route for a main-root path from a linked worktree, since a body naming only the destination reports a success that did not happen
 - Route every edit inside a workspace file that already exists through a verb resolving the root in-process, since a heredoc reaches a whole-file create alone and the stream editors that would reach the rest are banned
 - Settle the learner's starting point by asking, so difficulty sits above a measured floor
-- Research the subject from sources before teaching it, and record what was read and what was found and not opened
+- Research the subject from sources before teaching it, choosing them by the teach standard's ladder, and record what was read and what was found and not opened
 - Place each lesson from the learning records rather than from the subject's order, and open with retrieval on the last wrong answer
 - Split the output by lifetime, sending the worked-through half to lessons and the looked-up half to reference pages in the format the authoring gates read
 - Record the wrong answer itself rather than the count, since that is what the next session places the learner from

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

@@ -61,7 +61,7 @@ Repeat `--success` and `--out-of-scope` per line. The verb refuses a topic anoth
 
 ## Step 2: research before teaching
 
-Read the subject from sources rather than from recall. Record what was read and what was only found through the verb that owns the file:
+Read the subject from sources rather than from recall, chosen by the standard's `### Choosing sources` ladder, with a third-rung source's reason in its title. Record what was read and what was only found through the verb that owns the file:
 
 ```bash
 canon teach resource <topic> --json \
@@ -83,7 +83,7 @@ Open on what `due` reports as overdue, oldest date first, before anything new. W
 
 Two outputs with two lifetimes, and the split decides the format.
 
-- A lesson is a self-contained page carrying its own quiz, a teach-back block, and the feedback for each question. It embeds one shared stylesheet rather than restating styles, and it is disposable and never promoted.
+- A lesson is a self-contained page carrying its own quiz, a teach-back block, and the feedback for each question. It embeds one shared stylesheet rather than restating styles, and it is disposable and never promoted. Its `refs` pass the source ladder, and a learner's or organization's file goes in the body, labeled.
 - A reference page goes to `reference/<slug>.md`, written for a reader with no learner in it. This is the half that survives the workspace, so it is written in markdown to pass the authoring gates a promotion would put it through. `canon teach nav` renders it to a `reference/<slug>.html` sibling, and a lesson links that sibling, since a served `.md` opens as plain text.
 
 Resolve the lesson before writing it, rather than composing its name or its quiz order by hand:

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -74,14 +74,17 @@ The stepper hides and shows and sets nothing else, so how a selected option look
 
 ## The block list
 
-`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Five types, and every structural body composes from them:
+`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Six types, and every structural body composes from them:
 
 - `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
 - `{"type":"paragraph","text":"<text>","lede":true,"cites":[1]}`: a `<p>`, marked `lede` for the dek that opens the lesson. `cites` adds a footnote marker per reference number after the text, and a lede takes none.
 - `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
 - `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the lesson's one reference list, numbered from 1 in item order. `url` and `note` are optional, and a `url` must be http or https.
+- `{"type":"code","lang":"ts","text":"<source>"}`: a code sample, highlighted at render time with no script. `lang` is optional and takes a highlight.js name or alias. One the renderer does not register renders as plain escaped code.
 - `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
 
+Code never travels through `raw`. A hand-written `<pre><code>` renders with no color, and `nav` never highlights markup already in a lesson body, so a sample written that way stays plain for good. A fenced block in a reference page's markdown is highlighted by `nav` on its own.
+
 The quiz and the teach-back block above are the one case `raw` is always needed for, since their fixed contract is not a components concern. Give them the array's last `raw` entry, followed only by `refs`, rather than reaching for `raw` anywhere the other types could carry the content instead.
 
 A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than into the sentence. Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened. Render refuses a cite no reference resolves, so number the list before citing into it.

package/claude/skills/teach-workspace/references/pedagogy.md

@@ -75,3 +75,4 @@ Parametric recall is confident where it is wrong, and a learner cannot audit it.
 - Read the subject from sources before teaching, and record each one with its link
 - Mark any claim resting on recall as resting on recall, in the lesson itself
 - List a source found and not opened as a lead, and never cite it
+- Choose which sources to read by the ladder under `### Choosing sources` in the teach standard, which also rules out the learner's own work as proof of a general claim

package/docs/agents/commands.md

@@ -141,3 +141,9 @@ The report carries three states and never changes an exit code. `behind` names
 reason the registry could not be reached. Branch on the `skew.state` field in
 the JSON record rather than on the exit, since an offline machine has to read as
 unmeasured rather than as a failing check.
+
+`canon upgrade --json` carries one further state, `pending`, that the skew report
+does not. It means the checkout at the working directory holds a release npm does
+not serve yet, so there is nothing to install. The record names that version in
+`checkout` beside `latest`, exits 0, and its `message` starts `CLI stays at`. A
+directory outside any canon checkout never reads `pending`.

package/docs/agents/teach-authoring.md

@@ -38,7 +38,7 @@ The order is drawn here rather than instructed, and that is the point of the ver
 
 ## Render
 
-`canon teach render` renders a lesson body's structural blocks to HTML, through the four lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+`canon teach render` renders a lesson body's structural blocks to HTML, through the five lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
 
 ```bash
 echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json
@@ -48,7 +48,13 @@ echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach re
 | -------- | ---------------------------------------- |
 | `--json` | Emit a machine-readable record on stdout |
 
-It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
+It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, `code`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
+
+A `code` block carries `text` and an optional `lang`, a highlight.js name or alias. The source is highlighted at render time into `hljs-*` class spans the workspace stylesheet colors in both themes, so the page carries no script. A `lang` the renderer does not register renders as plain escaped code, and one that does not match `^[a-z0-9+#-]+$` is refused. A workspace seeded before the syntax colors existed shows the spans uncolored until `canon teach stylesheet <topic>` rewrites its base stylesheet.
+
+```json
+[{ "type": "code", "lang": "ts", "text": "const a: number = 1" }]
+```
 
 A citation takes two shapes. A `paragraph` carries an optional `cites` array of reference numbers, rendered as `sup.cite` markers after its text. The one `refs` block carries `items` of `{ title, url?, note? }`, rendered as `ol.refs` and numbered from 1, so cite `1` links to the first item.
 
@@ -107,6 +113,6 @@ Splicing the stepper into a lesson of either shape was measured against a browse
 
 ### Reference pages
 
-Each reference page is rendered to a `reference/<slug>.html` sibling carrying the same chrome, and the contents page links that sibling rather than the markdown, which `canon serve` hands over as plain text. The render drops the frontmatter, turns tables into `<table>` markup, and escapes raw HTML written in the markdown rather than passing it through. A body with no H1 gets one from the frontmatter `title`. A relative link to another reference page's markdown points at that page's `.html` sibling, and one to the workspace `GLOSSARY.md` points at the glossary on the contents page, `../index.html#gloss`. Every other link, such as `../RESOURCES.md`, stays as written. The markdown file is never touched.
+Each reference page is rendered to a `reference/<slug>.html` sibling carrying the same chrome, and the contents page links that sibling rather than the markdown, which `canon serve` hands over as plain text. The render drops the frontmatter, turns tables into `<table>` markup, and escapes raw HTML written in the markdown rather than passing it through. A fenced code block in a language the highlighter registers is highlighted the same way a `code` block is, and one in any other language stays plain. A hand-written code block in a lesson body is never highlighted. A body with no H1 gets one from the frontmatter `title`. A relative link to another reference page's markdown points at that page's `.html` sibling, and one to the workspace `GLOSSARY.md` points at the glossary on the contents page, `../index.html#gloss`. Every other link, such as `../RESOURCES.md`, stays as written. The markdown file is never touched.
 
 Every rendered page carries a `<meta name="generator" content="canon teach nav">` tag. A `.html` file under `reference/` whose markdown is gone is deleted when it carries that tag, and a hand-written HTML file there, carrying none, is left alone. The record's `reference` field counts the pages rendered. On a Bun with no `Bun.markdown`, each reference page lands in `skipped` with `Bun.markdown` as what is missing, and the rest of the run goes on.

package/docs/agents/teach.md

@@ -81,7 +81,7 @@ canon teach resource regular-expressions \
 | `--json`             | Emit a machine-readable record on stdout           |
 | `--root <path>`      | Teach root, defaulting to the main worktree        |
 
-The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from.
+The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from. Which sources qualify is the source ladder in `canon standards teach`, and a source below its first two rungs also names why no higher one covers the claim.
 
 A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer.
 

package/docs/workflow/operating-model.md

@@ -232,5 +232,5 @@ port-collision detail.
 ## Related
 
 - [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the isolation and fan-out mechanics
-- [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism without worktrees
+- [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism without worktrees, and [blocking subagents](../../wiki/claude/permissions.md#blocking-subagents) for the `permissions.deny` rule that stops every spawn
 - `canon/context/claude-plugin/skill-strategy/overview.md` for how the skills in the loop are categorized

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -56,6 +56,7 @@
   "dependencies": {
     "commander": "^13.1.0",
     "execa": "^9.5.2",
+    "highlight.js": "^11.12.0",
     "playwright-core": "1.59.1",
     "pptxgenjs": "^4.0.1"
   },

package/src/claude/plugin-update.ts

@@ -43,6 +43,6 @@ export function matchInstall(
 
 export function updatedMessage(before: string, after: string): string {
   return after === before
-    ? `Reinstalled ${after}, unchanged.`
-    : `Updated ${before} to ${after}.`
+    ? `Plugin reinstalled ${after}, unchanged.`
+    : `Plugin updated ${before} to ${after}.`
 }

package/src/commands/teach.ts

@@ -2,7 +2,7 @@ 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'
-import { type RenderOutcome, renderLessonBody } from '@/teach/render'
+import type { RenderOutcome } from '@/teach/render'
 import {
   defineTerms,
   type ListOutcome,
@@ -393,10 +393,14 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Reads a JSON array of blocks from stdin, each a heading, paragraph,',
-        'list, refs, or raw block, and renders it through the same components',
-        'the fixture lesson is generated from. Content the structured blocks',
-        'cannot express takes type raw, carrying its own html verbatim,',
-        'unescaped.',
+        'list, refs, code, or raw block, and renders it through the same',
+        'components the fixture lesson is generated from. Content the',
+        'structured blocks cannot express takes type raw, carrying its own',
+        'html verbatim, unescaped.',
+        '',
+        'A code block takes text and an optional lang, a highlight.js name or',
+        'alias matching ^[a-z0-9+#-]+$, and renders highlighted at build time',
+        'with no script. An unregistered lang renders as plain escaped code.',
         '',
         'A paragraph takes an optional cites array of reference numbers,',
         'rendered as footnote markers after its text. The one refs block',
@@ -752,6 +756,9 @@ async function runRender(opts: RenderCommandOptions): Promise<number> {
     )
   }
 
+  // Loaded here rather than at the top, since the renderer pulls in the
+  // highlighter and every other verb would pay for its grammars at startup.
+  const { renderLessonBody } = await import('@/teach/render')
   return reportRender(renderLessonBody(parsed), emitJson)
 }
 

package/src/commands/upgrade.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander'
 import { execa } from 'execa'
-import { PROJECT_ROOT } from '@/project-root'
+import { findCheckoutMismatch, PROJECT_ROOT } from '@/project-root'
 import {
   frameError,
   intro,
@@ -10,6 +10,7 @@ import {
   outro,
   select,
 } from '@/ui'
+import { compareVersions, parseVersion } from '@/version/compare'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { detectManager, installCommand, type Manager } from '@/version/manager'
 import {
@@ -30,7 +31,9 @@ interface UpgradeRecord {
   readonly before: string
   readonly after?: string
   readonly latest?: string
-  readonly state: 'upgraded' | 'current' | 'cancelled' | 'refused'
+  /** The version of the checkout at cwd, present only on `pending`. */
+  readonly checkout?: string
+  readonly state: 'upgraded' | 'current' | 'pending' | 'cancelled' | 'refused'
   readonly reason?: string
   /**
    * One rendered line for a caller that reports the outcome without parsing
@@ -117,7 +120,24 @@ async function runUpgrade(opts: UpgradeOptions): Promise<number> {
   logStep('Published')
   logInfo(describeSkew(skew))
 
+  const checkout = readCheckoutVersion()
+  const latest = latestOf(skew)
+
   if (skew.state === 'current') {
+    const note = pendingNote(latest, checkout)
+    if (note !== undefined && checkout !== undefined) {
+      logWarn(note)
+      outro()
+      emit(opts, {
+        ...base(before, manager, command, skew),
+        after: before,
+        checkout,
+        state: 'pending',
+        message: `CLI stays at ${before}. ${note}`,
+      })
+      return 0
+    }
+
     outro()
     emit(opts, {
       ...base(before, manager, command, skew),
@@ -128,7 +148,7 @@ async function runUpgrade(opts: UpgradeOptions): Promise<number> {
     return 0
   }
 
-  return await applyUpgrade(opts, before, skew, manager, command)
+  return await applyUpgrade(opts, before, skew, manager, command, checkout)
 }
 
 /**
@@ -147,6 +167,7 @@ async function applyUpgrade(
   skew: SkewReport,
   manager: Manager,
   command: readonly string[],
+  checkout: string | undefined,
 ): Promise<number> {
   const proceed = await select({
     message: `Run \`${command.join(' ')}\`?`,
@@ -199,15 +220,50 @@ async function applyUpgrade(
     ...base(before, manager, command, skew),
     after,
     state: 'upgraded',
-    message: upgradedMessage(before, after),
+    message: [upgradedMessage(before, after), pendingNote(after, checkout)]
+      .filter((part) => part !== undefined)
+      .join(' '),
   })
   return 0
 }
 
+/**
+ * The version of the checkout the caller stands in, read off cwd rather than
+ * off `PROJECT_ROOT`, which is the installed package a bare `canon` resolves
+ * to. A target project sits in no canon checkout, so this reads nothing there
+ * and the verb behaves as it did.
+ */
+function readCheckoutVersion(): string | undefined {
+  const dir = findCheckoutMismatch(process.cwd())
+  return dir === undefined ? undefined : readInstalled(dir).version
+}
+
+/**
+ * The clause a caller appends when the checkout carries a release npm does not
+ * serve yet. A pull lands the release commit before the publish job finishes,
+ * so for a few minutes the checkout leads the registry, and a release that
+ * never publishes keeps it leading. The wording names the served version
+ * rather than promising a publish for that reason. `undefined` covers every
+ * case with nothing to say, including a version that does not parse.
+ */
+export function pendingNote(
+  served: string | undefined,
+  checkout: string | undefined,
+): string | undefined {
+  if (served === undefined || checkout === undefined) return undefined
+
+  const local = parseVersion(checkout)
+  const published = parseVersion(served)
+  if (local === undefined || published === undefined) return undefined
+  if (compareVersions(local, published) <= 0) return undefined
+
+  return `The checkout is at ${checkout} and npm serves ${served}.`
+}
+
 export function upgradedMessage(before: string, after: string): string {
   return after === before
-    ? `Reinstalled ${after}, unchanged.`
-    : `Upgraded ${before} to ${after}.`
+    ? `CLI reinstalled ${after}, unchanged.`
+    : `CLI upgraded ${before} to ${after}.`
 }
 
 function base(

package/src/design/components.ts

@@ -210,6 +210,39 @@ export const COMPONENTS: readonly Component[] = [
  */
 export const TEACH_SIDEBAR_BREAKPOINT = 1100
 
+/**
+ * The colors highlighted code renders in, one per token class the teach
+ * article maps highlight.js spans onto. Hex rather than `color-mix` so the
+ * contrast test can measure each against the code surface, and dark by default
+ * with a light override, following the same `data-theme` switch as the ground
+ * they sit on. Teach-local until a second surface renders highlighted code.
+ * `keyword`, `comment` and `meta` repeat the accent, muted and secondary
+ * values, so code reads in the page's own palette.
+ */
+export const TEACH_SYNTAX: readonly {
+  readonly name: string
+  readonly dark: string
+  readonly light: string
+}[] = [
+  { name: 'keyword', dark: '#c76b5f', light: '#ad4a4b' },
+  { name: 'string', dark: '#8dbb6c', light: '#2d6b22' },
+  { name: 'number', dark: '#d4a15a', light: '#8a5300' },
+  { name: 'title', dark: '#b99ad8', light: '#72489a' },
+  { name: 'attr', dark: '#6fb3c4', light: '#1e6478' },
+  { name: 'comment', dark: '#7f7f7c', light: '#6e6d6c' },
+  { name: 'meta', dark: '#8c8b86', light: '#666561' },
+]
+
+const syntaxProperty = (name: string): string => `--teach-syntax-${name}`
+
+const TEACH_SYNTAX_DARK = TEACH_SYNTAX.map(
+  ({ name, dark }) => `  ${syntaxProperty(name)}: ${dark};`,
+).join('\n')
+
+const TEACH_SYNTAX_LIGHT = TEACH_SYNTAX.map(
+  ({ name, light }) => `  ${syntaxProperty(name)}: ${light};`,
+).join('\n')
+
 const TEACH_CHROME: Component = {
   name: 'teach-chrome',
   note: [
@@ -263,6 +296,12 @@ const TEACH_CHROME: Component = {
   --ink-faint: var(--color-muted);
   --accent: var(--color-accent);
   --accent-bg: var(--color-teach-accent-bg);
+
+${TEACH_SYNTAX_DARK}
+}
+
+[data-theme='light'] {
+${TEACH_SYNTAX_LIGHT}
 }
 
 @media (prefers-color-scheme: dark) {
@@ -1007,6 +1046,7 @@ const TEACH_ARTICLE: Component = {
     '--color-accent',
     '--teach-hand',
     '--teach-mono',
+    ...TEACH_SYNTAX.map(({ name }) => syntaxProperty(name)),
     '--t1',
     '--t2',
     '--t3',
@@ -1092,6 +1132,18 @@ pre {
 
 pre code { background: none; padding: 0; font-size: 1em; }
 
+/* Build-time highlight.js spans. Every class reads a --teach-syntax-* token,
+   so the dark and light values switch with the ground rather than per rule. */
+.hljs-keyword, .hljs-selector-tag, .hljs-literal, .hljs-built_in, .hljs-doctag { color: var(--teach-syntax-keyword); }
+.hljs-string, .hljs-regexp, .hljs-addition, .hljs-template-tag, .hljs-symbol { color: var(--teach-syntax-string); }
+.hljs-number, .hljs-type, .hljs-selector-class, .hljs-selector-id { color: var(--teach-syntax-number); }
+.hljs-title, .hljs-section, .hljs-name, .hljs-bullet { color: var(--teach-syntax-title); }
+.hljs-attr, .hljs-attribute, .hljs-variable, .hljs-template-variable, .hljs-property { color: var(--teach-syntax-attr); }
+.hljs-comment, .hljs-quote { color: var(--teach-syntax-comment); font-style: italic; }
+.hljs-meta, .hljs-deletion, .hljs-subst { color: var(--teach-syntax-meta); }
+.hljs-emphasis { font-style: italic; }
+.hljs-strong { font-weight: 700; }
+
 /* ---- Callout ---- */
 
 .hard {

package/src/teach/components/code.tsx

@@ -0,0 +1,24 @@
+/** @jsxImportSource ../html */
+import { highlight } from '@/teach/highlight'
+import type { Element } from '@/teach/html/jsx-runtime'
+import { raw } from '@/teach/html/raw'
+
+export interface CodeProps {
+  /** A highlight.js language name or alias. Unregistered ones render plain. */
+  readonly lang?: string
+  readonly text: string
+}
+
+/**
+ * The one way code reaches a lesson body. The highlighter escapes every source
+ * character before wrapping tokens in spans, which is what makes passing its
+ * output through `raw` safe.
+ */
+export function Code({ lang, text }: CodeProps): Element {
+  const className = lang === undefined ? 'hljs' : `hljs language-${lang}`
+  return (
+    <pre>
+      <code class={className}>{raw(highlight(text, lang).html)}</code>
+    </pre>
+  )
+}

package/src/teach/highlight.ts

@@ -0,0 +1,71 @@
+import hljs from 'highlight.js/lib/core'
+import bash from 'highlight.js/lib/languages/bash'
+import css from 'highlight.js/lib/languages/css'
+import diff from 'highlight.js/lib/languages/diff'
+import dockerfile from 'highlight.js/lib/languages/dockerfile'
+import go from 'highlight.js/lib/languages/go'
+import javascript from 'highlight.js/lib/languages/javascript'
+import json from 'highlight.js/lib/languages/json'
+import markdown from 'highlight.js/lib/languages/markdown'
+import python from 'highlight.js/lib/languages/python'
+import shell from 'highlight.js/lib/languages/shell'
+import sql from 'highlight.js/lib/languages/sql'
+import typescript from 'highlight.js/lib/languages/typescript'
+import xml from 'highlight.js/lib/languages/xml'
+import yaml from 'highlight.js/lib/languages/yaml'
+
+/**
+ * A fixed set rather than all of highlight.js, since each grammar costs load
+ * time and a workspace rarely reaches past these. An unlisted language renders
+ * plain rather than refusing, so adding one here is the whole change.
+ */
+const LANGUAGES = {
+  bash,
+  css,
+  diff,
+  dockerfile,
+  go,
+  javascript,
+  json,
+  markdown,
+  python,
+  shell,
+  sql,
+  typescript,
+  xml,
+  yaml,
+}
+
+for (const [name, grammar] of Object.entries(LANGUAGES)) {
+  hljs.registerLanguage(name, grammar)
+}
+
+export interface Highlighted {
+  /** Markup safe to embed inside `<code>`: every source character escaped. */
+  readonly html: string
+  /** The language as asked for, or `undefined` when it rendered plain. */
+  readonly language: string | undefined
+}
+
+function escapeCode(text: string): string {
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}
+
+/**
+ * Highlights code at build time into `hljs-*` class spans the teach
+ * stylesheet colors, so an emitted page needs no script. An absent or
+ * unregistered language falls back to escaped plain text rather than
+ * throwing or guessing.
+ */
+export function highlight(text: string, lang?: string): Highlighted {
+  if (lang === undefined || hljs.getLanguage(lang) === undefined) {
+    return { html: escapeCode(text), language: undefined }
+  }
+  return {
+    html: hljs.highlight(text, { language: lang, ignoreIllegals: true }).value,
+    language: lang,
+  }
+}

package/src/teach/nav.ts

@@ -1170,6 +1170,35 @@ function retargetReferenceLinks(
   )
 }
 
+const FENCED_CODE =
+  /<pre><code class="language-([^"]+)">([\s\S]*?)<\/code><\/pre>/g
+
+function decodeHtml(html: string): string {
+  return html
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&#39;', "'")
+    .replaceAll('&amp;', '&')
+}
+
+/**
+ * Highlights the fenced blocks `Bun.markdown` emitted, decoding each once
+ * since the renderer already escaped it. A fence in a language the highlighter
+ * does not register is left exactly as the markdown rendered it. The module is
+ * imported here rather than at the top so a verb that never reaches a
+ * reference page does not load its grammars.
+ */
+async function highlightFences(html: string): Promise<string> {
+  if (!html.includes('<pre><code class="language-')) return html
+  const { highlight } = await import('@/teach/highlight')
+  return html.replace(FENCED_CODE, (match, lang: string, escaped: string) => {
+    const result = highlight(decodeHtml(escaped), lang)
+    if (result.language === undefined) return match
+    return `<pre><code class="hljs language-${lang}">${result.html}</code></pre>`
+  })
+}
+
 /**
  * One reference page as a styled page carrying the workspace chrome. The
  * markdown beside it stays the durable, promotable half, and this file is
@@ -1191,10 +1220,12 @@ async function renderReferencePage(
     readField(parseFrontmatter(source), 'title') ?? referenceFallbackTitle(file)
 
   const rendered = retargetReferenceLinks(
-    Bun.markdown.html(stripFrontmatter(source), {
-      noHtmlBlocks: true,
-      noHtmlSpans: true,
-    }),
+    await highlightFences(
+      Bun.markdown.html(stripFrontmatter(source), {
+        noHtmlBlocks: true,
+        noHtmlSpans: true,
+      }),
+    ),
     new Set(detail.referenceFiles),
   )
   const body = /<h1[\s>]/.test(rendered)

package/src/teach/render.ts

@@ -1,3 +1,4 @@
+import { Code } from '@/teach/components/code'
 import { Heading } from '@/teach/components/heading'
 import { List } from '@/teach/components/list'
 import { Paragraph } from '@/teach/components/paragraph'
@@ -19,6 +20,7 @@ export type LessonBlock =
       readonly ordered?: boolean
     }
   | { readonly type: 'refs'; readonly items: readonly Reference[] }
+  | { readonly type: 'code'; readonly text: string; readonly lang?: string }
   | { readonly type: 'raw'; readonly html: string }
 
 export interface RenderRendered {
@@ -28,7 +30,17 @@ export interface RenderRendered {
 
 export type RenderOutcome = RenderRendered | TeachRefused
 
-const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'refs', 'raw'] as const
+const BLOCK_TYPES = [
+  'heading',
+  'paragraph',
+  'list',
+  'refs',
+  'code',
+  'raw',
+] as const
+
+/** Bounds a lang to what a class name can carry, so it never injects. */
+const CODE_LANG = /^[a-z0-9+#-]+$/
 
 const LINK_PROTOCOLS = new Set(['http:', 'https:'])
 
@@ -170,6 +182,20 @@ function renderBlock(
         referenceCount: items.length,
       }
     }
+    case 'code': {
+      if (!isString(fields.text)) {
+        return badBlock(index, 'code needs a string text')
+      }
+      if (
+        fields.lang !== undefined &&
+        !(isString(fields.lang) && CODE_LANG.test(fields.lang))
+      ) {
+        return badBlock(index, `code lang must match ${CODE_LANG.source}`)
+      }
+      return {
+        html: render(Code({ lang: fields.lang, text: fields.text })),
+      }
+    }
     case 'raw': {
       if (!isString(fields.html)) {
         return badBlock(index, 'raw needs a string html')

package/standards/teach.md

@@ -128,6 +128,20 @@ Splits what was read from what was found.
 
 A source found and not read is listed as a lead because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later session searching for what this one already surfaced.
 
+### Choosing sources
+
+Rest each general claim on the highest rung that covers it:
+
+1. Documentation or a specification published by whoever owns the subject
+2. A canonical work on the subject, such as the standard text, a reference book, or a primary paper
+3. Other material, such as a tutorial, a course, or a post, and only for a claim the first two rungs do not cover
+
+A subject nobody owns, such as a mathematical topic or a craft, has no first rung, so its list starts at the second and is not missing anything. Record a third-rung source with the claim it covers and why no higher rung does, since that reason is what a later session checks the choice against.
+
+The learner's own projects and material specific to one employer or organization are never a source for a general claim. Either may appear in the workspace as a worked application labeled with whose it is, and neither stands in `RESOURCES.md` as proof of what the subject says.
+
+A source reachable only through a paywall or a summary stays a lead until it is opened. A review or summary of a book is a different source from the book, so list the summary as read on its own rung and the book as a lead.
+
 ## Conventions
 
 - Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
@@ -141,6 +155,7 @@ A source found and not read is listed as a lead because a link attached to a pag
 - **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
 - **The revisit note with no date.** A line naming what to come back to and not when is read by nothing and schedules nothing, so the next session picks from the last record alone, which is the state the section exists to end.
 - **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
+- **The first search result as the source list.** A workspace resting on whatever a search returned first teaches the weakest account of the subject, and nothing in the folder says a stronger one was never looked for.
 - **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
 
 ## Template