docs: a guide, a wiki and screenshots

The README grew a section per feature and is a good reference, but nothing said where to begin. docs/wiki now has a getting-started page, a guide that walks through one day with the workspace and explains each part where it comes up, and a page per part of the app, each with screenshots of what it describes. Three pages are read out of the code rather than written, so they cannot drift from it: the keys and commands from Help.svelte and commands.ts, the same lists `:help` draws; the settings from .env.example, which gains a heading for the vault, trash and history settings so they no longer sit under mail; and the API from the README's table. `make wiki` writes them, and `--check` fails when one is stale or a link between pages leads nowhere. `--publish` lays the pages out for a GitHub wiki: links without `.md`, images beside them, `[[` escaped so the wiki does not take a command's help text for a link to a page. The screenshots are taken by `make screenshots`: the debug binary on a temporary data directory, with a password made up for the run, filled with an example workspace over the API, and a headless Chromium driven over the DevTools protocol through the views the docs show. Nothing outside the temporary directory is touched but docs/images, and the pictures are cut to 256 colours, a third of their size, which a dark UI does not show. The README opens with the banner, a CI badge, the guide, the features grouped by what they are for, and six of the screenshots.
2026-11-03 16:41:27 +01:00 · 2026-10-21 12:07:32 +02:00
1 parent 7b2fd5579c
commit 4eb663e2d7
@@ -0,0 +1,430 @@
+/*
+ * The screenshots in docs/images, taken again: `make screenshots`.
+ *
+ * Starts the debug binary on a data directory of its own, with a password made
+ * up for the run, fills it with a workspace that has something in every
+ * corner, and drives a headless Chromium over the DevTools protocol through
+ * the views the docs talk about. Nothing outside the temporary directory is
+ * read or written except docs/images. Needs `bun run build` in web/ and
+ * `cargo build` first, which the make target does.
+ */
+import { spawn, spawnSync, which, type Subprocess } from 'bun'
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const root = resolve(import.meta.dir, '..')
+const out = join(root, 'docs/images')
+const port = 4299
+const base = `http://127.0.0.1:${port}`
+const user = 'demo'
+const password = crypto.randomUUID()
+const dir = mkdtempSync(join(tmpdir(), 'workspace-shots-'))
+const chromium = process.env.CHROMIUM ?? 'chromium'
+
+const children: Subprocess[] = []
+function cleanup() {
+  for (const child of children) child.kill()
+  rmSync(dir, { recursive: true, force: true })
+}
+process.on('exit', cleanup)
+
+const sleep = (ms: number) => new Promise((done) => setTimeout(done, ms))
+
+async function waitFor(url: string) {
+  for (let i = 0; i < 100; i++) {
+    try {
+      if ((await fetch(url)).ok) return
+    } catch {
+      /* not up yet */
+    }
+    await sleep(200)
+  }
+  throw new Error(`${url} never answered`)
+}
+
+// --- the server --------------------------------------------------------------
+
+children.push(
+  spawn([join(root, 'target/debug/narl-workspace')], {
+    cwd: root,
+    env: {
+      ...process.env,
+      WORKSPACE_DATA_DIR: join(dir, 'data'),
+      WORKSPACE_BIND: `127.0.0.1:${port}`,
+      WORKSPACE_USER: user,
+      WORKSPACE_PASSWORD: password,
+      WORKSPACE_SECRET: crypto.randomUUID() + crypto.randomUUID(),
+      WORKSPACE_TIMEZONE: 'Europe/Berlin',
+      RUST_LOG: 'warn',
+    },
+    stdout: 'ignore',
+    stderr: 'inherit',
+  }),
+)
+await waitFor(`${base}/api/health`)
+
+const login = await fetch(`${base}/api/login`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ username: user, password }),
+})
+const cookie = (login.headers.get('set-cookie') ?? '').split(';')[0]
+if (!login.ok || !cookie) throw new Error(`login: ${login.status}`)
+const [cookieName, cookieValue] = cookie.split('=')
+
+async function api<T = any>(method: string, path: string, body?: unknown): Promise<T> {
+  const response = await fetch(`${base}/api${path}`, {
+    method,
+    headers: { cookie, 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${await response.text()}`)
+  return response.json() as Promise<T>
+}
+
+async function upload(parent: number, name: string, bytes: string | Uint8Array, type: string) {
+  const form = new FormData()
+  form.append('file', new File([bytes], name, { type }))
+  const response = await fetch(`${base}/api/nodes/${parent}/files`, { method: 'POST', headers: { cookie }, body: form })
+  if (!response.ok) throw new Error(`upload ${name}: ${response.status}`)
+}
+
+// --- the workspace -------------------------------------------------------------
+
+const day = 24 * 3600
+const midnight = new Date()
+midnight.setHours(0, 0, 0, 0)
+const today = Math.floor(midnight.getTime() / 1000)
+const at = (days: number, hour: number) => today + days * day + hour * 3600
+
+const doc = (parent_id: number, name: string, body: string, created_at?: number) =>
+  api('POST', '/nodes', { parent_id, name, body, created_at })
+const folder = (parent_id: number, name: string) => api('POST', '/nodes', { parent_id, name, kind: 'folder' })
+
+// A new database starts with diary, work and uni.
+const spaces = await api<{ id: number; slug: string }[]>('GET', '/spaces')
+const space = async (slug: string) =>
+  spaces.find((space) => space.slug === slug)?.id ?? (await api('POST', '/spaces', { name: slug })).id
+const diary = await space('diary')
+const work = await space('work')
+const uni = await space('uni')
+const home = await space('home')
+
+// work
+const projects = await folder(work, 'projects')
+const pipeline = await doc(
+  projects.id,
+  'Ingest pipeline',
+  `Moving the nightly import off cron and onto a queue, so a slow source no longer holds up the rest. See [[Runbook]] for how it is operated today.
+
+## Why
+
+- the cron job runs **every source in series**; one slow API delays all of them
+- a failed run is retried by hand, the next morning
+- nobody can tell from the outside how far a run has come
+
+## Shape
+
+| stage | owner | state |
+| --- | --- | --- |
+| fetch | worker pool | done |
+| parse | worker pool | in review |
+| store | one writer | open |
+
+\`\`\`rust
+async fn drain(queue: &Queue, store: &Store) -> anyhow::Result<()> {
+    while let Some(job) = queue.next().await? {
+        let rows = parse(&job.payload)?;
+        store.write(job.source, rows).await?;
+        queue.ack(job.id).await?;
+    }
+    Ok(())
+}
+\`\`\`
+
+## Throughput
+
+With $n$ sources of mean latency $\\bar t$, the serial run takes about $n \\bar t$; with $w$ workers it is closer to
+
+$$
+T \\approx \\frac{n \\bar t}{w} + t_{\\max}
+$$
+
+## Open questions
+
+1. Does the writer need a lock per source, or is one queue enough?
+2. Where does the dead-letter queue live?
+`,
+)
+await doc(projects.id, 'Search rewrite', `A sketch of the new search API.\n\nDepends on the [[Ingest pipeline]] landing first.\n`)
+const runbook = await doc(
+  work,
+  'Runbook',
+  `How the nightly import is operated until the [[Ingest pipeline]] replaces it.
+
+## When the import fails
+
+1. read the log of the run: \`journalctl -u import --since today\`
+2. re-run the one source that failed: \`import --source <name>\`
+3. write down what happened in the incident notes
+`,
+)
+// Two saves over the first text, so the runbook has a history to show.
+await api('PUT', `/nodes/${runbook.id}`, {
+  name: 'Runbook',
+  body: `How the nightly import is operated until the [[Ingest pipeline]] replaces it.
+
+## When the import fails
+
+1. read the log of the run: \`journalctl -u import --since today\`
+2. re-run the one source that failed: \`import --source <name> --resume\`
+3. if it fails twice, page the owner of that source
+4. write down what happened in the incident notes
+`,
+})
+const data = await folder(work, 'data')
+await upload(
+  data.id,
+  'throughput.csv',
+  'day,sources,rows,duration_s,failures\n' +
+    Array.from({ length: 14 }, (_, i) => `2026-10-${String(i + 1).padStart(2, '0')},${38 + (i % 3)},${120000 + i * 3150},${2400 - i * 61},${i % 5 === 0 ? 1 : 0}`).join('\n') +
+    '\n',
+  'text/csv',
+)
+await upload(
+  data.id,
+  'import-2026-10-14.log',
+  `2026-10-14T02:00:01Z INFO  import: 41 sources queued
+2026-10-14T02:00:03Z INFO  fetch: weather-api 200 in 812ms
+2026-10-14T02:03:47Z WARN  fetch: tariffs-api slow, 9.4s
+2026-10-14T02:04:12Z ERROR parse: tariffs-api: unexpected field "valid_from"
+2026-10-14T02:41:55Z INFO  import: 40 of 41 sources stored
+`,
+  'text/plain',
+)
+const certs = await folder(work, 'certificates')
+await upload(certs.id, 'gateway.pem', readFileSync(join(root, 'src/routes/testdata/cert.pem')), 'application/x-pem-file')
+const templates = await folder(work, 'templates')
+await doc(templates.id, 'meeting', `# {{title}}\n\n{{weekday}}, {{date}} at {{time}}\n\n## Agenda\n\n- \n\n## Decisions\n\n- \n`)
+
+const lists = (await api('GET', `/spaces/${work}/board`)).lists as { id: number; name: string }[]
+const [backlog, doing, done] = lists
+await api('POST', `/lists/${backlog.id}/cards`, { title: 'Renew the gateway certificate', due_at: at(-1, 12) })
+await api('POST', `/lists/${backlog.id}/cards`, { title: 'Write the dead-letter queue proposal', due_at: at(3, 12) })
+await api('POST', `/lists/${backlog.id}/cards`, { title: 'Ask ops about a staging queue' })
+const weekly = await api('POST', `/lists/${backlog.id}/cards`, { title: 'Weekly import report', due_at: at(0, 17) })
+await api('PUT', `/cards/${weekly.id}`, { repeat: 'weekly' })
+await api('POST', `/lists/${doing.id}/cards`, { title: 'Parse stage review', node_id: pipeline.id, due_at: at(1, 12) })
+await api('POST', `/lists/${doing.id}/cards`, { title: 'Benchmark the worker pool' })
+const finished = await api('POST', `/lists/${backlog.id}/cards`, { title: 'Move fetch onto the queue' })
+await api('POST', `/cards/${finished.id}/move`, { list_id: done.id })
+
+// uni
+const algebra = await folder(uni, 'linear algebra')
+await doc(
+  algebra.id,
+  'Eigenvalues',
+  `For a square matrix $A$, a scalar $\\lambda$ is an **eigenvalue** when there is a vector $v \\neq 0$ with $Av = \\lambda v$. They are the roots of
+
+$$
+\\det(A - \\lambda I) = 0
+$$
+
+## Example
+
+$$
+A = \\begin{pmatrix} 2 & 1 \\\\ 1 & 2 \\end{pmatrix}
+\\quad\\Rightarrow\\quad
+\\lambda_1 = 3,\\; \\lambda_2 = 1
+$$
+
+The trace is the sum of the eigenvalues, $\\operatorname{tr} A = 4$, and the determinant their product, $\\det A = 3$.
+`,
+)
+await doc(algebra.id, 'Exercise sheet 4', `- [x] 4.1 characteristic polynomial\n- [x] 4.2 diagonalise\n- [ ] 4.3 Jordan form\n`)
+const thesis = await folder(uni, 'thesis')
+await doc(thesis.id, 'Outline', `## Chapters\n\n1. Introduction\n2. Related work\n3. Method\n4. Evaluation\n`)
+const uniLists = (await api('GET', `/spaces/${uni}/board`)).lists as { id: number }[]
+await api('POST', `/lists/${uniLists[0].id}/cards`, { title: 'Hand in exercise sheet 4', due_at: at(2, 10) })
+
+// home
+await doc(home, 'Groceries', `- oat milk\n- coffee\n- lemons\n`)
+await api('PUT', `/nodes/${home}`, { name: 'home', has_board: false })
+
+// diary
+const entries: [number, string, string][] = [
+  [-1, 'Queue day', 'Fetch runs on the queue now. The tariffs source still fails on a new field.'],
+  [-2, 'Long run', 'Ten kilometres along the river, slower than last week and better for it.'],
+  [-3, 'Sheet 4', 'Diagonalised everything in sight. Jordan form tomorrow.'],
+  [-5, 'Rain', 'Stayed in and read.'],
+  [-8, 'Planning', 'Wrote down why the nightly import should move to a queue.'],
+  [-12, 'Market', 'Lemons, coffee, a plant that will not survive the winter.'],
+  [-365, 'A year ago', 'First entry in the new workspace.'],
+]
+for (const [offset, name, body] of entries) await doc(diary, name, body + '\n', at(offset, 20))
+
+// --- the browser ----------------------------------------------------------------
+
+const profile = join(dir, 'chromium')
+children.push(
+  spawn(
+    [chromium, '--headless=new', '--remote-debugging-port=9333', `--user-data-dir=${profile}`, '--hide-scrollbars', '--no-first-run', 'about:blank'],
+    { stdout: 'ignore', stderr: 'ignore' },
+  ),
+)
+await waitFor('http://127.0.0.1:9333/json/version')
+const targets = (await (await fetch('http://127.0.0.1:9333/json/list')).json()) as { type: string; webSocketDebuggerUrl: string }[]
+const socket = new WebSocket(targets.find((target) => target.type === 'page')!.webSocketDebuggerUrl)
+await new Promise((ready) => socket.addEventListener('open', ready, { once: true }))
+
+let next = 0
+const pending = new Map<number, (value: any) => void>()
+socket.addEventListener('message', (event) => {
+  const message = JSON.parse(String(event.data))
+  if (message.id !== undefined) pending.get(message.id)?.(message.result ?? message.error)
+})
+function send(method: string, params: object = {}): Promise<any> {
+  const id = ++next
+  socket.send(JSON.stringify({ id, method, params }))
+  return new Promise((done) => pending.set(id, done))
+}
+
+async function viewport(width: number, height: number, mobile = false) {
+  await send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: mobile ? 3 : 2, mobile })
+  await send('Emulation.setTouchEmulationEnabled', { enabled: mobile, maxTouchPoints: mobile ? 5 : 0 })
+  await send('Emulation.setEmitTouchEventsForMouse', { enabled: mobile })
+}
+
+async function open(path: string, signedIn = true) {
+  await send('Network.clearBrowserCookies')
+  if (signedIn) await send('Network.setCookie', { name: cookieName, value: cookieValue, url: base })
+  await send('Page.navigate', { url: base + path })
+  await sleep(1500)
+}
+
+const named: Record<string, { code: string; keyCode: number }> = {
+  Escape: { code: 'Escape', keyCode: 27 },
+  Enter: { code: 'Enter', keyCode: 13 },
+  Tab: { code: 'Tab', keyCode: 9 },
+}
+
+/** Keys as typed: `gh`, `?`, `<Escape>` for a named one, `<A-h>` with Alt. */
+async function keys(sequence: string, pause = 250) {
+  for (const token of sequence.match(/<A-\w>|<\w+>|./g) ?? []) {
+    if (token.startsWith('<A-')) {
+      const key = token[3]
+      const params = { key, code: `Key${key.toUpperCase()}`, modifiers: 1 }
+      await send('Input.dispatchKeyEvent', { type: 'rawKeyDown', ...params })
+      await send('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
+    } else if (token.startsWith('<')) {
+      const key = token.slice(1, -1)
+      const { code, keyCode } = named[key]
+      const text = key === 'Enter' ? '\r' : undefined
+      await send('Input.dispatchKeyEvent', { type: 'keyDown', key, code, windowsVirtualKeyCode: keyCode, text })
+      await send('Input.dispatchKeyEvent', { type: 'keyUp', key, code, windowsVirtualKeyCode: keyCode })
+    } else {
+      const upper = token !== token.toLowerCase()
+      const code = /[a-z]/i.test(token) ? `Key${token.toUpperCase()}` : undefined
+      const params = { key: token, code, text: token, modifiers: upper ? 8 : 0 }
+      await send('Input.dispatchKeyEvent', { type: 'keyDown', ...params })
+      await send('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
+    }
+    await sleep(pause)
+  }
+}
+
+async function shot(name: string) {
+  await sleep(600)
+  const { data } = await send('Page.captureScreenshot', { format: 'png' })
+  const file = join(out, `${name}.png`)
+  writeFileSync(file, Buffer.from(data, 'base64'))
+  // A dark UI fits in 256 colours at a third of the size; skipped without ImageMagick.
+  if (which('magick')) spawnSync(['magick', file, '-dither', 'None', '-colors', '256', '-define', 'png:compression-level=9', `PNG8:${file}`])
+  console.log(`docs/images/${name}.png`)
+}
+
+await send('Page.enable')
+await send('Network.enable')
+// The agenda opens itself once a day; here it opens when asked.
+await send('Page.addScriptToEvaluateOnNewDocument', {
+  source: `localStorage.setItem('diary:agenda-seen', new Date().toDateString())`,
+})
+
+await viewport(1440, 900)
+
+await open('/', false)
+await shot('login')
+
+await open('/n/work/projects/ingest-pipeline')
+await shot('document')
+
+// From the folder: the pipeline in the focused tile, the rewrite beside it.
+await open('/n/work/projects')
+await keys('jl')
+await sleep(800)
+await keys('<A-h>kL')
+await sleep(800)
+await shot('tiles')
+
+await open('/n/work/runbook')
+await keys('gh', 400)
+await sleep(800)
+await shot('history')
+
+await open('/n/work/runbook')
+await keys('i')
+await sleep(500)
+await shot('editor')
+
+await open('/n/uni/linear-algebra/eigenvalues')
+await shot('math')
+
+await open('/n/work')
+await keys('b')
+await sleep(800)
+await shot('board')
+
+await keys('t')
+await sleep(800)
+await shot('agenda')
+await keys('<Escape>')
+
+await open('/n/diary')
+await keys('C')
+await sleep(800)
+await shot('calendar')
+await keys('<Escape>')
+
+await open('/n/work')
+await keys('/')
+await send('Input.insertText', { text: 'tariffs' })
+await sleep(300)
+await keys('<Enter>')
+await sleep(800)
+await shot('search')
+
+await open('/n/work/data/throughput-csv')
+await shot('file-table')
+
+await open('/n/work/certificates/gateway-pem')
+await shot('file-certificate')
+
+await open('/n/work')
+await keys('w')
+await sleep(800)
+await shot('overview')
+await keys('<Escape>')
+
+await keys('?')
+await sleep(800)
+await shot('help')
+
+await viewport(390, 844, true)
+await open('/n/work/projects/ingest-pipeline')
+await shot('mobile-document')
+await open('/n/work')
+await shot('mobile-tree')
+
+socket.close()
+process.exit(0)
@@ -0,0 +1,274 @@
+/*
+ * The wiki, from the files it describes: `make wiki`.
+ *
+ * docs/wiki holds the pages. Three of them are not written by hand but read
+ * out of the code, so they cannot drift from it:
+ *
+ * - Commands.md, from the keys in Help.svelte and the commands in commands.ts,
+ *   the same lists `:help` draws;
+ * - Configuration.md, from the comments and values in .env.example;
+ * - API.md, from the API section of README.md.
+ *
+ * `bun scripts/wiki.ts` writes those three and checks that every link between
+ * pages and every image resolves. `--publish <dir>` also lays the wiki out for
+ * GitHub: links without `.md`, images beside the pages, a footer saying where
+ * the pages come from. CI does that on every push to main and pushes the result
+ * to the wiki repository; `--check` fails when a generated page is stale.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const root = resolve(import.meta.dir, '..')
+const pages = join(root, 'docs/wiki')
+const images = join(root, 'docs/images')
+const repo = process.env.GITHUB_REPOSITORY ?? 'narrrl/narl-workspace'
+const read = (path: string) => readFileSync(join(root, path), 'utf8')
+
+const args = process.argv.slice(2)
+const check = args.includes('--check')
+const publish = args.includes('--publish') ? args[args.indexOf('--publish') + 1] : undefined
+if (args.includes('--publish') && !publish) throw new Error('--publish needs a directory')
+
+const generated = (source: string) =>
+  `<!-- Generated by scripts/wiki.ts from ${source}. Edit that, then run \`make wiki\`. -->\n\n`
+
+/** A JS string literal's value: `'it\'s'` or `"it's"`. */
+function unquote(literal: string): string {
+  return literal.slice(1, -1).replace(/\\(.)/g, '$1')
+}
+const STRING = `('(?:[^'\\\\]|\\\\.)*'|"(?:[^"\\\\]|\\\\.)*")`
+
+/** `|` inside a table cell would end it, and a GitHub wiki reads `[[x]]` as a link to page x. */
+const cell = (text: string) => text.replace(/\|/g, '\\|').replace(/\[\[/g, '\\[\\[')
+/** A key or command as code, safe in a table even when it holds a backtick. */
+const code = (text: string) => (text.includes('`') ? `<code>${cell(text).replace(/</g, '&lt;')}</code>` : `\`${cell(text)}\``)
+
+// --- Commands.md ---------------------------------------------------------------
+
+function keyTable(source: string, name: string): string {
+  const start = source.indexOf(`const ${name}: [string, string][] = [`)
+  if (start < 0) throw new Error(`Help.svelte has no ${name}`)
+  const body = source.slice(start, source.indexOf('\n  ]', start))
+  const pairs = [...body.matchAll(new RegExp(`\\[${STRING}, ${STRING}\\]`, 'g'))].map(([, key, description]) => [unquote(key), unquote(description)])
+  if (pairs.length === 0) throw new Error(`Help.svelte: ${name} is empty`)
+  // `rule` is not a key but the sentence the help column starts with.
+  const rule = pairs.find(([key]) => key === 'rule')
+  const rows = pairs.filter(([key]) => key !== 'rule').map(([key, description]) => `| ${code(key)} | ${cell(description)} |`)
+  const table = ['| key | what it does |', '| --- | --- |', ...rows].join('\n')
+  return rule ? `${rule[1][0].toUpperCase()}${rule[1].slice(1)}.\n\n${table}` : table
+}
+
+interface Spec {
+  name: string
+  aliases: string[]
+  args?: string
+  group: string
+  help: string
+  bang?: string
+}
+
+function commandSpecs(source: string): Spec[] {
+  const start = source.indexOf('export const commands: CommandSpec[] = [')
+  const end = source.indexOf('\n]\n', start)
+  // Every command is an object literal opened on a line of its own, two in.
+  const blocks = source.slice(start, end).split('\n  {\n').slice(1)
+  const field = (block: string, name: string, indent = 4) =>
+    new RegExp(`^${' '.repeat(indent)}${name}: ${STRING},?$`, 'm').exec(block)?.[1]
+  return blocks.map((block) => {
+    const name = field(block, 'name')
+    const group = field(block, 'group')
+    const help = field(block, 'help')
+    if (!name || !group || !help) throw new Error(`commands.ts: a command without a name, group or help:\n${block.slice(0, 200)}`)
+    const aliases = /^    aliases: \[(.*)\],$/m.exec(block)?.[1]
+    const bang = /^    bang: \{/m.test(block) ? field(block, 'help', 6) : undefined
+    const args = field(block, 'args')
+    return {
+      name: unquote(name),
+      group: unquote(group),
+      help: unquote(help),
+      aliases: aliases ? [...aliases.matchAll(new RegExp(STRING, 'g'))].map(([literal]) => unquote(literal)) : [],
+      args: args && unquote(args),
+      bang: bang && unquote(bang),
+    }
+  })
+}
+
+function commandsPage(): string {
+  const help = read('web/src/lib/Help.svelte')
+  const source = read('web/src/lib/commands.ts')
+  const groups = [.../export const groups = \[(.*)\] as const/.exec(source)![1].matchAll(new RegExp(STRING, 'g'))].map(([g]) => unquote(g))
+  const titles = Object.fromEntries(
+    [...help.matchAll(new RegExp(`^    (\\w+): ${STRING},$`, 'gm'))].map(([, group, title]) => [group, unquote(title)]),
+  )
+  const specs = commandSpecs(source)
+
+  const sections = groups.map((group) => {
+    const rows = specs
+      .filter((spec) => spec.group === group)
+      .flatMap((spec) => {
+        const names = [spec.name, ...spec.aliases].map((name) => `:${name}`).join(', ')
+        const usage = spec.args ? `${names} ${spec.args}` : names
+        const row = `| ${code(usage)} | ${cell(spec.help)} |`
+        return spec.bang ? [row, `| ${code(`:${spec.name}!`)} | ${cell(spec.bang)} |`] : [row]
+      })
+    const title = titles[group] ?? group
+    return `### ${title[0].toUpperCase()}${title.slice(1)}\n\n| command | what it does |\n| --- | --- |\n${rows.join('\n')}`
+  })
+
+  return (
+    generated('web/src/lib/Help.svelte and web/src/lib/commands.ts') +
+    `# Keys and commands
+
+Everything here is also on \`?\` (\`:help\`) inside the app, which draws the same
+lists. Keys act on whatever has focus: the row under the cursor in the list, or
+the document in the focused tile. Inside the editor the full vim keymap is live,
+and \`:\` opens the command line, where \`Tab\` completes commands and their
+arguments and \`↑\` / \`↓\` recall earlier lines.
+
+## Keys
+
+### Browsing and reading
+
+${keyTable(help, 'keys')}
+
+### On a board
+
+${keyTable(help, 'boardKeys')}
+
+### In the agenda
+
+${keyTable(help, 'agendaKeys')}
+
+## Commands
+
+A command takes a \`!\` for its forcing variant where one exists, the way vim's
+do: \`:w!\`, \`:space! <name>\`, \`:import!\`.
+
+${sections.join('\n\n')}
+`
+  )
+}
+
+// --- Configuration.md -------------------------------------------------------------
+
+function configurationPage(): string {
+  const lines = read('.env.example').split('\n')
+  const out: string[] = []
+  let comment: string[] = []
+  let table: string[] = []
+  const flush = () => {
+    if (table.length) out.push('| setting | example | what it does |', '| --- | --- | --- |', ...table, '')
+    table = []
+  }
+  for (const line of lines) {
+    const section = /^# --- (.+?) -+$/.exec(line)
+    const setting = /^(?:# )?(WORKSPACE_\w+)=(.*)$/.exec(line)
+    if (section) {
+      flush()
+      out.push(`## ${section[1]}`, '')
+      comment = []
+    } else if (setting) {
+      const [, name, value] = setting
+      // A comment above two settings belongs to both: USER and PASSWORD.
+      const text = comment.join(' ').replace(/\s+/g, ' ').trim() || 'See the row above.'
+      const unset = line.startsWith('#') && !/off until/i.test(text) ? ' Unset by default.' : ''
+      table.push(`| \`${name}\` | ${value ? `\`${cell(value)}\`` : ''} | ${cell(text)}${unset} |`)
+      comment = []
+    } else if (line.startsWith('#')) {
+      comment.push(line.replace(/^# ?/, ''))
+    } else if (line.trim() === '') {
+      // A blank line ends a paragraph that belonged to no single setting.
+      if (comment.length && table.length === 0 && out.length) out.push(comment.join(' ').trim(), '')
+      comment = []
+    }
+  }
+  flush()
+  return (
+    generated('.env.example') +
+    `# Configuration
+
+Every setting is an environment variable, read at start, usually from a \`.env\`
+file beside the binary (\`cp .env.example .env\`). The older \`DIARY_<NAME>\`
+spelling of each is still accepted. A value that is set but cannot be read stops
+the start with the reason rather than falling back to the default.
+
+## Basics
+
+${out.join('\n').trim()}
+`
+  )
+}
+
+// --- API.md -----------------------------------------------------------------------
+
+function apiPage(): string {
+  const readme = read('README.md')
+  const start = readme.indexOf('\n## API\n')
+  const end = readme.indexOf('\n## ', start + 1)
+  if (start < 0) throw new Error('README.md has no API section')
+  return generated('the API section of README.md') + '# API\n' + readme.slice(start + '\n## API\n'.length, end).trimEnd() + '\n'
+}
+
+// --- writing, checking, publishing -----------------------------------------------
+
+const outputs: Record<string, string> = {
+  'Commands.md': commandsPage(),
+  'Configuration.md': configurationPage(),
+  'API.md': apiPage(),
+}
+
+let stale = false
+for (const [name, text] of Object.entries(outputs)) {
+  const path = join(pages, name)
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  if (before === text) continue
+  if (check) {
+    console.error(`docs/wiki/${name} is out of date: run \`make wiki\``)
+    stale = true
+  } else {
+    writeFileSync(path, text)
+    console.log(`docs/wiki/${name}`)
+  }
+}
+
+const names = readdirSync(pages).filter((name) => name.endsWith('.md'))
+const broken: string[] = []
+for (const name of names) {
+  // Code shows links as examples; only the prose around it links.
+  const text = readFileSync(join(pages, name), 'utf8')
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]*`/g, '')
+  for (const [, target] of text.matchAll(/\]\(([^)\s]+)\)/g)) {
+    if (/^(https?:|mailto:|#)/.test(target)) continue
+    const path = target.split('#')[0]
+    const exists = path.startsWith('../') ? existsSync(join(pages, path)) : names.includes(path)
+    if (!exists) broken.push(`docs/wiki/${name}: ${target}`)
+  }
+}
+if (broken.length) {
+  console.error(`links that lead nowhere:\n  ${broken.join('\n  ')}`)
+  process.exit(1)
+}
+if (stale) process.exit(1)
+
+if (publish) {
+  const dir = resolve(publish)
+  // Everything but the wiki's own git directory is ours to replace.
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) if (entry !== '.git') rmSync(join(dir, entry), { recursive: true })
+  }
+  mkdirSync(dir, { recursive: true })
+  cpSync(images, join(dir, 'images'), { recursive: true })
+  for (const name of names) {
+    const text = readFileSync(join(pages, name), 'utf8')
+      .replace(/\]\(\.\.\/images\//g, '](images/')
+      .replace(/\]\(\.\.\/\.\.\/([^)]+)\)/g, `](https://github.com/${repo}/blob/main/$1)`)
+      .replace(/\]\(([\w-]+)\.md(#[^)]*)?\)/g, (_, page, anchor = '') => `](${page}${anchor})`)
+    writeFileSync(join(dir, name), text)
+  }
+  writeFileSync(
+    join(dir, '_Footer.md'),
+    `Written in [\`docs/wiki\`](https://github.com/${repo}/tree/main/docs/wiki) and published by CI on every push to main; an edit made here is overwritten by the next one.\n`,
+  )
+  console.log(`wiki laid out in ${dir}`)
+}