k0-board 0.1.0

package/web/fuzzy.js

@@ -0,0 +1,57 @@
+// ── Searching the names ───────────────────────────────────────────────────────
+// It does not look for the exact word: it looks for the letters you typed, in the order you
+// typed them, scattered through the path. So `audrep` finds `docs/audit-report.md` and `bapl`
+// finds `docs/backlog/plans/`.
+//
+// The score exists to put what you actually meant at the top. Worth more: a letter next to the
+// previous one, a letter at the start of a word, and anything in the file's name rather than in
+// the directory — because you usually reach a file through its name, not through where it is.
+
+const BOUNDARY = new Set(['/', '-', '_', '.', ' '])
+
+/**
+ * How much `text` looks like `query`: the higher, the more alike. `-1` when the letters simply
+ * are not there. With an empty search it is 0 for everybody, and the caller decides the order.
+ */
+export function score(text, query) {
+  const q = String(query ?? '').trim().toLowerCase().replace(/\s+/g, '')
+  if (!q) return 0
+  const s = String(text ?? '')
+  const low = s.toLowerCase()
+
+  // Where the file name starts: from there on every hit is worth more.
+  const nameAt = s.lastIndexOf('/') + 1
+
+  let total = 0
+  let at = 0
+  let last = -2
+  for (const ch of q) {
+    const hit = low.indexOf(ch, at)
+    if (hit === -1) return -1
+
+    let point = 1
+    if (hit === last + 1) point += 4 // next to the previous one
+    if (hit === 0 || BOUNDARY.has(s[hit - 1])) point += 3 // the start of a word
+    else if (s[hit] >= 'A' && s[hit] <= 'Z') point += 2 // the start of a word in camelCase
+    if (hit >= nameAt) point += 2 // in the file name, not the directory
+
+    total += point
+    last = hit
+    at = hit + 1
+  }
+
+  // On equal hits the shorter name wins: there is less around what you were looking for.
+  return total - s.length * 0.01
+}
+
+/** The rows that match, most alike first. `key` says where to look. */
+export function search(items, query, key = (x) => x, limit = 200) {
+  if (!String(query ?? '').trim()) return items.slice(0, limit)
+  const hits = []
+  for (const item of items) {
+    const s = score(key(item), query)
+    if (s >= 0) hits.push({ item, s })
+  }
+  hits.sort((a, b) => b.s - a.s)
+  return hits.slice(0, limit).map((h) => h.item)
+}

package/web/index.html

@@ -0,0 +1,112 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>k0 — Dashboard</title>
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/board.css">
+</head>
+<body>
+  <header class="topbar">
+    <h1>k0</h1>
+    <button class="new" id="new-card" title="New card" aria-label="New card">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
+    </button>
+    <div class="filters" id="filters"></div>
+
+    <!-- How the computer is doing. Always visible; clicking it switches off the weights on the cards. -->
+    <button class="gauge" id="gauge" type="button" hidden></button>
+
+    <!-- The four modes: how awake the machine has to stay. It is a scale, not four switches —
+         sleep, away, nerd, driving, each one including the one before it — and exactly one is
+         always lit. Clicking the lit one again does nothing: to leave it you go to another. It
+         sits at the end of the bar, where driving mode used to be. -->
+    <div class="modes" id="modes" role="radiogroup" aria-label="Wake mode">
+      <button type="button" role="radio" data-mode="sleep" aria-checked="false" title="Sleep" aria-label="Sleep">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 4h5l-5 6h5"/><path d="M4 12h8l-8 8h8"/></svg>
+      </button>
+      <button type="button" role="radio" data-mode="away" aria-checked="false" title="Away" aria-label="Away">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11.6 21.5c0-4.6.8-8.2 2.1-11.2"/><path d="M13.7 10.3c-2.5-1.7-5.4-1.5-7.5.4"/><path d="M13.7 10.3c-1.4-2.7-3.8-4.1-6.4-3.9"/><path d="M13.7 10.3c.4-3 2.3-5.2 4.9-5.8"/><path d="M13.7 10.3c2.6-1.2 5.4-.6 7.2 1.4"/></svg>
+      </button>
+      <button type="button" role="radio" data-mode="nerd" aria-checked="false" title="Nerd" aria-label="Nerd">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9.5"/><circle cx="8.2" cy="10.4" r="2.8"/><circle cx="15.8" cy="10.4" r="2.8"/><path d="M11 10.4h2"/><path d="M8.6 16.4q3.4 2 6.8 0"/></svg>
+      </button>
+      <button type="button" role="radio" data-mode="driving" aria-checked="false" title="Driving" aria-label="Driving">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 17h14"/><path d="M4 17v-4.2a2 2 0 0 1 .2-.9l1.9-3.8A2 2 0 0 1 7.9 7h8.2a2 2 0 0 1 1.8 1.1l1.9 3.8a2 2 0 0 1 .2.9V17"/><path d="M4 17v2h2v-2"/><path d="M18 17v2h2v-2"/><circle cx="7.5" cy="13.5" r="1"/><circle cx="16.5" cy="13.5" r="1"/></svg>
+      </button>
+    </div>
+  </header>
+
+  <main id="viewport" class="viewport">
+    <div id="board" class="board"></div>
+    <p class="empty" id="empty">The dashboard is empty. Add your first card.</p>
+
+    <!-- Where the board continues past the edge: with no scrollbars, it is the only way to tell. -->
+    <div class="edges" id="edges" aria-hidden="true"><i class="l"></i><i class="r"></i><i class="t"></i><i class="b"></i></div>
+
+    <div class="zoom" id="zoom">
+      <button type="button" id="z-out" title="Zoom out" aria-label="Zoom out">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 12h14"/></svg>
+      </button>
+      <button type="button" id="z-level" title="Back to 100%">100%</button>
+      <button type="button" id="z-in" title="Zoom in" aria-label="Zoom in">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
+      </button>
+      <button type="button" id="z-fit" title="Fit the whole board on screen" aria-label="Fit to screen">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5"/></svg>
+      </button>
+    </div>
+  </main>
+
+  <dialog id="editor">
+    <form id="editor-form">
+      <div class="head">
+        <h2 id="editor-title">New card</h2>
+        <button type="button" id="f-close" class="x" title="Close" aria-label="Close">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18"/></svg>
+        </button>
+      </div>
+
+      <label>Repository
+        <div class="picker">
+          <input id="f-project" autocomplete="off" placeholder="search a repository…">
+          <div class="picker-list" id="f-project-list" hidden></div>
+        </div>
+      </label>
+
+      <label>Title
+        <input id="f-title" required autocomplete="off" spellcheck="false" placeholder="Fix-Login-Bug">
+        <small>this is also the session name</small>
+      </label>
+
+      <label>Description
+        <textarea id="f-desc" rows="2" placeholder="a line or two about this session"></textarea>
+      </label>
+
+      <label>What Claude should do when it starts
+        <textarea id="f-prompt" rows="6" placeholder="you can leave this empty"></textarea>
+      </label>
+
+      <footer>
+        <button type="button" id="f-delete" class="danger">Delete</button>
+        <span class="spacer"></span>
+        <button type="submit" id="f-save">Save</button>
+        <button type="button" id="f-start" class="primary">Start</button>
+      </footer>
+    </form>
+  </dialog>
+
+  <dialog id="confirm" class="ask">
+    <p id="confirm-text"></p>
+    <footer>
+      <span class="spacer"></span>
+      <button type="button" id="confirm-no">Cancel</button>
+      <button type="button" id="confirm-yes" class="destructive">Delete</button>
+    </footer>
+  </dialog>
+
+  <div id="toast" class="toast"></div>
+  <script type="module" src="/board.js"></script>
+</body>
+</html>

package/web/md.js

@@ -0,0 +1,238 @@
+// ── Markdown ──────────────────────────────────────────────────────────────────
+// A small layout engine, written by hand because k0 has no dependencies and nothing to
+// compile. It covers what documents actually contain: headings, lists — including the ones with
+// checkboxes, which is the shape an archived plan takes — tables, quotes, code blocks, and
+// inline bold, italic, strikethrough and links.
+//
+// The order matters. First every piece of HTML is escaped, so nothing in the file can become a
+// tag; then the pieces that need protecting — code and links — are set aside and put back at
+// the end, otherwise a `**x**` inside code would come out bold.
+
+export const esc = (s) =>
+  String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))
+
+/**
+ * The header block between two lines of nothing but dashes, the way Claude Code's skills and
+ * plans write it. It is not text of the document: it is its label, and it should be read as
+ * one — the title becomes the name of the page, not just another paragraph.
+ * Returns `{ data, body }`; with no header, `data` is empty and `body` is everything.
+ */
+export function matter(md) {
+  const text = String(md ?? '').replace(/\0/g, '').replace(/\r\n?/g, '\n')
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text)
+  if (!m) return { data: {}, body: text }
+
+  const data = {}
+  for (const line of m[1].split('\n')) {
+    // Only `key: value` on one line. The rest — lists, nesting — is of no use here, and
+    // trying would mean writing a whole YAML parser.
+    const kv = /^([A-Za-z_][\w -]*):\s*(.*)$/.exec(line)
+    if (!kv) continue
+    data[kv[1].trim().toLowerCase()] = kv[2].trim().replace(/^["'](.*)["']$/s, '$1')
+  }
+  return { data, body: text.slice(m[0].length) }
+}
+
+/** The title written in the header, whatever it was called. */
+export const titleOf = (data) => data.title || data.name || null
+
+/**
+ * `md` is the text, `link(target, kind)` decides where a reference leads: the viewer needs it
+ * to point images at the real bytes and links at the other documents.
+ */
+export function render(md, link = (t) => t) {
+  const lines = matter(md).body.split('\n')
+
+  const out = []
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+
+    if (!line.trim()) {
+      i++
+      continue
+    }
+
+    // A code fence: nothing inside is looked at, it is simply copied.
+    const fence = /^\s*(```+|~~~+)\s*(\S*)/.exec(line)
+    if (fence) {
+      const close = fence[1][0]
+      const body = []
+      i++
+      while (i < lines.length && !new RegExp(`^\\s*${close}{3,}\\s*$`).test(lines[i])) body.push(lines[i++])
+      i++ // the closing line
+      const lang = fence[2] ? ` class="lang-${esc(fence[2])}"` : ''
+      out.push(`<pre><code${lang}>${esc(body.join('\n'))}</code></pre>`)
+      continue
+    }
+
+    const head = /^(#{1,6})\s+(.*)$/.exec(line)
+    if (head) {
+      const n = head[1].length
+      out.push(`<h${n}>${inline(head[2].replace(/\s+#+\s*$/, ''), link)}</h${n}>`)
+      i++
+      continue
+    }
+
+    if (/^\s{0,3}([-*_])\s*(\1\s*){2,}$/.test(line)) {
+      out.push('<hr>')
+      i++
+      continue
+    }
+
+    if (/^\s{0,3}>/.test(line)) {
+      const body = []
+      while (i < lines.length && (/^\s{0,3}>/.test(lines[i]) || (body.length && lines[i].trim()))) {
+        body.push(lines[i++].replace(/^\s{0,3}>\s?/, ''))
+      }
+      out.push(`<blockquote>${render(body.join('\n'), link)}</blockquote>`)
+      continue
+    }
+
+    if (ITEM.test(line)) {
+      const items = []
+      while (i < lines.length && (ITEM.test(lines[i]) || (items.length && lines[i].trim() && /^\s{2,}/.test(lines[i])))) {
+        const m = ITEM.exec(lines[i])
+        if (m) items.push({ indent: m[1].length, ordered: /\d/.test(m[2]), text: m[3] })
+        // A continuation line: it belongs to the last item.
+        else items[items.length - 1].text += ` ${lines[i].trim()}`
+        i++
+      }
+      // One pass is usually enough. A second is only needed when a list starts indented and
+      // then comes back to the left: those items are a list of their own.
+      for (let k = 0; k < items.length; ) {
+        const built = nest(items, k, link)
+        out.push(built.html)
+        k = built.i
+      }
+      continue
+    }
+
+    if (line.includes('|') && i + 1 < lines.length && isRule(lines[i + 1])) {
+      const header = cells(line)
+      const align = cells(lines[i + 1]).map((c) => (c.startsWith(':') && c.endsWith(':') ? 'center' : c.endsWith(':') ? 'right' : ''))
+      i += 2
+      const rows = []
+      while (i < lines.length && lines[i].includes('|') && lines[i].trim()) rows.push(cells(lines[i++]))
+      const th = header.map((c, k) => `<th${style(align[k])}>${inline(c, link)}</th>`).join('')
+      const tb = rows
+        .map((r) => `<tr>${r.map((c, k) => `<td${style(align[k])}>${inline(c, link)}</td>`).join('')}</tr>`)
+        .join('')
+      out.push(`<table><thead><tr>${th}</tr></thead><tbody>${tb}</tbody></table>`)
+      continue
+    }
+
+    // A paragraph runs until something else starts. The lines are joined: documents wrap at
+    // seventy characters, and breaking there for real would cut every sentence in half.
+    const para = []
+    while (i < lines.length && lines[i].trim() && !starts(lines[i])) para.push(lines[i++])
+    out.push(`<p>${inline(para.join('\n'), link)}</p>`)
+  }
+  return out.join('\n')
+}
+
+const ITEM = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/
+const style = (a) => (a ? ` style="text-align:${a}"` : '')
+const cells = (line) => line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim())
+const isRule = (line) => {
+  const c = cells(line)
+  return c.length > 0 && c.every((x) => /^:?-{1,}:?$/.test(x))
+}
+
+/** The lines that open a different block, and so close the paragraph in progress. */
+const starts = (l) =>
+  /^\s*(```|~~~)/.test(l) || /^#{1,6}\s/.test(l) || /^\s{0,3}>/.test(l) || ITEM.test(l) || /^\s{0,3}([-*_])\s*(\1\s*){2,}$/.test(l)
+
+/** Lists nest by indentation: everything further right is taken. */
+function nest(items, from, link) {
+  const indent = items[from].indent
+  const ordered = items[from].ordered
+  const parts = []
+  let i = from
+  while (i < items.length && items[i].indent >= indent) {
+    if (items[i].indent > indent) {
+      const inner = nest(items, i, link)
+      parts[parts.length - 1] += inner.html
+      i = inner.i
+      continue
+    }
+    parts.push(item(items[i].text, link))
+    i++
+  }
+  const tag = ordered ? 'ol' : 'ul'
+  return { html: `<${tag}>${parts.map((p) => `<li>${p}</li>`).join('')}</${tag}>`, i }
+}
+
+/** `- [ ]` and `- [x]`: the checkboxes of an archived plan, shown but not tickable. */
+function item(text, link) {
+  const box = /^\[( |x|X)\]\s+(.*)$/.exec(text)
+  if (!box) return inline(text, link)
+  const on = box[1] !== ' '
+  // The text has to be wrapped: the label is both a column and a row, and without one
+  // container every bold fragment would become a column of its own.
+  return `<label class="task"><input type="checkbox" disabled${on ? ' checked' : ''}><span>${inline(
+    box[2],
+    link
+  )}</span></label>`
+}
+
+// ── Inline ───────────────────────────────────────────────────────────────────
+function inline(raw, link) {
+  // Anything already finished is set aside behind a placeholder and put back at the end. The
+  // placeholder lives in Unicode's private-use area: no real document contains those
+  // characters, so there is no way to confuse one with the text.
+  const kept = []
+  const hold = (html) => `\uE000${kept.push(html) - 1}\uE001`
+
+  let s = esc(raw)
+
+  // Code first: what is inside it is not markdown, it is text.
+  s = s.replace(/`([^`\n]+)`/g, (_, c) => hold(`<code>${c}</code>`))
+  // Images before links: same syntax, with an exclamation mark in front.
+  s = s.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+&quot;[^)]*&quot;)?\)/g, (_, alt, src) =>
+    hold(`<img src="${href(src, 'image', link)}" alt="${alt}" loading="lazy">`)
+  )
+  s = s.replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+&quot;[^)]*&quot;)?\)/g, (_, text, target) => {
+    const u = href(target, 'link', link)
+    const out = /^https?:/i.test(u) ? ' target="_blank" rel="noreferrer"' : ''
+    return hold(`<a href="${u}"${out}>${text}</a>`)
+  })
+  // Bare addresses, which in documents are the majority.
+  s = s.replace(/(^|[\s(])(https?:\/\/[^\s<)]+)/g, (_, before, u) =>
+    `${before}${hold(`<a href="${u}" target="_blank" rel="noreferrer">${u}</a>`)}`
+  )
+
+  // Bold can start on one line and end on the next. Documents wrap at seventy characters, and
+  // a bold phrase longer than that is bound to straddle a break: excluding the newline left it
+  // on screen with the asterisks still in it. Crossing a newline here is safe — the real break,
+  // the one between one paragraph and the next, never reaches this far: every block is laid out
+  // on its own.
+  s = s
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/__([^_]+)__/g, '<strong>$1</strong>')
+    .replace(/(^|[^*\w])\*([^*]+)\*/g, '$1<em>$2</em>')
+    .replace(/(^|[^_\w])_([^_]+)_/g, '$1<em>$2</em>')
+    .replace(/~~([^~]+)~~/g, '<del>$1</del>')
+    // Two spaces at the end of a line are a deliberate break; other newlines are not.
+    .replace(/ {2,}\n/g, '<br>\n')
+
+  // Several passes, because the placeholders nest: a link whose text is already a piece set
+  // aside — `[`name.md`](...)` — brings the code's placeholder back out when it is restored.
+  // A single pass would leave it there, on screen, as a little square.
+  for (let i = 0; i < 6 && s.includes('\uE000'); i++) {
+    s = s.replace(/\uE000(\d+)\uE001/g, (_, k) => kept[Number(k)] ?? '')
+  }
+  return s
+}
+
+/**
+ * Where a reference leads. Schemes that are not addresses — `javascript:`, `data:` — do not get
+ * through: Claude writes these files, but they are still files that come off the disk and
+ * nobody has looked at them before they are shown.
+ */
+function href(target, kind, link) {
+  const t = target.trim()
+  if (/^(https?:|mailto:|#)/i.test(t)) return t
+  if (/^[a-z][a-z0-9+.-]*:/i.test(t)) return '#'
+  return link(t, kind)
+}

package/web/mentions.js

@@ -0,0 +1,188 @@
+// ── The files a piece of text names ───────────────────────────────────────────
+// When a session ends, the summary in the chat says what it touched and names the files:
+// "from-the-call.md", "interviews/onboarding/journal.md", "the survey". To read them again you
+// had to go and find them one by one, remembering what each was called.
+//
+// This does the opposite: it takes the text as it is and works out which of this repository's
+// files it names. It does not look for the subject — only for the names written down — which
+// is why it costs nothing and never goes near the server: the file listing is already in the
+// browser.
+//
+// What is written out in full and what is merely guessed at stay separate, because they are
+// two different degrees of certainty: mixing them would make a word that is only a hunch look
+// like a fact.
+
+/** The extension on the end of a name. It has to start with a letter: `1.5` is not a file. */
+const EXT = /\.([A-Za-z][A-Za-z0-9]{0,5})$/
+/** A piece of text that might be a name or a path. */
+const TOKEN = /[A-Za-z0-9][A-Za-z0-9._/-]*/g
+/** Under four characters a word is not the name of anything: it is a word. */
+const MIN = 4
+
+const low = (s) => String(s ?? '').toLowerCase()
+const nameOf = (p) => p.slice(p.lastIndexOf('/') + 1)
+const dirOf = (p) => p.slice(0, Math.max(0, p.lastIndexOf('/')))
+const newest = (a, b) => b.m - a.m
+
+/**
+ * The indexes the search runs on, rebuilt on every call: they cost one pass over the listing,
+ * and the caller already knows when the listing changes.
+ *
+ * `byDir` only knows a directory's **direct** files, not those of its subdirectories: opening
+ * a directory means seeing what is in it, not the whole tree. Which is why a directory
+ * containing only other directories does not appear here — it would have nothing to show.
+ */
+function index(files) {
+  const byName = new Map()
+  const byStem = new Map()
+  const byDir = new Map()
+  const dirTail = new Map() // last piece of a directory → the directories ending that way
+  const exts = new Set()
+  const push = (map, key, val) => {
+    const a = map.get(key)
+    if (a) a.push(val)
+    else map.set(key, [val])
+  }
+
+  for (const f of files) {
+    const p = low(f.p)
+    const n = nameOf(p)
+    push(byName, n, f)
+    push(byStem, n.replace(EXT, ''), f)
+    const ext = EXT.exec(n)
+    if (ext) exts.add(ext[1])
+    const d = dirOf(p)
+    if (d) push(byDir, d, f)
+  }
+  for (const d of byDir.keys()) push(dirTail, nameOf(d), d)
+
+  return { byName, byStem, byDir, dirTail, exts, stems: [...byStem.keys()] }
+}
+
+/** The pieces of text worth trying, lower case and in the order they appear. */
+function tokens(text) {
+  const out = []
+  for (const m of String(text ?? '').matchAll(TOKEN)) {
+    // Punctuation stuck on the end is not part of the name: "…it is in from-the-call.md."
+    const t = low(m[0]).replace(/[._/-]+$/, '')
+    if (t) out.push(t)
+  }
+  return out
+}
+
+/**
+ * The files a token with an extension names, or `null`.
+ *
+ * The path can be written in full, only from the end, or with things in front that do not
+ * count here (`research-notes/interviews/onboarding/journal.md`): they are all worth the same.
+ * If the path as written matches nobody but the name does, the name wins — people writing from
+ * memory get the directory wrong far more often than the name.
+ */
+function filesFor(token, ix) {
+  const cands = ix.byName.get(nameOf(token))
+  if (!cands) return null
+  if (!token.includes('/')) return cands
+  const exact = cands.filter((f) => {
+    const p = low(f.p)
+    return p === token || p.endsWith('/' + token) || token.endsWith('/' + p)
+  })
+  return exact.length ? exact : cands
+}
+
+/**
+ * The directory a token names, or `null`. If one name matches several directories and there is
+ * no path to tell them apart, it is left alone: a single row that opens the wrong directory is
+ * worse than no row at all.
+ */
+function dirFor(token, ix) {
+  if (ix.byDir.has(token)) return token
+  const tails = ix.dirTail.get(nameOf(token)) || []
+  const exact = tails.filter((d) => d.endsWith('/' + token) || token.endsWith('/' + d))
+  return exact.length === 1 ? exact[0] : null
+}
+
+/**
+ * This repository's files as named inside `text`.
+ *
+ * - `named` — what is written out in full: a name with its extension, or a directory path.
+ *   There is nothing to guess.
+ * - `maybe` — what is only guessed at: a word that is a file's name without the extension
+ *   ("summary"), or the whole beginning of a name ("survey" for `survey-round-two.md`).
+ * - `missing` — names written with a dot that do not exist in here. Only those with an
+ *   extension the repository actually uses, otherwise `example.com` would look like a lost file.
+ *
+ * Every entry is `{ token, file, more }` for a file — `file` is the most recently touched one
+ * when a name points at several, `more` are the rest — or `{ token, dir, files }` for a
+ * directory. A file never appears twice, and what is certain takes precedence over what is
+ * guessed.
+ */
+export function mentions(text, files) {
+  const ix = index(files || [])
+  const toks = tokens(text)
+  const seen = new Set()
+  const named = []
+  const maybe = []
+  const missing = []
+  const missed = new Set()
+
+  /** Drops the ones already listed and puts the most recent first. */
+  const fresh = (hits) => (hits || []).filter((f) => !seen.has(f.p)).sort(newest)
+  const keep = (out, entry, taken) => {
+    for (const f of taken) seen.add(f.p)
+    out.push(entry)
+  }
+
+  // First pass: what is written out in full.
+  for (const t of toks) {
+    if (EXT.test(t)) {
+      const hits = filesFor(t, ix)
+      if (!hits) {
+        if (ix.exts.has(EXT.exec(t)[1]) && !missed.has(t)) {
+          missed.add(t)
+          missing.push(t)
+        }
+        continue
+      }
+      const f = fresh(hits)
+      if (f.length) keep(named, { token: t, file: f[0], more: f.slice(1) }, f)
+    } else if (t.includes('/')) {
+      // A directory written as a path is not just any word: it is certain.
+      const d = dirFor(t, ix)
+      const f = d ? fresh(ix.byDir.get(d)) : []
+      if (f.length) keep(named, { token: t, dir: d, files: f }, f)
+    }
+  }
+
+  // Second pass: the names that are only guessed at. It comes after the first, so a file
+  // already found by its full name does not turn up again down here as a hunch.
+  const guess = (t) => t.length >= MIN && !EXT.test(t) && !t.includes('/')
+
+  // File names first: the whole name without the dot, failing that the whole beginning of a
+  // name cut at a dash — "survey" for `survey-round-two.md`.
+  for (const t of toks) {
+    if (!guess(t)) continue
+    const hits =
+      ix.byStem.get(t) ||
+      ix.stems.filter((s) => s.startsWith(t + '-')).flatMap((s) => ix.byStem.get(s))
+    const f = fresh(hits)
+    if (f.length) keep(maybe, { token: t, file: f[0], more: f.slice(1) }, f)
+  }
+
+  // Then the directories named with a single word. They come last because they are the weakest
+  // clue there is: "onboarding" in a text about onboarding is an ordinary word, and if it came
+  // first it would carry off `interviews/onboarding/summary.md`, leaving "summary" to show the
+  // summary of something else entirely.
+  for (const t of toks) {
+    if (!guess(t)) continue
+    const d = dirFor(t, ix)
+    const f = d ? fresh(ix.byDir.get(d)) : []
+    if (f.length) keep(maybe, { token: t, dir: d, files: f }, f)
+  }
+
+  return { named, maybe, missing }
+}
+
+/** How many files a group of entries opens: a directory counts for what is inside it. */
+export function countIn(entries) {
+  return entries.reduce((n, e) => n + (e.files ? e.files.length : 1 + e.more.length), 0)
+}