@erclx/aitk 3.45.0 → 3.46.0

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

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

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

@@ -13,6 +13,8 @@ It also produces one output where two are needed. A page written to be worked th
 
 A session that does record something records the wrong thing. It writes what was taught rather than what the learner retrieved, and a tally of errors carries none of the misconception a later session would work against.
 
+The lesson then reaches nobody. It is a page carrying a stylesheet and a script, and the only thing a session hands over is a file path, which an editor preview opens with neither. The learner reads unstyled markup and takes it for the lesson, or opens nothing at all, and either way the session reports the lesson as delivered. A path is also the wrong unit once a workspace holds several pages, since the learner wants the one they are on rather than the folder it sits in.
+
 The durable half then has nowhere to go. A reference page and a glossary carry no learner and are ordinary reference prose, so they belong wherever the project already keeps prose on that subject, and a workspace holding them is a gitignored folder one person reads. A session moving them by hand picks a destination from the reader's activity rather than from who owns the subject, drops a page into a corpus without the source line that corpus requires, and has nothing stopping it from carrying a lesson across.
 
 Two failures land specifically on where the folder sits. A workspace resolved against the current directory forks into a copy per linked worktree, so the learning records split and no session sees the whole history. A body naming only the destination path reports success and loses the write, because the file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead.
@@ -28,6 +30,7 @@ Two failures land specifically on where the folder sits. A workspace resolved ag
 - Split the output by lifetime, sending the worked-through half to lessons and the looked-up half to reference pages in the format the authoring gates read
 - Record the wrong answer itself rather than the count, since that is what the next session places the learner from
 - Report progress against the mission's success lines, so a mission can be called finished
+- Hand the learner a link that opens the workspace in a real browser on every run, reading it back from the verb that served it rather than composing one, since the port a preview lands on is not the port it asked for
 - Propose a destination for each durable page by who owns its subject, and wait for the operator rather than routing on the session's own reading
 - Hand each confirmed page off through a named file of its own, so one skill owns the durable writes and no other producer's unread work is discarded with it
 - Name what the destination expects that the page does not carry yet, since the workspace runs none of the gates the destination does

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

@@ -113,6 +113,18 @@ aitk teach glossary <topic> --json \
 
 Follow `${CLAUDE_SKILL_DIR}/references/lesson-craft.md` for what makes a lesson worth returning to. Keep every quiz answer the same length, so formatting leaks no clue about which one is correct.
 
+### Hand over a link, never a path
+
+A lesson is a page carrying a stylesheet and a script, and an editor preview opens it with neither, so a path alone delivers unstyled markup that reads as the lesson. Serve the teach root and give the learner a link they can click:
+
+```bash
+aitk serve .claude/teach --entry <nn>-<topic>/index.html --json
+```
+
+Start it in the background so the session keeps going, and read `url` off the record rather than composing one. The verb walks past a port already in use, so the port it took is exactly the half a guessed URL gets wrong. Report the refusal and its `reason` when `ok` is false, and report it rather than proceeding silently when the verb does not resolve at all, which is an installed CLI predating it.
+
+Do this on every run that opens or resumes a workspace, including one that writes no lesson, since the learner's route into what is already there is the same link.
+
 ## Step 5: record what happened
 
 Write `learning-records/<nnnn>-<slug>.md` before the session ends, carrying the lessons covered, what the learner retrieved unaided, what they got wrong with the wrong answer itself, and what to revisit.
@@ -165,9 +177,14 @@ Lesson:    .claude/teach/<nn>-<topic>/lessons/<nnnn>-<slug>.html
 Reference: .claude/teach/<nn>-<topic>/reference/<slug>.md
 Record:    .claude/teach/<nn>-<topic>/learning-records/<nnnn>-<slug>.md
 Progress:  <n> of <m> success lines met
+Open:      [<the url the serve verb reported>](<the same url>)
 ```
 
-Omit the reference line where the lesson produced no durable page. Emit every path from the project root, in the form the project's instruction file sets.
+Omit the reference line where the lesson produced no durable page. The open line is the one line that is never omitted, since it is the only route the learner has into the page, and it carries what `aitk serve` reported rather than a URL composed here. Where the verb refused, that line names the refusal instead of a link.
+
+Write that line as a markdown link carrying the URL as both its text and its target, rather than as a bare URL and never inside backticks. A code span renders as text the reader has to select and copy, which is the one thing the line exists to save them, and the path rule the project states governs a file path rather than a URL.
+
+Emit every path from the project root, in the form the project's instruction file sets.
 
 A promotion pass reports its own shape instead, one line per page the operator confirmed and one naming the handoff:
 

package/docs/agents/commands.md

@@ -63,8 +63,17 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                            |
 | `aitk inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                 |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                |
+| `aitk serve [dir]`         | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                              |
 | `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                |
 
+`aitk serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
+
+A port already in use is the ordinary case rather than a refusal, so it walks forward to the next free one and reports which it took. That is why a caller reads `url` off the `--json` record instead of composing one from the port it asked for. Only contention is walked past. Any other bind failure refuses as `bind-failed` carrying the error's code, rather than being retried twenty times and reported as a range being full, which names a cause nothing checked.
+
+A request naming a directory is redirected to its trailing-slash form rather than answered in place. A browser resolves a relative asset against the last slash of the URL it is on, so answering `/lesson` directly leaves the page asking for `/course.css` instead of `/lesson/course.css`, and it renders unstyled through the server that exists to prevent exactly that.
+
+Containment is tested after symlinks are followed rather than on the path as written, and the test sits immediately before the read rather than beside the request that produced it. Resolving a request lexically clears a link pointing outside the served root, and this repository is a live instance of that shape, since `claude/standards` and `claude/snippets` are links out of `claude/`. Position is what makes the property hold: a directory request appends its index after the request path has been checked, so a check placed earlier leaves that index untested. An `--entry` that escapes the root refuses with `no-entry` before a port is taken, because `url` is the field a caller hands to a reader.
+
 `aitk demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
 
 `aitk inventory` is the third and takes the same answer for the same reason. It reads `inventory.toml` at the project root for its base URL, its routes, and the element query each subject runs over, so what it walks comes from the project rather than from the toolkit. It reports how many different answers a site gives for one property and never gates, because whether five focus rings across four routes is a defect is a judgment. A missing server and an unmatched query are both refusals rather than empty listings, since a listing with no rows reads as one consistent answer.

package/docs/agents/counts.md

@@ -59,7 +59,7 @@ The article gate is looser than the verb list and carries a real cost. Re-runnin
 
 A delta phrased as a transition (`from fourteen to fifteen`), a fraction (`thirteen of sixteen`), and a total reached through an indirect noun (`denominator of sixty-one shipped skills`) are all catalog-size claims this corpus carries, and none matches the trigger shape this reads. Each stays a known gap. The false-positive rate that gated closing them has a measurement behind it now, and what it showed is that the widening these three need is the one that costs a false positive rather than the one that does not.
 
-A second figure in a sentence whose first figure already matched is a fourth gap and a structural one, since one match is taken per catalog per sentence. `authors 70 rules under governance/rules/ and consumes 55 into .claude/rules/` is read for its 70 alone, which is correct here because the two figures name different populations, and a sentence stating one catalog twice would go unread the same way.
+A second figure in a sentence whose first figure already matched is a fourth gap and a structural one, since one match is taken per catalog per sentence. `authors 70 rules under governance/rules/ and consumes 62 into .claude/rules/` is read for its 70 alone, which is correct here because the two figures name different populations, and a sentence stating one catalog twice would go unread the same way.
 
 A calendar date (`2026-08-21`) or a backticked commit reference in the same sentence reads the whole sentence past, since that is how this corpus already marks a figure as a historical record rather than a live claim. `.claude/ARCHITECTURE.md` and the context entries carry a figure this way deliberately, and every one of them stays correct forever.
 

package/docs/agents/teach.md

@@ -129,6 +129,18 @@ Each `quiz` entry carries `order`, the authored option indices in presentation o
 
 The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.
 
+## Opening a workspace
+
+No `aitk teach` verb serves the workspace. `aitk serve` does, taking the teach root as its directory and the workspace contents page as its entry:
+
+```bash
+aitk serve .claude/teach --entry 03-fde-system-design/index.html --json
+```
+
+It stays general rather than becoming `aitk 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.
+
 ## Refusal reasons
 
 | Reason         | Raised when                                                     |

package/governance/rules/claude/561-teach.md

@@ -9,5 +9,5 @@ paths:
 ## Authority
 
 - Follow the teach standard for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source. Read it with `aitk standards teach`.
-- Read `references/glossary.md` inside the `aitk:claude-teach` skill for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it rather than invoking the skill, which resumes a workspace and runs lessons.
+- Follow the glossary standard for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it with `aitk standards glossary`.
 - Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/governance/rules/ui/400-ui.md

@@ -4,6 +4,7 @@ paths:
   - '**/*.tsx'
   - '**/*.jsx'
   - '**/*.astro'
+  - '**/*.html'
 ---
 
 # UI copy standards

package/governance/rules/ui/410-a11y.md

@@ -4,6 +4,8 @@ paths:
   - '**/*.tsx'
   - '**/*.jsx'
   - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
 ---
 
 # Accessibility and keyboard standards

package/governance/rules/ui/420-forms.md

@@ -4,6 +4,7 @@ paths:
   - '**/*.tsx'
   - '**/*.jsx'
   - '**/*.astro'
+  - '**/*.html'
 ---
 
 # Form standards

package/governance/rules/ui/430-ux-completeness.md

@@ -4,6 +4,8 @@ paths:
   - '**/*.tsx'
   - '**/*.jsx'
   - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
 ---
 
 # UX completeness standards

package/governance/rules/ui/440-surface-capture.md

@@ -1,24 +1,32 @@
 ---
-description: Require a route capture against a running preview after a page or route surface changes
+description: Require a capture against a running preview after a rendered surface changes
 paths:
   - '**/routes/**/*.{tsx,jsx,vue,svelte,astro}'
   - '**/pages/**/*.{tsx,jsx,vue,svelte,astro}'
   - '**/app/**/page.{tsx,jsx}'
+  - '**/*.html'
 ---
 
 # Surface capture standards
 
+## What a surface is
+
+- A surface is anything the project renders for a person to look at. A framework route is one. A page the project generates is another, whoever generates it.
+- Judge a generated page by the same rule as a route. Reading its markup reports nothing about how it composes.
+
 ## When to capture
 
-- Run `bun run screenshot` after changing what a route renders.
+- Run the project's capture command after changing what a surface renders. Report it rather than proceeding silently when the project has none.
 - Capture against a running preview server. Do not capture against a dev server.
-- Capture every theme the route ships. Do not capture the default theme alone.
+- Capture every theme the surface ships. Do not capture the default theme alone.
+- Capture again after fixing a defect a capture found. A repair inside a shared stylesheet can cancel a rule written earlier in the same file.
 
 ## What a capture covers
 
 - Capture the full page at the viewport its case declares. Do not capture a component in isolation.
-- Add a case to the capture record when adding a route.
-- Remove a route's case in the change that removes the route.
+- Drive a state a screenshot cannot reach. An initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling.
+- Add a case to the capture record when adding a surface.
+- Remove a surface's case in the change that removes the surface.
 
 ## Sharing a capture
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.45.0",
+  "version": "3.46.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -15,6 +15,7 @@ import { register as docs } from '@/commands/docs'
 import { register as design } from '@/commands/design'
 import { register as slides } from '@/commands/slides'
 import { register as capture } from '@/commands/capture'
+import { register as serve } from '@/commands/serve'
 import { register as demo } from '@/commands/demo'
 import { register as inventory } from '@/commands/inventory'
 import { register as feedback } from '@/commands/feedback'
@@ -61,6 +62,7 @@ function showHelp(): void {
     `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render)${NC}`,
     `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
     `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
+    `${GREY}│${NC}    serve [dir]        ${GREY}# Serve a directory over localhost and print the preview link${NC}`,
     `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
     `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/feedback/${NC}`,
@@ -108,6 +110,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk slides render`,
     `${GREY}│${NC}    aitk slides list --json`,
     `${GREY}│${NC}    aitk capture assets/install.html`,
+    `${GREY}│${NC}    aitk serve .claude/teach`,
     `${GREY}│${NC}    aitk inventory focus --json`,
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
@@ -160,6 +163,7 @@ docs(program)
 design(program)
 slides(program)
 capture(program)
+serve(program)
 demo(program)
 inventory(program)
 feedback(program)

package/src/commands/serve.ts

@@ -0,0 +1,159 @@
+import type { Command } from 'commander'
+import { relative } from 'node:path'
+import { DEFAULT_PORT, type ServeOutcome, startServer } from '@/serve/static'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+const DEFAULT_DIR = '.'
+
+interface ServeCommandOptions {
+  readonly entry?: string
+  readonly json?: boolean
+  readonly port?: string
+}
+
+export function register(program: Command): void {
+  program
+    .command('serve')
+    .description('Serve a directory over localhost and print the preview link')
+    .argument('[dir]', 'Directory to serve', DEFAULT_DIR)
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--port <number>', `Port to try first, default ${DEFAULT_PORT}`)
+    .option('--entry <path>', 'Page the printed link opens, default index.html')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the server stopped after running',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'The server binds 127.0.0.1 and nothing else, and it sends no cache',
+        'headers, so an edited stylesheet is never served stale. A port in use',
+        'is not a failure: the next free one is taken and the link says which.',
+        '',
+        'It runs until interrupted. A session wanting the link without waiting',
+        'starts it in the background and reads the record off stdout.',
+        '',
+        'Examples:',
+        '  aitk serve .claude/teach',
+        '  aitk serve .claude/teach --entry 03-fde-system-design/index.html',
+        '  aitk serve dist --port 4000 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (dir: string, opts: ServeCommandOptions) => {
+      process.exitCode = await runServe(dir, opts)
+    })
+}
+
+async function runServe(
+  dir: string,
+  opts: ServeCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  const port = parsePort(opts.port)
+  if (port === undefined) {
+    return report(
+      { ok: false, reason: 'no-port', detail: `${opts.port} is not a port` },
+      emitJson,
+    )
+  }
+
+  const outcome = startServer(dir, { port, entry: opts.entry })
+  const code = report(outcome, emitJson)
+  if (!outcome.ok) return code
+
+  await waitForInterrupt(outcome.stop)
+  return 0
+}
+
+/**
+ * The relative path where it stays inside the working directory, and the
+ * absolute one where it climbs out. A run from a linked worktree serving the
+ * main root reports `../../teach`, which names the directory without giving a
+ * reader anything they can open.
+ */
+function displayPath(root: string): string {
+  const near = relative(process.cwd(), root)
+  if (near === '') return '.'
+  return near.startsWith('..') ? root : near
+}
+
+/**
+ * Undefined for a value that is not a port, distinct from an absent flag,
+ * which takes the default. A `Number` of a typo is `NaN`, and passing that on
+ * asks the runtime to bind a port nobody named.
+ */
+function parsePort(raw: string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_PORT
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0 || value > 65535) return undefined
+  return value
+}
+
+function report(outcome: ServeOutcome, emitJson: boolean): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, detail: outcome.detail })}\n`,
+      )
+      return 1
+    }
+    intro('aitk serve')
+    logError(outcome.detail)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root: outcome.root,
+        host: outcome.host,
+        port: outcome.port,
+        entry: outcome.entry,
+        url: outcome.url,
+        entryExists: outcome.entryExists,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk serve')
+  logStep('Serving')
+  logInfo(displayPath(outcome.root))
+  logStep('Open')
+  logInfo(outcome.url)
+
+  if (!outcome.entryExists) {
+    logStep('No entry page')
+    logWarn(
+      `${outcome.entry} is not in that directory, so the link opens a 404`,
+    )
+  }
+
+  logStep('Stop')
+  logInfo('Ctrl-C')
+  return 0
+}
+
+/**
+ * Resolves when the process is asked to stop. The frame is closed here rather
+ * than in the reporter, because the run is the serving rather than the start,
+ * and closing at start would print the frame's end while the server ran on.
+ */
+function waitForInterrupt(stop: () => Promise<void>): Promise<void> {
+  return new Promise((settle) => {
+    const finish = () => {
+      void stop().then(() => {
+        outro()
+        settle()
+      })
+    }
+    process.once('SIGINT', finish)
+    process.once('SIGTERM', finish)
+  })
+}

package/src/serve/static.ts

@@ -0,0 +1,322 @@
+import { existsSync, realpathSync, statSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+
+/**
+ * The loopback interface, never a wildcard bind. A preview serves whatever
+ * directory it is pointed at, and the folders this exists for are the
+ * gitignored record trees, so reaching the network is the one thing it must
+ * not do.
+ */
+export const SERVE_HOST = '127.0.0.1'
+
+/** Tried first, then the next ports in order, so a second preview still opens. */
+export const DEFAULT_PORT = 8787
+
+/** How far past the requested port to look before refusing. */
+const PORT_ATTEMPTS = 20
+
+const DEFAULT_ENTRY = 'index.html'
+
+/**
+ * Extensions a browser has to be told about. Anything absent is served as an
+ * octet stream, which downloads rather than renders, and that is the safe
+ * direction for a type this map does not claim to know.
+ */
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  css: 'text/css; charset=utf-8',
+  gif: 'image/gif',
+  htm: 'text/html; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  js: 'text/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  /**
+   * Plain text rather than `text/markdown`, which a browser offers to save
+   * instead of showing. A reader following a link to a source page wants to
+   * read it, and the rendered sibling is a separate file.
+   */
+  md: 'text/plain; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  txt: 'text/plain; charset=utf-8',
+  webp: 'image/webp',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+}
+
+export type ServeRefusal =
+  | 'no-root'
+  | 'not-a-directory'
+  | 'no-port'
+  | 'no-entry'
+  | 'bind-failed'
+
+export interface ServeRefused {
+  readonly ok: false
+  readonly reason: ServeRefusal
+  readonly detail: string
+}
+
+export interface ServeStarted {
+  readonly ok: true
+  /** Absolute, so a report names the directory rather than the caller's cwd. */
+  readonly root: string
+  readonly host: string
+  readonly port: number
+  /** The entry page relative to the root, as the URL spells it. */
+  readonly entry: string
+  /** What a reader clicks. Complete, including the entry page. */
+  readonly url: string
+  /** Whether the entry page exists. A missing one is reported, never fatal. */
+  readonly entryExists: boolean
+  readonly stop: () => Promise<void>
+}
+
+export type ServeOutcome = ServeStarted | ServeRefused
+
+export interface ServeOptions {
+  readonly port?: number
+  readonly entry?: string
+}
+
+function refuse(reason: ServeRefusal, detail: string): ServeRefused {
+  return { ok: false, reason, detail }
+}
+
+function contentType(path: string): string {
+  const dot = path.lastIndexOf('.')
+  if (dot === -1) return 'application/octet-stream'
+  const ext = path.slice(dot + 1).toLowerCase()
+  return CONTENT_TYPES[ext] ?? 'application/octet-stream'
+}
+
+/**
+ * Resolves a request path inside the root, or returns undefined when it escapes.
+ * The containment test compares resolved absolute paths rather than inspecting
+ * the request for `..`, because an encoded traversal survives a textual scan and
+ * does not survive resolution.
+ */
+export function resolveWithin(
+  root: string,
+  requestPath: string,
+): string | undefined {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(requestPath)
+  } catch {
+    return undefined
+  }
+  /**
+   * A NUL truncates the path at the filesystem layer, so a request carrying one
+   * asks for a different file than the one the containment test read.
+   */
+  if (decoded.includes('\0')) return undefined
+
+  const relativePath = decoded.replace(/^\/+/, '')
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + sep)) return undefined
+  return target
+}
+
+/**
+ * Re-tests containment after following symlinks. `resolveWithin` is lexical
+ * and `resolve` does not follow a link, so a link inside the root clears that
+ * test while the file it points at sits outside. This repository is a live
+ * instance, since `claude/standards` and `claude/snippets` are links out of
+ * `claude/`.
+ *
+ * Only a path that exists is checked, because a link can be followed only once
+ * there is something on the other end, and a path that resolves to nothing is
+ * a 404 rather than an escape.
+ */
+function escapesThroughLink(root: string, target: string): boolean {
+  if (!existsSync(target)) return false
+  try {
+    const realRoot = realpathSync(root)
+    const realTarget = realpathSync(target)
+    return realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)
+  } catch {
+    /* Unreadable resolves to no answer, and no answer is refused. */
+    return true
+  }
+}
+
+/**
+ * Whether a bind failure is contention worth trying the next port for.
+ *
+ * Lifted out of the loop so the decision is testable. Manufacturing a real
+ * non-contention bind failure needs a privileged port or an unavailable
+ * interface and neither travels between machines, where an error value does,
+ * so this is unit-tested and the bind itself is not.
+ */
+export function shouldWalkPast(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'EADDRINUSE'
+}
+
+/**
+ * Picks a listening port, starting at the requested one and walking forward.
+ * A busy port is the ordinary case rather than a failure, since a preview of
+ * one workspace is routinely open while another is started.
+ */
+function listen(
+  root: string,
+  first: number,
+): { server: ReturnType<typeof Bun.serve>; port: number } | undefined {
+  for (let port = first; port < first + PORT_ATTEMPTS; port++) {
+    try {
+      const server = Bun.serve({
+        hostname: SERVE_HOST,
+        port,
+        fetch: (request) => respond(root, request),
+      })
+      /**
+       * The bound port rather than the requested one. Port 0 asks the OS to
+       * choose, so reporting the request builds a URL pointing at nothing.
+       * The type admits undefined for a unix socket, which a bind carrying a
+       * hostname and a port never is, and the request is the honest fallback.
+       */
+      return { server, port: server.port ?? port }
+    } catch (error) {
+      /**
+       * Contention is the one cause worth walking past. A permission failure
+       * or an unavailable interface swallowed here would be retried twenty
+       * times and then reported as a port range being full, which names a
+       * cause nothing checked. `startServer` turns the rethrow into a refusal.
+       */
+      if (!shouldWalkPast(error)) throw error
+    }
+  }
+  return undefined
+}
+
+export async function respond(
+  root: string,
+  request: Request,
+): Promise<Response> {
+  const { pathname, search } = new URL(request.url)
+  const forbidden = () =>
+    new Response('Forbidden\n', {
+      status: 403,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+
+  const target = resolveWithin(root, pathname)
+  if (!target) return forbidden()
+
+  /**
+   * Tested here as well as before the read, because the redirect below answers
+   * ahead of that one. A redirect firing on an out-of-root directory reports
+   * that it exists, where one that does not answers 404, and the pair is a
+   * fact about the filesystem outside the root.
+   */
+  if (escapesThroughLink(root, target)) return forbidden()
+
+  let path = target
+  if (existsSync(path) && statSync(path).isDirectory()) {
+    /**
+     * A browser resolves a relative asset against the last slash of the URL it
+     * is on, so answering a directory in place leaves `/lesson` asking for
+     * `/course.css` rather than `/lesson/course.css` and the page renders
+     * unstyled. The redirect moves the base before the index is served.
+     */
+    if (!pathname.endsWith('/')) {
+      return new Response(null, {
+        status: 301,
+        headers: { location: `${pathname}/${search}` },
+      })
+    }
+    path = join(path, DEFAULT_ENTRY)
+  }
+
+  /**
+   * Sits immediately before the read rather than beside the path that produced
+   * it, so every path reaching `Bun.file` has been tested whatever produced
+   * it. Checking the request path alone left the appended index untested, and
+   * a real directory holding a linked index was served.
+   */
+  if (escapesThroughLink(root, path)) return forbidden()
+
+  const file = Bun.file(path)
+  if (!(await file.exists())) {
+    return new Response(`Not found: ${pathname}\n`, {
+      status: 404,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+  }
+
+  return new Response(file, {
+    headers: {
+      'content-type': contentType(path),
+      /**
+       * A preview is edited and reloaded continuously, and a cached stylesheet
+       * reads as a fix that did not work. Revalidation is the whole point of
+       * the surface, so it is not negotiable per response.
+       */
+      'cache-control': 'no-store',
+    },
+  })
+}
+
+export function startServer(
+  dir: string,
+  options: ServeOptions = {},
+): ServeOutcome {
+  const root = resolve(process.cwd(), dir)
+  if (!existsSync(root)) return refuse('no-root', `${dir} does not exist`)
+  if (!statSync(root).isDirectory())
+    return refuse('not-a-directory', `${dir} is not a directory`)
+
+  const entry = (options.entry ?? DEFAULT_ENTRY).replace(/^\/+/, '')
+
+  /**
+   * Checked before a port is taken, since `url` is the field a caller is told
+   * to read and hand to a reader. An entry the containment test rejects would
+   * otherwise be reported as a link the server then refuses. An entry that is
+   * merely absent is not this case and does not refuse, which `entryExists`
+   * reports instead.
+   */
+  const entryPath = resolveWithin(root, entry)
+  if (!entryPath) return refuse('no-entry', `${entry} escapes ${dir}`)
+
+  const first = options.port ?? DEFAULT_PORT
+
+  /**
+   * A bind failure that is not contention reaches here as a throw, and the
+   * command's own help promises a reason on stderr or in the record. A stack
+   * trace is neither, so it is caught and named.
+   */
+  let bound: ReturnType<typeof listen>
+  try {
+    bound = listen(root, first)
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
+    return refuse(
+      'bind-failed',
+      `could not bind ${SERVE_HOST}:${first} (${code})`,
+    )
+  }
+
+  if (!bound) {
+    return refuse(
+      'no-port',
+      `no free port between ${first} and ${first + PORT_ATTEMPTS - 1}`,
+    )
+  }
+
+  return {
+    ok: true,
+    root,
+    host: SERVE_HOST,
+    port: bound.port,
+    entry,
+    url: `http://${SERVE_HOST}:${bound.port}/${entry}`,
+    entryExists: existsSync(entryPath),
+    stop: async () => {
+      await bound.server.stop(true)
+    },
+  }
+}