blume 2.1.3 → 2.2.0

package/skills/blume-migrate/scripts/github-wiki-codemod.mjs

@@ -0,0 +1,2808 @@
+#!/usr/bin/env node
+// github-wiki-codemod.mjs — the mechanical part of a GitHub wiki → Blume
+// migration. Run it from a copy of the wiki clone, which becomes the Blume
+// project (`blume.config.ts` beside it, pages moved into `docs/`). It has four
+// commands:
+//
+//   routes   Lists the wiki's pages the way GitHub serves them (every file in a
+//            markup format GitHub renders, named by its file name, folders
+//            ignored, a root file winning a name clash) and writes the route
+//            table: `wiki-routes.json` (page name → new flat route) and
+//            `wiki-files.json` (page name → file). It suggests which pages are
+//            moved notices or not content, for you to classify by editing the
+//            table (a target URL or route, or `null`). It never overwrites a
+//            table that exists: it compares the two instead.
+//   convert  Reads the classified table and, per Markdown page that stays:
+//            moves it to `docs/(group)/<route>.md` (`Home` → `docs/index.md`),
+//            writes `title` (the page name as GitHub showed it), `sidebar.label`,
+//            and `slug` where the file's place doesn't give its route; turns
+//            `[[wiki links]]` (text first, `[[Page]]`, `[[text|Page#anchor]]`,
+//            `[[text|https://…]]`, image tags, `[[_TOC_]]`) and links to the
+//            wiki (absolute, root-relative, bare page names, `#user-content-`
+//            anchors, the mirror repository's copies, relative links that leave
+//            the wiki) into routes; moves the wiki's own images next to the
+//            pages and points them there (Markdown images, wiki image tags, and
+//            a raw `<img>` alone on its line), dropping a relative image that
+//            pointed at nothing on GitHub either; converts GitHub alerts to `:::`
+//            directives (an indented or lazy one stays an alert, which Blume
+//            renders as a callout in `.mdx`); lowercases fence languages (Blume
+//            reads any case, so that only tidies) and maps Linguist-only ones;
+//            pins `<a name>` heading anchors as `[#id]` (Blume would take the
+//            name as the id anyway; the pin drops the empty tag); deletes a
+//            leading H1 that repeats the page name
+//            and demotes every heading one level on a page that still has an H1
+//            (ATX and one-line setext); deletes a Foam "Autogenerated link
+//            references" block and link definitions a same-label one above
+//            already shadows (CommonMark uses the first); and renames a page
+//            that now needs MDX to `.mdx` with its comments, void tags,
+//            autolinks, bare `<`, and braces made MDX-safe. It writes a
+//            `meta.ts` per `_Sidebar.md` group, a root one in sidebar order, and
+//            a collapsed "More pages" group for the pages the sidebar doesn't
+//            list. It leaves fenced, indented, and inline code, `<code>` and
+//            `<tt>`, HTML comments, and gollum's `'[[…]]` escape alone, and
+//            writes a wiki link inside an HTML block as `<a href>`, since
+//            Markdown there shows as text.
+//   stubs    In a fresh clone of the wiki (with both tables copied in),
+//            replaces every page with a one-line link to its new URL and the
+//            sidebar with a notice. It only writes files: it never commits or
+//            pushes, and it refuses to run beside a `blume.config.ts`. The
+//            user pushes. `--notice-only` only puts the notice at the top of
+//            `Home` and `_Sidebar.md`.
+//   check    After `blume build`: every route in the table must exist in
+//            `dist/`, anchors included. Given old wiki URLs (inbound links from
+//            the main repository), it prints each one's new route and checks
+//            its page and anchor, suggesting ids for an anchor that's gone.
+//
+// It reports, and never fakes, what needs judgment: pages in other markup
+// formats (convert them with pandoc first), sidebar lines it can't place,
+// wiki links to missing or left-out pages (made plain text), Markdown links
+// that were already broken on GitHub (left for you to retarget), wiki UI links,
+// files stored in the wiki that pages link or show in raw HTML, uploaded
+// attachments to vendor, dropped images and image sizes, multi-line setext
+// headings, emoji in headings, MDX hazards it can't fix, and the files a
+// converted copy leaves behind.
+//
+// Design constraints (as mintlify-codemod.mjs): zero dependencies, sorted and
+// deterministic, idempotent (a second run changes nothing), dry run by default.
+//
+// Usage, from the copy of the wiki clone:
+//   node github-wiki-codemod.mjs routes --repo owner/repo            # report
+//   node github-wiki-codemod.mjs routes --repo owner/repo --write    # write the table
+//   node github-wiki-codemod.mjs convert --repo owner/repo           # dry run
+//   node github-wiki-codemod.mjs convert --repo owner/repo --write   # apply
+//   node github-wiki-codemod.mjs stubs --site https://docs.example.com --write
+//   node github-wiki-codemod.mjs check [https://github.com/owner/repo/wiki/FAQ#x …]
+//
+// Options:
+//   --repo <owner/repo>   The repository the wiki belongs to (routes, convert).
+//   --mirror <owner/repo> A repository that mirrors the wiki (`<repo>-wiki`):
+//                         links to its copies of pages become routes too.
+//   --content <dir>       The content root (default: docs).
+//   --emoji <file>        Shortcode → emoji map (GitHub's /emojis JSON works).
+//   --site <url>          The new site, base path included (stubs).
+//   --notice-only         Stubs: only the notice on Home and the sidebar.
+//   --dist <dir>          The build to check (default: dist).
+//   --write               Apply. Without it, report only.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+const { posix } = path;
+
+// --- Tables -------------------------------------------------------------------
+
+// Every extension GitHub renders as a wiki page (github/markup).
+const MARKUP =
+  /\.(?:md|markdown|mdown|mkdn|textile|rdoc|org|creole|mediawiki|wiki|rst|rest|asciidoc|adoc|asc|pod6?)$/iu;
+const MARKDOWN = /\.(?:md|markdown|mdown|mkdn)$/iu;
+const CHROME = /^_(?:sidebar|footer)\./iu;
+const SIDEBAR = /^_sidebar\./iu;
+const FOOTER = /^_footer\./iu;
+const IMAGE = /\.(?:apng|avif|bmp|gif|ico|jpe?g|png|svg|webp)$/iu;
+const ALERTS = {
+  caution: "danger",
+  important: "note",
+  note: "note",
+  tip: "tip",
+  warning: "warning",
+};
+// Linguist names Shiki doesn't know.
+const FENCE_LANGUAGES = { posh: "powershell" };
+const DROPPED_FENCES = new Set(["geojson", "stl", "topojson"]);
+const NOT_CONTENT = new Set([
+  "code_of_conduct",
+  "contributing",
+  "license",
+  "readme",
+  "security",
+]);
+const NOT_CONTENT_FOLDERS = new Set(["fixtures", "scripts", "test", "tests"]);
+const SKIP_DIRS = new Set([".blume", ".git", "dist", "node_modules", "public"]);
+const PROJECT_FILES = new Set([
+  ".gitignore",
+  "blume.config.ts",
+  "bun.lock",
+  "package-lock.json",
+  "package.json",
+  "pnpm-lock.yaml",
+  "theme.css",
+  "wiki-files.json",
+  "wiki-routes.json",
+  "yarn.lock",
+]);
+const HTML_TAGS = new Set(
+  [
+    "a abbr b bdo blockquote br caption cite code col colgroup dd del details",
+    "dfn div dl dt em figcaption figure h1 h2 h3 h4 h5 h6 hr i img input ins",
+    "kbd li mark ol p picture pre q rp rt ruby s samp small source span strike",
+    "strong sub summary sup table tbody td tfoot th thead time tr tt u ul var",
+    "video wbr",
+  ]
+    .join(" ")
+    .split(" ")
+);
+const ROUTES_FILE = "wiki-routes.json";
+const FILES_FILE = "wiki-files.json";
+const DELETED = "\u{0}";
+const UNICODE_HYPHEN = "\u{2010}";
+const MAX_NOTICE_LINES = 3;
+const MAX_ID_SUGGESTIONS = 3;
+const HEADING_LEVELS = 6;
+
+// --- Patterns -----------------------------------------------------------------
+
+const ATX =
+  /^(?<prefix> {0,3}(?:>(?:\t {0,3}| {0,4}))*)(?<hashes>#{1,6})(?<rest>(?:[ \t].*)?)$/u;
+const SETEXT = /^ {0,3}(?<marker>=+|-+)[ \t]*$/u;
+const LIST_ITEM =
+  /^(?<indent>[ \t]*)(?<marker>[-*+]|\d{1,9}[.)])(?<gap>[ \t]+|$)(?<content>.*)$/u;
+const FENCE = /^(?<prefix>[ \t>]*)(?<marker>`{3,}|~{3,})(?<info>.*)$/u;
+// A backslash escapes the backtick after it (an even run of backslashes doesn't).
+const CODE_SPAN =
+  /(?<=(?:^|[^\\])(?:\\\\)*)(?<ticks>`+)(?<code>[\s\S]*?[^`])\k<ticks>(?!`)/gu;
+const COMMENT = /<!--[\s\S]*?(?:-->|$)/gu;
+// GitHub leaves `[[…]]` alone inside `<code>` and `<tt>` too.
+const CODE_ELEMENT = /<(?<name>code|tt)\b[^<>]*>[\s\S]*?<\/\k<name>\s*>/giu;
+const TAG = /<\/?[A-Za-z][^<>]*>/gu;
+const LINK_DESTINATION = /\]\((?:[^()\s]|\([^()\s]*\))*(?:\s+"[^"]*")?\)/gu;
+// `'[[Page]]` is gollum's escape for literal brackets (unless a `'` follows),
+// and the text may hold balanced brackets (`[[execute[.*]|Page]]`).
+const WIKI_LINK =
+  /(?<!\\)(?<quote>'?)\[\[(?<inner>(?:[^[\]\n]|\[[^[\]\n]*\])+)\]\](?<after>'?)/dgu;
+const ESCAPED_WIKI_LINK = /\\\[\\\[(?<inner>(?:[^[\]\\\n]|\\\|)+?)\\\]\\\]/dgu;
+const PIPE = /\s*\\?\|\s*/u;
+const DESTINATION = String.raw`(?<dest><[^<>\n]*>|[^\s()<>]*(?:\([^\s()]*\)[^\s()<>]*)*)`;
+const TITLE = String.raw`(?<title>\s+(?:"[^"\n]*"|'[^'\n]*'))?`;
+const MD_IMAGE = new RegExp(
+  String.raw`!\[(?<alt>[^[\]\n]*)\]\(\s*${DESTINATION}${TITLE}\s*\)`,
+  "dgu"
+);
+const MD_LINK = new RegExp(
+  String.raw`(?<!!)\[(?<label>(?:[^[\]\n]|\[[^[\]\n]*\])*)\]\(\s*${DESTINATION}${TITLE}\s*\)`,
+  "dgu"
+);
+const RAW_HREF =
+  /<a\b[^<>]*?\bhref\s*=\s*(?<quote>["'])(?<dest>[^"']*)\k<quote>/dgiu;
+const RAW_IMG_LINE =
+  /^(?<indent>[ \t]*)<img\b(?<attributes>[^<>]*?)\/?>[ \t]*$/iu;
+const DEFINITION =
+  /^(?<indent> {0,3})\[(?<label>(?:[^[\]\\\n]|\\.)+)\]:[ \t]*(?<dest><[^<>\n]*>|[^\s<]\S*)(?<rest>.*)$/u;
+const ALERT_START =
+  /^>[ \t]*\[!(?<type>caution|important|note|tip|warning)\][ \t]*$/iu;
+const ANY_ALERT = /^[ \t]*>[ \t]*\[!(?:caution|important|note|tip|warning)\]/iu;
+const QUOTED = /^ {0,3}>/u;
+const NAMED_ANCHOR =
+  /<a\s+(?:id|name)\s*=\s*["'](?<id>[^"']+)["']\s*(?:\/>|>\s*<\/a\s*>)[ \t]*/iu;
+const HEADING_MARKER = /\s(?:\[#[^\s\]]+\]|\\?\{#[^\s}]+\\?\})\s*$/u;
+const CLOSING_HASHES = /[ \t]+#+[ \t]*$/u;
+const FOAM_BEGIN = /^\[\/\/begin\]:\s*#/u;
+const FOAM_END = /^\[\/\/end\]:\s*#/u;
+const SHORTCODE = /(?<![\w:]):(?<name>[a-z0-9_+][a-z0-9_+-]*):(?![\w:])/dgu;
+const EMOJI_ENTRY =
+  /["']?(?<name>[\w+-]+)["']?\s*:\s*["'][^"']*unicode\/(?<hex>[0-9a-f-]+)/giu;
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+// A wiki link's target is a URL only with `//` or `mailto:`: page names can
+// hold a colon (`[[Module: Battery]]`).
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:\/\/|mailto:)/iu;
+const ATTACHMENT =
+  /^https?:\/\/(?:(?:private-)?user-images\.githubusercontent\.com|github\.com\/user-attachments)\//iu;
+const BLOB =
+  /^https?:\/\/(?:www\.)?github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)\/blob\/(?<rest>[^?#]+)(?:\?raw=true)?$/iu;
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/u;
+const UI_PAGE = /^_(?:access|compare|history|new|pages|search)$/iu;
+const ORDERING_PREFIX = /^(?<order>\d+)[-_.]/u;
+const NOT_AN_ORDER = /^(?:\d+\.\d|\d{4}-\d{2}-\d{2}(?:[-_.]|$))/u;
+const PLAIN_SCALAR = /^[\p{L}\p{N}][^:#\n"'[\]{}&*!|>%@`]*$/u;
+const YAML_KEYWORD = /^(?:true|false|yes|no|on|off|null|~|[\d.+-]+)$/iu;
+const MOVED_NOTICE =
+  /\bmoved\s+to\b|\bhas\s+moved\b|\bnow\s+(?:lives|hosted)\b|\bis\s+now\s+at\b/iu;
+const FIRST_URL = /https?:\/\/[^\s)>\]"'`]+/u;
+const ID_ATTRIBUTE = /\sid="(?<id>[^"]+)"/gu;
+const VOID_TAG =
+  /<(?<tag>area|base|br|col|embed|hr|img|input|link|meta|source|track|wbr)\b(?<attributes>(?:[^<>/]|\/(?!>))*)>/dgiu;
+const ANGLE_AUTOLINK = /<(?<url>https?:\/\/[^\s<>]+)>/dgu;
+const STRAY_ANGLE = /<(?![A-Za-z/!])/dgu;
+const BRACE = /(?<!\\)[{}]/dgu;
+const OPEN_TAG = /<(?<tag>[A-Za-z][\w-]*)(?:[\s/][^<>]*)?>/gu;
+
+// --- Small helpers --------------------------------------------------------------
+
+const compareText = (left, right) => {
+  if (left < right) {
+    return -1;
+  }
+  return left > right ? 1 : 0;
+};
+
+const escapeRegExp = (text) =>
+  text.replaceAll(/[$()*+.?[\\\]^{|}]/gu, String.raw`\$&`);
+
+const decode = (text) => {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+};
+
+/** A page's new route segment: lowercase, apostrophes dropped, other runs → `-`. */
+const slugOf = (name) =>
+  name
+    .normalize("NFC")
+    .replaceAll(/['\p{Pf}]/gu, "")
+    .toLowerCase()
+    .replaceAll(/[^\p{L}\p{N}]+/gu, "-")
+    .replaceAll(/^-+|-+$/gu, "");
+
+/** GitHub's page name for a file: its base name minus the last extension. */
+const pageNameOf = (file) =>
+  posix.basename(file).replace(MARKUP, "").replaceAll(" ", "-");
+
+/** How GitHub matched a name: case-insensitive, spaces read as `-`. */
+const keyOf = (name) => name.trim().replaceAll(" ", "-").toLowerCase();
+
+const ownRouteOf = (name) =>
+  keyOf(name) === "home" ? "/" : `/${slugOf(name)}`;
+
+/** The page name as GitHub showed it above the page. */
+const titleOf = (name) =>
+  name.replaceAll("-", " ").replaceAll(UNICODE_HYPHEN, "-");
+
+const plainText = (text) =>
+  text
+    .replaceAll(/[*_`~]/gu, "")
+    .replaceAll(/\[(?<text>[^\]]*)\]\([^)]*\)/gu, "$<text>")
+    .trim();
+
+const comparable = (text) =>
+  plainText(text)
+    .toLowerCase()
+    .replaceAll(/[^\p{L}\p{N}]/gu, "");
+
+const yamlScalar = (value) =>
+  PLAIN_SCALAR.test(value) &&
+  !YAML_KEYWORD.test(value) &&
+  value.trim() === value
+    ? value
+    : JSON.stringify(value);
+
+const cleanAnchor = (anchor) => anchor.replace(/^user-content-/u, "");
+
+const unwrapAngle = (dest) =>
+  dest.startsWith("<") && dest.endsWith(">") ? dest.slice(1, -1) : dest;
+
+const depthOf = (file) => file.split("/").length;
+
+const byDepthThenName = (left, right) =>
+  depthOf(left) - depthOf(right) || compareText(left, right);
+
+/** Blume's route for a file under the content root (ordering prefixes and `(group)` folders dropped). */
+const derivedRoute = (relative) => {
+  const segments = relative
+    .replace(/\.mdx?$/u, "")
+    .split("/")
+    .filter((segment) => !(segment.startsWith("(") && segment.endsWith(")")))
+    .map((segment) => {
+      const order = NOT_AN_ORDER.test(segment)
+        ? null
+        : ORDERING_PREFIX.exec(segment);
+      return order ? segment.slice(order.groups.order.length + 1) : segment;
+    });
+  if (segments.at(-1) === "index") {
+    segments.pop();
+  }
+  return `/${segments.join("/")}`;
+};
+
+const relativeAsset = (fromFile, toFile) => {
+  const relative = posix.relative(posix.dirname(fromFile), toFile);
+  const dotted = relative.startsWith(".") ? relative : `./${relative}`;
+  return dotted.replaceAll(" ", "%20");
+};
+
+const walk = (root, skip, dir = "") => {
+  const files = [];
+  const entries = readdirSync(path.join(root, dir), { withFileTypes: true });
+  for (const entry of entries.toSorted((left, right) =>
+    compareText(left.name, right.name)
+  )) {
+    const relative = dir ? `${dir}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (!skip.has(relative) && !SKIP_DIRS.has(entry.name)) {
+        files.push(...walk(root, skip, relative));
+      }
+    } else {
+      files.push(relative);
+    }
+  }
+  return files;
+};
+
+const resolveUrl = (href, base) => {
+  try {
+    return new URL(href, base).href;
+  } catch {
+    return null;
+  }
+};
+
+const isFile = (file) => existsSync(file) && statSync(file).isFile();
+
+const readJson = (file) => JSON.parse(readFileSync(file, "utf-8"));
+
+const writeJson = (file, value) =>
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+
+const loadEmoji = (file) => {
+  const map = new Map();
+  if (!file) {
+    return map;
+  }
+  for (const match of readFileSync(file, "utf-8").matchAll(EMOJI_ENTRY)) {
+    const points = match.groups.hex
+      .split("-")
+      .map((hex) => Number.parseInt(hex, 16));
+    map.set(match.groups.name, String.fromCodePoint(...points));
+  }
+  return map;
+};
+
+/** `line` with code spans, comments, tags, and link destinations blanked out (same length). */
+const blankOut = (span) => DELETED.repeat(span.length);
+
+const mask = (
+  line,
+  { comments = true, destinations = false, elements = false, tags = false } = {}
+) => {
+  let masked = line.replaceAll(CODE_SPAN, blankOut);
+  if (comments) {
+    masked = masked.replaceAll(COMMENT, blankOut);
+  }
+  if (elements) {
+    masked = masked.replaceAll(CODE_ELEMENT, blankOut);
+  }
+  if (tags) {
+    masked = masked.replaceAll(TAG, blankOut);
+  }
+  if (destinations) {
+    masked = masked.replaceAll(LINK_DESTINATION, blankOut);
+  }
+  return masked;
+};
+
+/**
+ * Replace each match of `pattern` (a `d`-flagged global regex) found outside
+ * code spans and comments. `replace(group, original)` gets the match's text
+ * from the real line, and returns the replacement or null to keep it.
+ */
+const replaceOutside = (line, pattern, replace, options) => {
+  const masked = mask(line, options);
+  let out = "";
+  let last = 0;
+  for (const match of masked.matchAll(pattern)) {
+    const end = match.index + match[0].length;
+    const original = line.slice(match.index, end);
+    const group = (name) => {
+      const span = match.indices.groups?.[name];
+      return span ? line.slice(span[0], span[1]) : null;
+    };
+    const next = original.includes(DELETED) ? null : replace(group, original);
+    out += `${line.slice(last, match.index)}${next ?? original}`;
+    last = end;
+  }
+  return `${out}${line.slice(last)}`;
+};
+
+// --- Arguments -------------------------------------------------------------------
+
+const VALUE_OPTIONS = new Set([
+  "content",
+  "dist",
+  "emoji",
+  "mirror",
+  "repo",
+  "site",
+]);
+
+const parseArgs = (argv) => {
+  const options = new Map();
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const [key, inline] = arg.startsWith("--")
+      ? arg.slice(2).split("=", 2)
+      : [];
+    if (key === undefined) {
+      positional.push(arg);
+    } else if (VALUE_OPTIONS.has(key) && inline === undefined) {
+      index += 1;
+      options.set(key, argv[index]);
+    } else {
+      options.set(key, inline ?? "");
+    }
+  }
+  return { options, positional };
+};
+
+const HELP = [
+  "Usage:",
+  "  node github-wiki-codemod.mjs routes --repo <owner/repo> [--write]",
+  "  node github-wiki-codemod.mjs convert --repo <owner/repo> [--mirror <owner/repo>] [--emoji <file>] [--write]",
+  "  node github-wiki-codemod.mjs stubs --site <url> [--notice-only] [--write]",
+  "  node github-wiki-codemod.mjs check [--dist dist] [old wiki URL …]",
+  "",
+  "  --repo <owner/repo>     the repository the wiki belongs to",
+  "  --mirror <owner/repo>   a repository that mirrors the wiki",
+  "  --content <dir>         the content root (default: docs)",
+  "  --emoji <file>          shortcode → emoji map (GitHub's /emojis JSON works)",
+  "  --site <url>            the new site, base path included (stubs)",
+  "  --notice-only           stubs: only a notice on Home and the sidebar",
+  "  --dist <dir>            the build to check (default: dist)",
+  "  --write                 apply (default: dry run)",
+].join("\n");
+
+// --- The wiki ----------------------------------------------------------------------
+
+const REPO = /^(?<owner>[\w.-]+)\/(?<name>[\w.-]+)$/u;
+
+const repoUrls = (repo, mirror) => {
+  const { owner, name } = REPO.exec(repo).groups;
+  const base = `${escapeRegExp(owner)}/${escapeRegExp(name)}`;
+  const mirrorMatch = mirror ? REPO.exec(mirror) : null;
+  const mirrorBase = mirrorMatch
+    ? `${escapeRegExp(mirrorMatch.groups.owner)}/${escapeRegExp(mirrorMatch.groups.name)}`
+    : null;
+  return {
+    angle: new RegExp(
+      String.raw`<(?<url>https?://(?:www\.)?github\.com/${base}/wiki(?:[/#][^<>\s]*)?)>`,
+      "dgiu"
+    ),
+    bare: new RegExp(
+      String.raw`(?<![\w(<\["'=/])(?<url>https?://(?:www\.)?github\.com/${base}/wiki(?:[/#][^\s<>()[\]"'\u{60}]*)?)`,
+      "dgiu"
+    ),
+    base: `https://github.com/${owner}/${name}/wiki/`,
+    mirror: mirrorBase
+      ? new RegExp(
+          String.raw`^https?://(?:www\.)?github\.com/${mirrorBase}/blob/[^/]+/(?<file>[^?#]+)(?<hash>#.*)?$`,
+          "iu"
+        )
+      : null,
+    owner,
+    raw: new RegExp(
+      String.raw`^https?://raw\.githubusercontent\.com/wiki/${base}/(?<file>[^?#]+)`,
+      "iu"
+    ),
+    repoRoot: new RegExp(String.raw`^/${base}(?:[/?#]|$)`, "iu"),
+    wiki: new RegExp(
+      String.raw`^(?:https?://(?:www\.)?github\.com)?/${base}/wiki(?<rest>/[^?#]*)?(?:\?[^#]*)?(?<hash>#.*)?$`,
+      "iu"
+    ),
+  };
+};
+
+/** The wiki's pages, the way GitHub serves them. */
+const listPages = (root, content) => {
+  const files = walk(root, new Set([content])).toSorted(byDepthThenName);
+  const pages = files.filter((file) => {
+    const base = posix.basename(file);
+    return MARKUP.test(base) && !CHROME.test(base);
+  });
+  return { files, pages };
+};
+
+const buildTable = (pages) => {
+  const routes = {};
+  const sources = {};
+  const taken = new Map();
+  const owners = new Map();
+  const shadowed = [];
+  const clashes = [];
+  for (const file of pages) {
+    const name = pageNameOf(file);
+    const key = keyOf(name);
+    if (taken.has(key)) {
+      shadowed.push(`${file} (GitHub served ${taken.get(key)})`);
+      continue;
+    }
+    taken.set(key, file);
+    const route = ownRouteOf(name);
+    if (owners.has(route)) {
+      clashes.push(`${file} and ${owners.get(route)} → ${route}`);
+    }
+    owners.set(route, file);
+    routes[name] = route;
+    sources[name] = file;
+  }
+  return { clashes, routes, shadowed, sources };
+};
+
+const kindOf = (name, value, owners) => {
+  if (value === null) {
+    return "dropped";
+  }
+  if (URL_SCHEME.test(value) || value.includes("#")) {
+    return "moved";
+  }
+  const owner = owners.get(value);
+  return owner && owner !== name ? "moved" : "content";
+};
+
+/** Each page's role from the classified table: content, moved, or dropped. */
+const classify = (routes) => {
+  const owners = new Map(
+    Object.keys(routes).map((name) => [ownRouteOf(name), name])
+  );
+  const kinds = new Map();
+  const byKey = new Map();
+  for (const [name, value] of Object.entries(routes)) {
+    kinds.set(name, kindOf(name, value, owners));
+    byKey.set(keyOf(name), name);
+  }
+  return { byKey, kinds, routes };
+};
+
+const findPage = (index, target) =>
+  index.byKey.get(keyOf(target)) ??
+  index.byKey.get(keyOf(target.replaceAll("_", "-"))) ??
+  null;
+
+/** A page target (`Page Name#anchor`) → { kind, name, href }. */
+const resolvePage = (index, target, self) => {
+  const hashAt = target.indexOf("#");
+  const page = hashAt === -1 ? target : target.slice(0, hashAt);
+  const anchor = hashAt === -1 ? "" : cleanAnchor(target.slice(hashAt + 1));
+  if (page.trim() === "") {
+    return anchor
+      ? { href: `#${anchor}`, kind: "content", name: self }
+      : { kind: "missing", name: target };
+  }
+  const name =
+    findPage(index, page) ?? findPage(index, page.replace(MARKUP, ""));
+  if (name === null) {
+    return { kind: "missing", name: page };
+  }
+  const kind = index.kinds.get(name);
+  const value = index.routes[name];
+  if (kind === "dropped") {
+    return { kind, name };
+  }
+  if (kind === "moved") {
+    return { href: value, kind, name };
+  }
+  return { href: anchor ? `${value}#${anchor}` : value, kind, name };
+};
+
+/** What a URL into the wiki names: a page, a file stored in the wiki, or GitHub's UI. */
+const wikiTarget = (ctx, href) => {
+  const match = ctx.urls.wiki.exec(href);
+  if (!match) {
+    return null;
+  }
+  const rest = decode((match.groups.rest ?? "").replace(/^\//u, "")).replace(
+    /\/$/u,
+    ""
+  );
+  const hash = match.groups.hash ?? "";
+  if (rest === "") {
+    return { kind: "page", target: `Home${hash}` };
+  }
+  if (ctx.fileExists(rest) && !MARKUP.test(rest)) {
+    return { file: rest, kind: "file" };
+  }
+  const [first, ...more] = rest.split("/");
+  const revision =
+    more.length === 1 && /^(?:_history|[0-9a-f]{7,40})$/iu.test(more[0]);
+  if (UI_PAGE.test(first) || revision) {
+    return { kind: "ui" };
+  }
+  if (more.length > 0) {
+    // GitHub serves a page's file at its path (`/wiki/dir/Page.md`) raw.
+    const name = MARKUP.test(rest)
+      ? findPage(ctx.index, pageNameOf(rest))
+      : null;
+    return name !== null && ctx.files[name] === rest
+      ? { kind: "page", raw: true, target: `${name}${hash}` }
+      : { kind: "unknown" };
+  }
+  return { kind: "page", raw: MARKUP.test(first), target: `${first}${hash}` };
+};
+
+/** A wiki file an image source names, `{ outside: true }` for a path above the wiki, or null. */
+const wikiFileOf = (ctx, src) => {
+  const raw = ctx.urls.raw.exec(src);
+  if (raw) {
+    return { file: decode(raw.groups.file) };
+  }
+  const mirrored = ctx.urls.mirror?.exec(src);
+  if (mirrored) {
+    return { file: decode(mirrored.groups.file) };
+  }
+  if (src.startsWith("#") || src.startsWith("//")) {
+    return null;
+  }
+  const relative = !URL_SCHEME.test(src) && !src.startsWith("/");
+  const absolute = relative
+    ? resolveUrl(src, `${ctx.urls.base}${encodeURIComponent(ctx.name)}`)
+    : src;
+  const match = absolute === null ? null : ctx.urls.wiki.exec(absolute);
+  if (match) {
+    const rest = decode((match.groups.rest ?? "").replace(/^\//u, ""));
+    return posix.extname(rest) === "" ? null : { file: rest };
+  }
+  return relative && absolute !== null ? { outside: true } : null;
+};
+
+// --- Findings ----------------------------------------------------------------------
+
+const createPage = (file, name) => ({
+  edits: {},
+  file,
+  name,
+  reviews: [],
+});
+
+const edit = (page, kind, count = 1) => {
+  page.edits[kind] = (page.edits[kind] ?? 0) + count;
+};
+
+const review = (page, line, message) => {
+  page.reviews.push({ line, message });
+};
+
+// --- Links and images -----------------------------------------------------------
+
+/** An image source → its new source, "" to drop an image GitHub couldn't show either, or null (keep). */
+const rewriteImage = (ctx, rawSrc) => {
+  const src = unwrapAngle(rawSrc);
+  if (ctx.done.has(src)) {
+    return null;
+  }
+  const found = wikiFileOf(ctx, src);
+  const relative = !URL_SCHEME.test(src) && !src.startsWith("/");
+  if (found?.outside || (found && relative && !ctx.fileExists(found.file))) {
+    review(
+      ctx.page,
+      ctx.line,
+      `image ${src} pointed at nothing on GitHub (${found.outside ? "above the wiki root" : "no such file"}): dropped`
+    );
+    edit(ctx.page, "broken image dropped");
+    return "";
+  }
+  if (found && !ctx.fileExists(found.file)) {
+    review(
+      ctx.page,
+      ctx.line,
+      `image ${src} names a file the wiki doesn't have`
+    );
+    return null;
+  }
+  if (found) {
+    ctx.images.add(found.file);
+    edit(ctx.page, "wiki image → file beside the pages");
+    const moved = relativeAsset(ctx.dest, `${ctx.content}/${found.file}`);
+    ctx.done.add(moved);
+    return moved;
+  }
+  if (ATTACHMENT.test(src)) {
+    review(ctx.page, ctx.line, `uploaded attachment ${src}: vendor it`);
+    return null;
+  }
+  const blob = BLOB.exec(src);
+  if (blob) {
+    edit(ctx.page, "blob image URL → raw URL");
+    return `https://raw.githubusercontent.com/${blob.groups.owner}/${blob.groups.repo}/${blob.groups.rest}`;
+  }
+  return null;
+};
+
+/** A page target → `{ href }`; a wiki link to a missing page, or any link to a left-out page, → `{ unlink }`. */
+const pageHref = (ctx, target, how, hint = "") => {
+  const result = resolvePage(ctx.index, target, ctx.name);
+  if (result.kind === "missing" && how !== "[[wiki link]]") {
+    review(
+      ctx.page,
+      ctx.line,
+      `${how} ${target} names no page in the wiki, so it was broken on GitHub too: retarget it or unlink it`
+    );
+    return null;
+  }
+  if (result.kind === "missing" || result.kind === "dropped") {
+    const why =
+      result.kind === "missing"
+        ? "names no page in the wiki"
+        : "names a page you left out";
+    review(
+      ctx.page,
+      ctx.line,
+      `${how} ${target} ${why}: made plain text${hint}`
+    );
+    return { unlink: true };
+  }
+  if (result.kind === "moved") {
+    edit(ctx.page, `${how} to a moved page → its target`);
+  } else {
+    edit(ctx.page, `${how} → route`);
+  }
+  return { href: result.href };
+};
+
+/** A Markdown or HTML link destination → `{ href }`, `{ unlink: true }`, or null (keep). */
+const anchorHref = (ctx, dest) => {
+  const anchor = cleanAnchor(dest.slice(1));
+  if (anchor === dest.slice(1)) {
+    return null;
+  }
+  edit(ctx.page, "#user-content- anchor → its id");
+  return { href: `#${anchor}` };
+};
+
+/** A root path: into the wiki (handled with absolute URLs), elsewhere in the repository, or neither. */
+const rootPathHref = (ctx, dest) => {
+  if (ctx.urls.wiki.test(dest)) {
+    return { wiki: true };
+  }
+  if (ctx.urls.repoRoot.test(dest)) {
+    edit(ctx.page, "repository path → absolute GitHub URL");
+    return { href: `https://github.com${dest}` };
+  }
+  return null;
+};
+
+const wikiHref = (ctx, dest, target, relative) => {
+  if (target.kind === "ui") {
+    review(
+      ctx.page,
+      ctx.line,
+      `${dest} points at the wiki's UI: it stops working with the wiki`
+    );
+    return null;
+  }
+  if (target.kind === "file") {
+    review(
+      ctx.page,
+      ctx.line,
+      `${dest} links ${target.file}, a file stored in the wiki: copy it to public/ and link /${target.file}`
+    );
+    return null;
+  }
+  if (target.kind === "unknown") {
+    review(
+      ctx.page,
+      ctx.line,
+      `${dest} names no page or file in the wiki, so it was broken on GitHub too: retarget it or unlink it`
+    );
+    return null;
+  }
+  const result = pageHref(
+    ctx,
+    decode(target.target),
+    relative ? "page-name link" : "wiki URL"
+  );
+  if (target.raw && result?.href) {
+    review(
+      ctx.page,
+      ctx.line,
+      `${dest} opened the page's raw file on GitHub: now its page`
+    );
+  }
+  return result;
+};
+
+/** A Markdown or HTML link destination → `{ href }`, `{ unlink: true }`, or null (keep). */
+const rewriteHref = (ctx, rawDest) => {
+  const dest = unwrapAngle(rawDest);
+  if (dest.startsWith("#")) {
+    return anchorHref(ctx, dest);
+  }
+  const mirrored = ctx.urls.mirror?.exec(dest);
+  if (mirrored && MARKUP.test(mirrored.groups.file)) {
+    const name = pageNameOf(decode(mirrored.groups.file));
+    return pageHref(ctx, `${name}${mirrored.groups.hash ?? ""}`, "mirror link");
+  }
+  if (dest.startsWith("/") && !dest.startsWith("//")) {
+    const rooted = rootPathHref(ctx, dest);
+    if (rooted === null || rooted.href) {
+      return rooted;
+    }
+  }
+  const relative =
+    !URL_SCHEME.test(dest) && !dest.startsWith("/") && dest !== "";
+  const absolute = relative
+    ? resolveUrl(dest, `${ctx.urls.base}${encodeURIComponent(ctx.name)}`)
+    : dest;
+  const target = absolute === null ? null : wikiTarget(ctx, absolute);
+  if (target !== null) {
+    return wikiHref(ctx, dest, target, relative);
+  }
+  if (relative && absolute !== null) {
+    edit(ctx.page, "relative link outside the wiki → absolute GitHub URL");
+    return { href: absolute };
+  }
+  return null;
+};
+
+const escapeHtml = (text) =>
+  text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+
+/** A link in the page's syntax: Markdown, or `<a>` inside an HTML block, where Markdown stays literal. */
+const linkMarkup = (ctx, text, href) => {
+  if (!ctx.html) {
+    return `[${text}](${href})`;
+  }
+  edit(ctx.page, "link in an HTML block written as <a href>");
+  return `<a href="${escapeHtml(href)}">${escapeHtml(text)}</a>`;
+};
+
+/** A wiki image tag's path: `/x.png` is the wiki root; a path the root lacks may sit in the page's folder. */
+const imageTagPath = (ctx, first) => {
+  const file = first.replace(/^\/(?!\/)/u, "");
+  const folder = posix.dirname(ctx.page.file);
+  if (
+    URL_SCHEME.test(file) ||
+    ctx.fileExists(file) ||
+    folder === "." ||
+    !ctx.fileExists(posix.join(folder, file))
+  ) {
+    return file;
+  }
+  review(
+    ctx.page,
+    ctx.line,
+    `image ${first} found only in the page's folder (${folder}/), which is where gollum looks: check the live page`
+  );
+  return posix.join(folder, file);
+};
+
+/** `[[image.png|alt=Text,frame]]`: an image whenever the first part names one, as on GitHub. */
+const convertImageTag = (ctx, first, parts) => {
+  const options = parts
+    .slice(1)
+    .flatMap((part) => part.split(","))
+    .map((option) => option.trim())
+    .filter(Boolean);
+  const alt =
+    options
+      .find((option) => /^alt\s*=/iu.test(option))
+      ?.replace(/^alt\s*=\s*/iu, "") ?? "";
+  const dropped = options.filter((option) => !/^alt\s*=/iu.test(option));
+  if (dropped.length > 0) {
+    review(ctx.page, ctx.line, `image options dropped: ${dropped.join(", ")}`);
+  }
+  const file = imageTagPath(ctx, first);
+  const src = rewriteImage(ctx, file);
+  if (src === "") {
+    return "";
+  }
+  if (ctx.html) {
+    review(
+      ctx.page,
+      ctx.line,
+      `[[${first}]] sits in an HTML block, where a Markdown image shows as text: write it as <img src="${src ?? file}" />, which Blume publishes with the page, or move the image out of the block`
+    );
+  }
+  edit(ctx.page, "[[image]] → Markdown image");
+  return `![${alt}](${src ?? file})`;
+};
+
+/** A wiki link's target that names a file stored in the wiki (`[[Spec|docs/spec.pdf]]`), not a page. */
+const isWikiFile = (ctx, target) => {
+  const file = target.replace(/^\//u, "");
+  return (
+    posix.extname(file) !== "" &&
+    !MARKUP.test(file) &&
+    findPage(ctx.index, file) === null &&
+    ctx.fileExists(file)
+  );
+};
+
+/** For `[[Page|text]]` in a Markdown page: the target-first order GitHub's docs show, which only MediaWiki pages use. */
+const swappedHint = (ctx, parts) => {
+  if (
+    parts.length !== 2 ||
+    resolvePage(ctx.index, parts[1].trim(), ctx.name).kind !== "missing" ||
+    resolvePage(ctx.index, parts[0].trim(), ctx.name).kind === "missing"
+  ) {
+    return "";
+  }
+  return ` (${parts[0].trim()} is a page: a Markdown page puts the text first, so GitHub showed a link to a missing page too)`;
+};
+
+const convertWikiLink = (ctx, inner) => {
+  const parts = inner.split(PIPE);
+  const first = parts[0].trim();
+  if (first === "_TOC_") {
+    edit(ctx.page, "[[_TOC_]] removed");
+    return "";
+  }
+  if (IMAGE.test(first.split("#")[0])) {
+    return convertImageTag(ctx, first, parts);
+  }
+  if (parts.length > 2) {
+    review(
+      ctx.page,
+      ctx.line,
+      `[[${inner}]] has more than one |: convert it by hand`
+    );
+    return null;
+  }
+  const text = first;
+  const target = (parts[1] ?? parts[0]).trim();
+  if (EXTERNAL.test(target)) {
+    edit(ctx.page, "[[text|URL]] → link");
+    return linkMarkup(ctx, text, target);
+  }
+  if (isWikiFile(ctx, target)) {
+    review(
+      ctx.page,
+      ctx.line,
+      `[[${inner}]] links ${target}, a file stored in the wiki: copy it to public/ and link /${target.replace(/^\//u, "")}`
+    );
+    return null;
+  }
+  const result = pageHref(
+    ctx,
+    target,
+    "[[wiki link]]",
+    swappedHint(ctx, parts)
+  );
+  return result.unlink ? text : linkMarkup(ctx, text, result.href);
+};
+
+/** One `[[…]]` match: `'[[…]]` stays (gollum's escape), the rest convert. */
+const convertWikiMatch = (ctx, group) => {
+  const quote = group("quote");
+  const after = group("after");
+  if (quote && !after) {
+    review(
+      ctx.page,
+      ctx.line,
+      `'[[${group("inner")}]] is gollum's escape for literal brackets, so it was left as is: check the live page, and drop the ' if it showed the brackets`
+    );
+    return null;
+  }
+  const converted = convertWikiLink(ctx, group("inner"));
+  return converted === null ? null : `${quote}${converted}${after}`;
+};
+
+const convertImages = (ctx, line) =>
+  replaceOutside(line, MD_IMAGE, (group) => {
+    const src = rewriteImage(ctx, group("dest"));
+    if (src === null || src === "") {
+      return src;
+    }
+    return `![${group("alt")}](${src}${group("title") ?? ""})`;
+  });
+
+const convertLinks = (ctx, line) =>
+  replaceOutside(line, MD_LINK, (group) => {
+    const label = group("label");
+    const result = rewriteHref(ctx, group("dest"));
+    if (result === null) {
+      return null;
+    }
+    if (result.unlink) {
+      return label;
+    }
+    const title = group("title") ?? "";
+    // Pandoc writes a MediaWiki link's text as its title too.
+    const keepTitle = title && title.trim().slice(1, -1) !== label;
+    return `[${label}](${result.href}${keepTitle ? title : ""})`;
+  });
+
+const convertRawHrefs = (ctx, line) =>
+  replaceOutside(line, RAW_HREF, (group, original) => {
+    const dest = group("dest");
+    const result = rewriteHref(ctx, dest);
+    if (result === null || result.unlink) {
+      return null;
+    }
+    return original.replace(dest, result.href);
+  });
+
+const urlReplacement = (ctx, url) => {
+  const target = wikiTarget(ctx, url);
+  if (target?.kind !== "page") {
+    review(ctx.page, ctx.line, `bare wiki URL left as is: ${url}`);
+    return null;
+  }
+  const result = resolvePage(ctx.index, decode(target.target), ctx.name);
+  if (result.kind === "missing" || result.kind === "dropped") {
+    review(
+      ctx.page,
+      ctx.line,
+      `bare wiki URL to a page that isn't kept: ${url}`
+    );
+    return null;
+  }
+  edit(ctx.page, "bare wiki URL → link");
+  return linkMarkup(ctx, titleOf(result.name), result.href);
+};
+
+const convertBareUrls = (ctx, line) => {
+  const angled = replaceOutside(line, ctx.urls.angle, (group) =>
+    urlReplacement(ctx, group("url"))
+  );
+  return replaceOutside(angled, ctx.urls.bare, (group) => {
+    const url = group("url");
+    const trail = TRAILING_PUNCTUATION.exec(url)?.[0] ?? "";
+    const link = urlReplacement(ctx, url.slice(0, url.length - trail.length));
+    return link === null ? null : `${link}${trail}`;
+  });
+};
+
+const convertEmoji = (ctx, line, heading) =>
+  replaceOutside(
+    line,
+    SHORTCODE,
+    (group, original) => {
+      const emoji = ctx.emoji.get(group("name"));
+      if (!emoji) {
+        return null;
+      }
+      if (heading) {
+        review(
+          ctx.page,
+          ctx.line,
+          `${original} in a heading: GitHub's id spelled the name; convert it and pin the old id with [#…]`
+        );
+        return null;
+      }
+      edit(ctx.page, "emoji shortcode → emoji");
+      return emoji;
+    },
+    { destinations: true }
+  );
+
+/** `\[\[…\]\]` is how pandoc writes a wiki link; in a page that was always Markdown, GitHub showed the brackets. */
+const convertEscapedWikiLink = (ctx, inner) => {
+  const converted = convertWikiLink(ctx, inner.replaceAll(String.raw`\|`, "|"));
+  if (converted !== null) {
+    review(
+      ctx.page,
+      ctx.line,
+      String.raw`\[\[${inner}\]\] read as a wiki link (pandoc's escape): if this page was Markdown on GitHub, it showed the brackets, so restore them`
+    );
+  }
+  return converted;
+};
+
+const convertInline = (ctx, line, heading = false) => {
+  let next = replaceOutside(
+    line,
+    WIKI_LINK,
+    (group) => convertWikiMatch(ctx, group),
+    { elements: true }
+  );
+  next = replaceOutside(
+    next,
+    ESCAPED_WIKI_LINK,
+    (group) => convertEscapedWikiLink(ctx, group("inner")),
+    { elements: true }
+  );
+  next = convertImages(ctx, next);
+  next = convertLinks(ctx, next);
+  next = convertRawHrefs(ctx, next);
+  next = convertBareUrls(ctx, next);
+  return ctx.emoji.size > 0 ? convertEmoji(ctx, next, heading) : next;
+};
+
+// --- Line structure -------------------------------------------------------------
+
+const indentWidth = (text) =>
+  [...text].reduce((width, char) => width + (char === "\t" ? 4 : 1), 0);
+
+/**
+ * One state per line: `open`/`fence`/`close` for fenced code (any indent, in
+ * a quote or not), `comment` inside a multi-line HTML comment, `indented` for
+ * indented code, `prose` otherwise.
+ */
+const closesFence = (fence, line) => {
+  const close = FENCE.exec(line);
+  return (
+    close?.groups.marker[0] === fence.char &&
+    close.groups.marker.length >= fence.length &&
+    close.groups.info.trim() === ""
+  );
+};
+
+const opensFence = (line) => {
+  const open = FENCE.exec(line);
+  if (
+    open === null ||
+    (open.groups.marker.startsWith("`") && open.groups.info.includes("`"))
+  ) {
+    return null;
+  }
+  return { char: open.groups.marker[0], length: open.groups.marker.length };
+};
+
+/** The content column of the list a line belongs to, or -1 outside lists. */
+const nextListIndent = (line, listIndent) => {
+  if (line.trim() === "") {
+    return listIndent;
+  }
+  const width = indentWidth(/^[ \t]*/u.exec(line)[0]);
+  const item = LIST_ITEM.exec(line);
+  if (item && width < listIndent + 4) {
+    return indentWidth(
+      `${item.groups.indent}${item.groups.marker}${item.groups.gap}`
+    );
+  }
+  return width === 0 ? -1 : listIndent;
+};
+
+/**
+ * One state per line: `open`/`fence`/`close` for fenced code (any indent, in
+ * a quote or not), `comment` inside a multi-line HTML comment, `indented` for
+ * indented code, `prose` otherwise.
+ */
+const lineStates = (lines) => {
+  const states = [];
+  let fence = null;
+  let comment = false;
+  let previousBlank = true;
+  let listIndent = -1;
+  for (const line of lines) {
+    if (fence) {
+      const closes = closesFence(fence, line);
+      states.push(closes ? "close" : "fence");
+      fence = closes ? null : fence;
+      previousBlank = false;
+    } else if (comment) {
+      states.push("comment");
+      comment = !line.includes("-->");
+    } else {
+      fence = opensFence(line);
+      if (fence) {
+        states.push("open");
+        continue;
+      }
+      const blank = line.trim() === "";
+      listIndent = nextListIndent(line, listIndent);
+      const width = indentWidth(/^[ \t]*/u.exec(line)[0]);
+      const codeIndent = listIndent === -1 ? 4 : listIndent + 4;
+      const indented =
+        !blank &&
+        width >= codeIndent &&
+        (previousBlank || states.at(-1) === "indented");
+      states.push(indented ? "indented" : "prose");
+      comment =
+        !indented &&
+        line.trimStart().startsWith("<!--") &&
+        !line.includes("-->");
+      previousBlank = blank;
+    }
+  }
+  return states;
+};
+
+const isCode = (state) => state !== "prose";
+
+// CommonMark HTML blocks, whose lines stay raw HTML: Markdown written there
+// shows as text, while GitHub turned `[[…]]` in them into links.
+const HTML_BLOCK_RAW = /^ {0,3}<(?<tag>pre|script|style|textarea)(?:[\s>]|$)/iu;
+const HTML_BLOCK_TAG = new RegExp(
+  String.raw`^ {0,3}<\/?(?:${[
+    "address article aside base basefont blockquote body caption center col",
+    "colgroup dd details dialog dir div dl dt fieldset figcaption figure footer",
+    "form frame frameset h1 h2 h3 h4 h5 h6 head header hr html iframe legend",
+    "li link main menu menuitem nav noframes ol optgroup option p param search",
+    "section summary table tbody td tfoot th thead title tr track ul",
+  ]
+    .join(" ")
+    .replaceAll(" ", "|")})(?:[\s>]|\/>|$)`,
+  "iu"
+);
+const HTML_BLOCK_LONE_TAG =
+  /^ {0,3}(?:<[A-Za-z][\w-]*(?:\s+[^<>]*)?\/?>|<\/[A-Za-z][\w-]*\s*>)[ \t]*$/u;
+
+/** The HTML block opening at `index`: `until` is its closing tag, or null when a blank line ends it. */
+const htmlBlockStart = (lines, index) => {
+  const line = lines[index];
+  const raw = HTML_BLOCK_RAW.exec(line);
+  if (raw) {
+    return { until: new RegExp(String.raw`</${raw.groups.tag}\s*>`, "iu") };
+  }
+  const previousBlank = index === 0 || lines[index - 1].trim() === "";
+  return HTML_BLOCK_TAG.test(line) ||
+    (previousBlank && HTML_BLOCK_LONE_TAG.test(line))
+    ? { until: null }
+    : null;
+};
+
+/** The indexes of prose lines inside an HTML block. */
+const htmlBlockLines = (lines, states) => {
+  const inside = new Set();
+  let block = null;
+  for (const [index, line] of lines.entries()) {
+    if (states[index] !== "prose") {
+      block = null;
+      continue;
+    }
+    block ??= htmlBlockStart(lines, index);
+    if (block === null || (block.until === null && line.trim() === "")) {
+      block = null;
+      continue;
+    }
+    inside.add(index);
+    if (block.until?.test(line)) {
+      block = null;
+    }
+  }
+  return inside;
+};
+
+/** The lines of the paragraph ending at `index`, or null if it isn't a plain paragraph. */
+const paragraphAbove = (lines, states, index) => {
+  let start = index;
+  while (
+    start > 0 &&
+    states[start - 1] === "prose" &&
+    lines[start - 1].trim() !== ""
+  ) {
+    start -= 1;
+  }
+  if (start === index) {
+    return null;
+  }
+  for (let line = start; line < index; line += 1) {
+    const text = lines[line];
+    if (
+      LIST_ITEM.test(text) ||
+      QUOTED.test(text) ||
+      ATX.test(text) ||
+      DEFINITION.test(text) ||
+      /^(?: {4}|\t)/u.test(text) ||
+      /^\s*[|<]/u.test(text)
+    ) {
+      return null;
+    }
+  }
+  return { count: index - start, start };
+};
+
+// --- Page content ------------------------------------------------------------------
+
+const removeFoam = (page, lines) => {
+  const begin = lines.findIndex((line) => FOAM_BEGIN.test(line));
+  const end = lines.findIndex((line) => FOAM_END.test(line));
+  if (begin === -1 || end < begin) {
+    return lines;
+  }
+  edit(page, "Foam autogenerated link block removed");
+  return [...lines.slice(0, begin), ...lines.slice(end + 1)];
+};
+
+/**
+ * Top-level alerts → `:::` directives. Blume renders an alert as a callout in
+ * `.mdx` too, so one this can't rewrite line by line (indented in a list, or
+ * with lazy lines) stays as written and only makes the page `.mdx`.
+ */
+const convertAlerts = (page, lines, states) => {
+  const out = [];
+  let converted = 0;
+  let kept = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const start =
+      states[index] === "prose" ? ALERT_START.exec(lines[index]) : null;
+    if (start === null) {
+      if (states[index] === "prose" && ANY_ALERT.test(lines[index])) {
+        if (/^[ \t]/u.test(lines[index])) {
+          kept += 1;
+        } else {
+          review(
+            page,
+            index + 1,
+            "a GitHub alert with text after its marker: convert it by hand"
+          );
+        }
+      }
+      out.push(lines[index]);
+      continue;
+    }
+    let end = index + 1;
+    while (end < lines.length && QUOTED.test(lines[end])) {
+      end += 1;
+    }
+    const body = lines
+      .slice(index + 1, end)
+      .map((line) => line.replace(/^ {0,3}>[ \t]?/u, ""));
+    if (end < lines.length && lines[end].trim() !== "") {
+      kept += 1;
+      out.push(lines[index]);
+      continue;
+    }
+    if (body.every((line) => line.trim() === "")) {
+      review(
+        page,
+        index + 1,
+        "a GitHub alert with no body lines: convert it by hand"
+      );
+      out.push(lines[index]);
+      continue;
+    }
+    while (body[0].trim() === "") {
+      body.shift();
+    }
+    while (body.at(-1).trim() === "") {
+      body.pop();
+    }
+    const fence = body.some((line) => /^\s*:{3,}/u.test(line)) ? "::::" : ":::";
+    out.push(
+      `${fence}${ALERTS[start.groups.type.toLowerCase()]}`,
+      ...body,
+      fence
+    );
+    converted += 1;
+    index = end - 1;
+  }
+  if (converted > 0) {
+    edit(page, "GitHub alert → ::: directive", converted);
+  }
+  if (kept > 0) {
+    edit(page, "indented or lazy GitHub alert kept: a callout in .mdx", kept);
+  }
+  return { converted, kept, lines: out };
+};
+
+const headingText = (rest) =>
+  rest.replace(HEADING_MARKER, "").replace(CLOSING_HASHES, "").trim();
+
+/** The page's heading plan: the leading H1 to delete, and whether to demote. */
+const planHeadings = (lines, states, title) => {
+  const first = lines.findIndex(
+    (line, index) => states[index] === "prose" && line.trim() !== ""
+  );
+  let deleted = [];
+  if (first !== -1) {
+    const atx = ATX.exec(lines[first]);
+    const underline = SETEXT.exec(lines[first + 1] ?? "");
+    if (atx && atx.groups.prefix === "" && atx.groups.hashes === "#") {
+      deleted =
+        comparable(headingText(atx.groups.rest)) === comparable(title)
+          ? [first]
+          : [];
+    } else if (
+      underline?.groups.marker.startsWith("=") &&
+      states[first + 1] === "prose" &&
+      comparable(lines[first]) === comparable(title)
+    ) {
+      deleted = [first, first + 1];
+    }
+  }
+  const skip = new Set(deleted);
+  const hasH1 = lines.some((line, index) => {
+    if (skip.has(index) || states[index] !== "prose") {
+      return false;
+    }
+    if (ATX.exec(line)?.groups.hashes === "#") {
+      return true;
+    }
+    return (
+      SETEXT.exec(line)?.groups.marker.startsWith("=") === true &&
+      paragraphAbove(lines, states, index) !== null
+    );
+  });
+  return { deleted: skip, hasH1 };
+};
+
+const pinNamedAnchor = (page, line, index) => {
+  const atx = ATX.exec(line);
+  const anchor = atx ? NAMED_ANCHOR.exec(atx.groups.rest) : null;
+  if (anchor === null) {
+    return line;
+  }
+  if (HEADING_MARKER.test(atx.groups.rest)) {
+    review(
+      page,
+      index + 1,
+      "a heading with both <a name> and an id marker: keep one"
+    );
+    return line;
+  }
+  const text = atx.groups.rest.replace(NAMED_ANCHOR, "").trim();
+  edit(page, "<a name> in a heading → [#id]");
+  return `${atx.groups.prefix}${atx.groups.hashes} ${text} [#${anchor.groups.id}]`;
+};
+
+const demoteAtx = (line) => {
+  const atx = ATX.exec(line);
+  if (atx === null || atx.groups.hashes.length >= HEADING_LEVELS) {
+    return line;
+  }
+  return `${atx.groups.prefix}#${atx.groups.hashes}${atx.groups.rest}`;
+};
+
+/** Setext headings → ATX one level down, on a page whose headings are demoted. */
+const demoteSetext = (page, lines, states) => {
+  const out = [...lines];
+  for (let index = 0; index < lines.length; index += 1) {
+    const underline =
+      states[index] === "prose" ? SETEXT.exec(lines[index]) : null;
+    const paragraph = underline ? paragraphAbove(lines, states, index) : null;
+    if (paragraph === null) {
+      continue;
+    }
+    const level = underline.groups.marker.startsWith("=") ? 2 : 3;
+    if (paragraph.count > 1) {
+      review(
+        page,
+        index + 1,
+        `a ${paragraph.count}-line setext heading can't be demoted: rewrite it as one ${"#".repeat(level)} line`
+      );
+      continue;
+    }
+    out[paragraph.start] =
+      `${"#".repeat(level)} ${lines[paragraph.start].trim()}`;
+    out[index] = null;
+    edit(page, "setext heading → ATX, demoted");
+  }
+  return out.filter((line) => line !== null);
+};
+
+const convertFenceInfo = (page, line, index) => {
+  const open = FENCE.exec(line);
+  const [language = "", ...rest] = open.groups.info.trim().split(/\s+/u);
+  const lower = language.toLowerCase();
+  const mapped = FENCE_LANGUAGES[lower] ?? lower;
+  if (DROPPED_FENCES.has(lower)) {
+    review(
+      page,
+      index + 1,
+      `a ${lower} block renders as code in Blume: maps and 3D models drop`
+    );
+  }
+  if (mapped === language) {
+    return { language: lower, line };
+  }
+  edit(page, `fence language ${language} → ${mapped}`);
+  const info = [mapped, ...rest].join(" ");
+  return {
+    language: mapped,
+    line: `${open.groups.prefix}${open.groups.marker}${info}`,
+  };
+};
+
+/** Delete link definitions a same-label definition above already shadows, and rewrite the rest. */
+const convertDefinition = (ctx, line, index, lines, seen) => {
+  const definition = DEFINITION.exec(line);
+  const previous = lines[index - 1] ?? "";
+  const startsBlock =
+    index === 0 ||
+    previous.trim() === "" ||
+    DEFINITION.test(previous) ||
+    ATX.test(previous) ||
+    /^\s*<!--[\s\S]*-->\s*$/u.test(previous) ||
+    previous.includes("-->");
+  if (definition === null || !startsBlock) {
+    return { isDefinition: false, line };
+  }
+  const label = definition.groups.label
+    .toLowerCase()
+    .replaceAll(/\s+/gu, " ")
+    .trim();
+  if (seen.has(label)) {
+    edit(ctx.page, "shadowed duplicate link definition removed");
+    return { isDefinition: true, line: null };
+  }
+  seen.add(label);
+  const result = rewriteHref(ctx, definition.groups.dest);
+  if (result === null || result.unlink) {
+    return { isDefinition: true, line };
+  }
+  const { indent, rest } = definition.groups;
+  return {
+    isDefinition: true,
+    line: `${indent}[${definition.groups.label}]: ${result.href}${rest}`,
+  };
+};
+
+const RAW_IMG_SRC =
+  /<img\b[^<>]*?\bsrc\s*=\s*(?<quote>["'])(?<src>[^"']*)\k<quote>/giu;
+
+/**
+ * A raw `<img>` of a wiki file inside other HTML: its `src` reads from the
+ * wiki root, not the page's new folder, so it needs a hand.
+ */
+const reviewRawImages = (ctx, line) => {
+  for (const match of mask(line).matchAll(RAW_IMG_SRC)) {
+    const found = wikiFileOf(ctx, match.groups.src);
+    if (found?.file) {
+      const file = `${ctx.content}/${found.file}`;
+      review(
+        ctx.page,
+        ctx.line,
+        `raw <img src="${match.groups.src}"> shows a file stored in the wiki: copy it to ${file} and point src at ${relativeAsset(ctx.dest, file)}, which Blume publishes with the page, or make it a Markdown image`
+      );
+    }
+  }
+};
+
+const convertRawImageLine = (ctx, line, previous) => {
+  const img = RAW_IMG_LINE.exec(line);
+  if (img === null || (previous ?? "").trim() !== "") {
+    reviewRawImages(ctx, line);
+    return line;
+  }
+  const attribute = (name) =>
+    new RegExp(
+      String.raw`\b${name}\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>`,
+      "iu"
+    ).exec(img.groups.attributes)?.groups.value ?? null;
+  const srcValue = attribute("src");
+  const found = srcValue ? wikiFileOf(ctx, srcValue) : null;
+  if (found === null || found.outside) {
+    return line;
+  }
+  const src = rewriteImage(ctx, srcValue);
+  if (src === null || src === "") {
+    return src === "" ? "" : line;
+  }
+  const dropped = ["width", "height", "align"]
+    .map((name) => [name, attribute(name)])
+    .filter(([, value]) => value !== null)
+    .map(([name, value]) => `${name}=${value}`);
+  if (dropped.length > 0) {
+    review(
+      ctx.page,
+      ctx.line,
+      `raw <img> → Markdown image; dropped ${dropped.join(", ")}`
+    );
+  }
+  edit(ctx.page, "raw <img> → Markdown image");
+  return `${img.groups.indent}![${attribute("alt") ?? ""}](${src})`;
+};
+
+// --- MDX safety ----------------------------------------------------------------------
+
+const commentText = (text) =>
+  text
+    .replace(/^\s*<!--/u, "")
+    .replace(/--!?>\s*$/u, "")
+    .replaceAll("*/", "* /")
+    .replaceAll(/\s+/gu, " ")
+    .trim();
+
+const mdxComments = (page, lines, states) => {
+  const out = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (
+      states[index] === "prose" &&
+      line.trimStart().startsWith("<!--") &&
+      !line.includes("-->")
+    ) {
+      let end = index;
+      while (end + 1 < lines.length && states[end + 1] === "comment") {
+        end += 1;
+      }
+      const [indent] = /^[ \t]*/u.exec(line);
+      out.push(
+        `${indent}{/* ${commentText(lines.slice(index, end + 1).join(" "))} */}`
+      );
+      edit(page, "HTML comment → MDX comment");
+      index = end;
+      continue;
+    }
+    if (states[index] !== "prose") {
+      out.push(line);
+      continue;
+    }
+    out.push(
+      replaceOutside(
+        line,
+        /<!--(?<text>[\s\S]*?)-->/dgu,
+        (group) => {
+          edit(page, "HTML comment → MDX comment");
+          return `{/* ${commentText(group("text"))} */}`;
+        },
+        { comments: false }
+      )
+    );
+  }
+  return out;
+};
+
+const mdxLine = (page, line, index) => {
+  let next = replaceOutside(line, ANGLE_AUTOLINK, (group) => {
+    edit(page, "<https://…> autolink → link");
+    return `[${group("url")}](${group("url")})`;
+  });
+  next = replaceOutside(next, VOID_TAG, (group) => {
+    edit(page, "void tag closed");
+    return `<${group("tag")}${group("attributes").trimEnd()} />`;
+  });
+  const strays = replaceOutside(
+    next,
+    STRAY_ANGLE,
+    () => {
+      edit(page, "bare < → &lt;");
+      return "&lt;";
+    },
+    { destinations: true }
+  );
+  const braces = replaceOutside(
+    strays,
+    BRACE,
+    (group, original) => {
+      edit(page, "brace in prose escaped");
+      return `\\${original}`;
+    },
+    { destinations: true, tags: true }
+  );
+  for (const match of mask(braces).matchAll(OPEN_TAG)) {
+    if (!HTML_TAGS.has(match.groups.tag)) {
+      review(
+        page,
+        index + 1,
+        `<${match.groups.tag}> reads as a JSX element in MDX: escape it or put it in code`
+      );
+    }
+  }
+  return braces;
+};
+
+const HTML_BLOCK = /<(?:center|details|div|li|ol|p|summary|table|td|tr|ul)\b/iu;
+
+/** Whether the indented block starting at `index` sits at the top level, not inside a list. */
+const topLevelBlock = (lines, states, index) => {
+  for (let line = index - 1; line >= 0; line -= 1) {
+    if (lines[line].trim() !== "" && states[line] !== "indented") {
+      return !LIST_ITEM.test(lines[line]) && /^\S/u.test(lines[line]);
+    }
+  }
+  return true;
+};
+
+/** The last line of the indented block starting at `index` (blank lines inside it included). */
+const indentedBlockEnd = (lines, states, index) => {
+  let end = index;
+  for (let line = index + 1; line < lines.length; line += 1) {
+    if (states[line] === "indented") {
+      end = line;
+    } else if (lines[line].trim() !== "") {
+      break;
+    }
+  }
+  return end;
+};
+
+/** MDX has no indented code: fence each top-level indented block, and report the rest. */
+const fenceIndentedCode = (page, lines, states) => {
+  const out = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (states[index] !== "indented" || states[index - 1] === "indented") {
+      out.push(lines[index]);
+      continue;
+    }
+    if (!topLevelBlock(lines, states, index)) {
+      review(
+        page,
+        index + 1,
+        "indented code inside a list renders as text in MDX: fence it"
+      );
+      out.push(lines[index]);
+      continue;
+    }
+    const end = indentedBlockEnd(lines, states, index);
+    const body = lines
+      .slice(index, end + 1)
+      .map((line) => line.replace(/^(?: {4}|\t| {0,3}\t)/u, ""));
+    const longest = Math.max(
+      2,
+      ...body
+        .flatMap((line) => line.match(/`+/gu) ?? [])
+        .map((run) => run.length)
+    );
+    const fence = "`".repeat(longest + 1);
+    out.push(fence, ...body, fence);
+    edit(page, "indented code → fenced block");
+    index = end;
+  }
+  return out;
+};
+
+const mdxSafe = (page, lines) => {
+  const fenced = fenceIndentedCode(page, lines, lineStates(lines));
+  const states = lineStates(fenced);
+  const html = fenced.findIndex(
+    (line, index) => states[index] === "prose" && HTML_BLOCK.test(mask(line))
+  );
+  if (html !== -1) {
+    review(
+      page,
+      html + 1,
+      "raw HTML blocks in an .mdx page: MDX reads Markdown inside them only with blank lines around it, and fails on interleaved tags; check the build"
+    );
+  }
+  const safe = fenced.map((line, index) =>
+    states[index] === "prose" ? mdxLine(page, line, index) : line
+  );
+  return mdxComments(page, safe, lineStates(safe));
+};
+
+// --- One page ---------------------------------------------------------------------------
+
+/** One line of a fence: its opener's language fixed, a ```math fence turned into $$. */
+const convertFenceLine = (ctx, line, index, state, flags) => {
+  if (state === "open") {
+    const fence = convertFenceInfo(ctx.page, line, index);
+    const bare = FENCE.exec(fence.line).groups.prefix === "";
+    flags.needsMdx ||= fence.language === "mermaid";
+    flags.math = fence.language === "math" && bare;
+    if (flags.math) {
+      edit(ctx.page, "```math → $$ block");
+      flags.needsMdx = true;
+    }
+    return flags.math ? "$$" : fence.line;
+  }
+  if (state === "close") {
+    const out = flags.math ? "$$" : line;
+    flags.math = false;
+    return out;
+  }
+  if (state === "indented" && line.includes("[[")) {
+    review(
+      ctx.page,
+      index + 1,
+      "[[…]] in an indented block was left alone: check whether it's code"
+    );
+  }
+  return line;
+};
+
+const convertProseLine = (ctx, lines, index, plan, seen) => {
+  const line = lines[index];
+  const definition = convertDefinition(ctx, line, index, lines, seen);
+  if (definition.isDefinition) {
+    return definition.line;
+  }
+  // In an HTML block, `#` lines are text, not headings.
+  const pinned = ctx.html ? line : pinNamedAnchor(ctx.page, line, index);
+  const isHeading = !ctx.html && ATX.test(pinned);
+  const imaged = convertRawImageLine(ctx, pinned, lines[index - 1]);
+  const converted = convertInline(ctx, imaged, isHeading);
+  return plan.hasH1 && isHeading ? demoteAtx(converted) : converted;
+};
+
+const trimBlankEdges = (lines) => {
+  const first = lines.findIndex((line) => line.trim() !== "");
+  if (first === -1) {
+    return [];
+  }
+  const last = lines.findLastIndex((line) => line.trim() !== "");
+  return lines.slice(first, last + 1);
+};
+
+const convertBody = (ctx, text) => {
+  const { page } = ctx;
+  const lines = removeFoam(
+    page,
+    text
+      .replace(/^\u{FEFF}/u, "")
+      .replaceAll("\r\n", "\n")
+      .split("\n")
+  );
+  const alerts = convertAlerts(page, lines, lineStates(lines));
+  const current = alerts.lines;
+  const states = lineStates(current);
+  const html = htmlBlockLines(current, states);
+  const plan = planHeadings(
+    current,
+    states.map((state, index) => (html.has(index) ? "html" : state)),
+    titleOf(ctx.name)
+  );
+  if (plan.deleted.size > 0) {
+    edit(page, "leading H1 repeating the page name removed");
+  }
+  const flags = { math: false, needsMdx: alerts.converted + alerts.kept > 0 };
+  const seen = new Set();
+  const out = [];
+  for (let index = 0; index < current.length; index += 1) {
+    ctx.line = index + 1;
+    ctx.html = html.has(index);
+    if (plan.deleted.has(index)) {
+      continue;
+    }
+    out.push(
+      isCode(states[index])
+        ? convertFenceLine(ctx, current[index], index, states[index], flags)
+        : convertProseLine(ctx, current, index, plan, seen)
+    );
+  }
+  let result = out.filter((line) => line !== null);
+  if (plan.hasH1) {
+    edit(page, "page with body H1s: every heading demoted one level");
+    result = demoteSetext(page, result, lineStates(result));
+  }
+  if (flags.needsMdx) {
+    result = mdxSafe(page, result);
+  }
+  return { body: trimBlankEdges(result).join("\n"), needsMdx: flags.needsMdx };
+};
+
+const frontmatter = (fields) => {
+  const lines = ["---", `title: ${yamlScalar(fields.title)}`];
+  if (fields.label) {
+    lines.push("sidebar:", `  label: ${yamlScalar(fields.label)}`);
+  }
+  if (fields.slug) {
+    lines.push(`slug: ${yamlScalar(fields.slug)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+};
+
+// --- The sidebar ------------------------------------------------------------------
+
+const HEADING_LABEL = /^ {0,3}#{1,6}[ \t]+(?<text>.*?)[ \t#]*$/u;
+const BOLD_LABEL =
+  /^ {0,3}(?:\*\*|__)(?<text>[^*_]+?)(?:\*\*|__)[ \t]*:?[ \t]*$/u;
+const ONLY_WIKI_LINK = /^\[\[(?<inner>[^[\]]+)\]\]$/u;
+const ONLY_MD_LINK = new RegExp(
+  String.raw`^\[(?<text>[^[\]]+)\]\(\s*${DESTINATION}${TITLE}\s*\)$`,
+  "u"
+);
+
+const parseItem = (content) => {
+  const text = content.trim();
+  const wiki = ONLY_WIKI_LINK.exec(text);
+  if (wiki) {
+    const parts = wiki.groups.inner.split(PIPE);
+    if (parts.length > 2) {
+      return { kind: "other", text };
+    }
+    const target = (parts[1] ?? parts[0]).trim();
+    return { kind: "wiki", label: parts[0].trim(), target };
+  }
+  const link = ONLY_MD_LINK.exec(text);
+  if (link) {
+    return {
+      dest: unwrapAngle(link.groups.dest),
+      kind: "link",
+      label: link.groups.text.trim(),
+    };
+  }
+  if (text.includes("[") || text.includes("<")) {
+    return { kind: "other", text };
+  }
+  return { kind: "label", label: plainText(text) };
+};
+
+/** `_Sidebar.md` → groups of item trees, in order. */
+const parseSidebar = (text) => {
+  const groups = [];
+  const notes = [];
+  let group = null;
+  let stack = [];
+  const lines = text.replaceAll("\r\n", "\n").split("\n");
+  const states = lineStates(lines);
+  for (const [index, line] of lines.entries()) {
+    if (line.trim() === "" || isCode(states[index])) {
+      continue;
+    }
+    const heading = HEADING_LABEL.exec(line) ?? BOLD_LABEL.exec(line);
+    if (heading) {
+      group = {
+        children: [],
+        head: parseItem(heading.groups.text),
+        line: index + 1,
+      };
+      groups.push(group);
+      stack = [];
+      continue;
+    }
+    const item = LIST_ITEM.exec(line);
+    if (item === null) {
+      notes.push(
+        `_Sidebar line ${index + 1} has no place in Blume's sidebar: ${line.trim()}`
+      );
+      continue;
+    }
+    const indent = indentWidth(item.groups.indent);
+    const node = {
+      ...parseItem(item.groups.content),
+      children: [],
+      line: index + 1,
+    };
+    while (stack.length > 0 && stack.at(-1).indent >= indent) {
+      stack.pop();
+    }
+    if (group === null) {
+      group = { children: [], head: null, line: index + 1 };
+      groups.push(group);
+    }
+    const parent = stack.at(-1)?.node ?? group;
+    parent.children.push(node);
+    stack.push({ indent, node });
+  }
+  return { groups, notes };
+};
+
+/** A sidebar item → `{ kind: "page", name }`, `{ kind: "external", href }`, or `{ kind: "skip", why }`. */
+const sidebarTarget = (ctx, node) => {
+  if (node.kind === "label" || node.kind === "other") {
+    return { kind: "label" };
+  }
+  let { target } = node;
+  if (node.kind === "link") {
+    const relative = !URL_SCHEME.test(node.dest) && !node.dest.startsWith("/");
+    const absolute = relative
+      ? resolveUrl(node.dest, ctx.urls.base)
+      : node.dest;
+    const wiki = absolute === null ? null : wikiTarget(ctx, absolute);
+    if (wiki === null) {
+      return URL_SCHEME.test(node.dest)
+        ? { href: node.dest, kind: "external" }
+        : { kind: "skip", why: `${node.dest} isn't a page` };
+    }
+    if (wiki.kind !== "page") {
+      return { kind: "skip", why: `${node.dest} isn't a page` };
+    }
+    target = decode(wiki.target);
+  }
+  if (EXTERNAL.test(target)) {
+    return { href: target, kind: "external" };
+  }
+  if (target.includes("#")) {
+    return {
+      kind: "skip",
+      why: `${target} links a heading, not a page (the page's outline lists it)`,
+    };
+  }
+  const result = resolvePage(ctx.index, target, "");
+  if (result.kind !== "content") {
+    return {
+      kind: "skip",
+      why: `${target} names a page that isn't kept (${result.kind})`,
+    };
+  }
+  if (!MARKDOWN.test(ctx.files[result.name])) {
+    return {
+      kind: "skip",
+      why: `${ctx.files[result.name]} isn't Markdown yet (convert it, then rerun)`,
+    };
+  }
+  return { kind: "page", name: result.name };
+};
+
+const uniqueName = (taken, base) => {
+  let name = base;
+  for (let count = 2; taken.has(name); count += 1) {
+    name = `${base}-${count}`;
+  }
+  taken.add(name);
+  return name;
+};
+
+const fileBase = (index, name) => {
+  const route = index.routes[name];
+  return route === "/" ? "index" : route.split("/").at(-1);
+};
+
+const createLayout = (ctx) => ({
+  ctx,
+  featured: [],
+  folders: new Map([["", new Set()]]),
+  metas: new Map(),
+  notes: [],
+  placed: new Map(),
+});
+
+const addMeta = (layout, dir, meta) => {
+  layout.metas.set(dir, meta);
+  layout.folders.set(dir, new Set());
+};
+
+const labelFor = (name, text) =>
+  text && comparable(text) !== comparable(titleOf(name)) ? text : null;
+
+const placeNodes = (layout, nodes, dir, pages) => {
+  const { ctx } = layout;
+  for (const node of nodes) {
+    const target = sidebarTarget(ctx, node);
+    if (target.kind === "external") {
+      layout.featured.push({ href: target.href, label: node.label });
+      layout.notes.push(
+        `_Sidebar line ${node.line}: external link "${node.label}" → navigation.featured`
+      );
+      continue;
+    }
+    if (target.kind === "skip") {
+      layout.notes.push(`_Sidebar line ${node.line}: dropped, ${target.why}`);
+      continue;
+    }
+    if (target.kind === "label") {
+      if (node.children.length === 0 || node.kind === "other") {
+        layout.notes.push(
+          `_Sidebar line ${node.line} has no place in Blume's sidebar: ${node.text ?? node.label}`
+        );
+        continue;
+      }
+      const folder = uniqueName(
+        layout.folders.get(dir),
+        `(${slugOf(node.label) || "group"})`
+      );
+      const sub = posix.join(dir, folder);
+      pages.push(folder.slice(1, -1));
+      const meta = { display: "group", pages: [], title: node.label };
+      addMeta(layout, sub, meta);
+      placeNodes(layout, node.children, sub, meta.pages);
+      continue;
+    }
+    const { name } = target;
+    if (layout.placed.has(name) || ctx.index.routes[name] === "/") {
+      const why =
+        ctx.index.routes[name] === "/"
+          ? "is the home page, which stays the root index"
+          : "is already placed";
+      layout.notes.push(
+        `_Sidebar line ${node.line}: ${name} ${why}, so this entry is dropped`
+      );
+      continue;
+    }
+    const base = fileBase(ctx.index, name);
+    const label = labelFor(name, node.label);
+    if (node.children.length === 0) {
+      layout.placed.set(name, { dir, file: base, label });
+      pages.push(base);
+      continue;
+    }
+    const folder = posix.join(dir, uniqueName(layout.folders.get(dir), base));
+    layout.placed.set(name, { dir: folder, file: "index", label });
+    pages.push(posix.basename(folder));
+    const meta = { display: "group", pages: [], title: titleOf(name) };
+    addMeta(layout, folder, meta);
+    placeNodes(layout, node.children, folder, meta.pages);
+  }
+};
+
+const placeGroup = (layout, group, rootPages) => {
+  const { ctx } = layout;
+  if (group.head === null) {
+    placeNodes(layout, group.children, "", rootPages);
+    return;
+  }
+  const head = sidebarTarget(ctx, { ...group.head, line: group.line });
+  const label = group.head.label ?? group.head.text;
+  if (head.kind === "external") {
+    layout.featured.push({ href: head.href, label });
+    layout.notes.push(
+      `_Sidebar line ${group.line}: heading link "${label}" → navigation.featured`
+    );
+  }
+  if (head.kind === "skip") {
+    layout.notes.push(
+      `_Sidebar line ${group.line}: the heading's link was dropped, ${head.why}`
+    );
+  }
+  if (group.children.length === 0) {
+    return;
+  }
+  if (head.kind === "page" && !layout.placed.has(head.name)) {
+    const dir = uniqueName(
+      layout.folders.get(""),
+      fileBase(ctx.index, head.name)
+    );
+    layout.placed.set(head.name, {
+      dir,
+      file: "index",
+      label: labelFor(head.name, label),
+    });
+    rootPages.push(dir);
+    const meta = { pages: [], title: label };
+    addMeta(layout, dir, meta);
+    placeNodes(layout, group.children, dir, meta.pages);
+    return;
+  }
+  const dir = uniqueName(
+    layout.folders.get(""),
+    `(${slugOf(label) || "group"})`
+  );
+  rootPages.push(dir.slice(1, -1));
+  const meta = { pages: [], title: label };
+  addMeta(layout, dir, meta);
+  placeNodes(layout, group.children, dir, meta.pages);
+};
+
+/** Where every kept page goes, and the meta.ts files that order them. */
+const layoutPages = (ctx, sidebar) => {
+  const layout = createLayout(ctx);
+  const contentPages = [...ctx.index.kinds]
+    .filter(
+      ([name, kind]) =>
+        kind === "content" &&
+        ctx.index.routes[name] !== "/" &&
+        MARKDOWN.test(ctx.files[name])
+    )
+    .map(([name]) => name);
+  if (sidebar === null) {
+    for (const name of contentPages) {
+      layout.placed.set(name, {
+        dir: "",
+        file: fileBase(ctx.index, name),
+        label: null,
+      });
+    }
+    return layout;
+  }
+  const rootPages = [];
+  layout.notes.push(...sidebar.notes);
+  for (const group of sidebar.groups) {
+    placeGroup(layout, group, rootPages);
+  }
+  const unlisted = contentPages
+    .filter((name) => !layout.placed.has(name))
+    .toSorted((left, right) =>
+      compareText(titleOf(left).toLowerCase(), titleOf(right).toLowerCase())
+    );
+  if (unlisted.length > 0) {
+    const dir = uniqueName(layout.folders.get(""), "(more)");
+    rootPages.push(dir.slice(1, -1));
+    addMeta(layout, dir, {
+      collapsed: true,
+      display: "group",
+      pages: unlisted.map((name) => fileBase(ctx.index, name)),
+      title: "More pages",
+    });
+    for (const name of unlisted) {
+      layout.placed.set(name, {
+        dir,
+        file: fileBase(ctx.index, name),
+        label: null,
+      });
+    }
+  }
+  layout.metas.set("", { pages: rootPages });
+  return layout;
+};
+
+const metaSource = (meta) => {
+  const lines = [
+    'import { defineMeta } from "blume";',
+    "",
+    "export default defineMeta({",
+  ];
+  for (const key of ["title", "display", "collapsed", "pages"]) {
+    if (meta[key] !== undefined) {
+      const value = Array.isArray(meta[key])
+        ? `[\n${meta[key].map((item) => `    ${JSON.stringify(item)},`).join("\n")}\n  ]`
+        : JSON.stringify(meta[key]);
+      lines.push(`  ${key}: ${value},`);
+    }
+  }
+  lines.push("});", "");
+  return lines.join("\n");
+};
+
+// --- convert ---------------------------------------------------------------------------
+
+const readTables = (root) => {
+  const routesFile = path.join(root, ROUTES_FILE);
+  const filesFile = path.join(root, FILES_FILE);
+  if (!existsSync(routesFile) || !existsSync(filesFile)) {
+    throw new Error(
+      `no ${ROUTES_FILE}/${FILES_FILE} here: run \`routes --write\` first`
+    );
+  }
+  const routes = readJson(routesFile);
+  const files = readJson(filesFile);
+  for (const [name, value] of Object.entries(routes)) {
+    if (value !== null && !/^(?:\/|https?:\/\/)/u.test(String(value))) {
+      throw new Error(
+        `${ROUTES_FILE}: "${name}" must map to a route, a URL, or null`
+      );
+    }
+    if (!(name in files)) {
+      throw new Error(`${FILES_FILE} has no file for "${name}"`);
+    }
+  }
+  return { files, routes };
+};
+
+const findChrome = (files, pattern) =>
+  files
+    .filter((file) => !file.includes("/") && pattern.test(file))
+    .toSorted(
+      (left, right) =>
+        Number(MARKDOWN.test(right)) - Number(MARKDOWN.test(left))
+    )[0] ?? null;
+
+const planPage = (ctx, layout, name, source) => {
+  const place = layout.placed.get(name) ?? {
+    dir: "",
+    file: "index",
+    label: null,
+  };
+  const page = createPage(source, name);
+  const draft = posix.join(ctx.content, place.dir, `${place.file}.md`);
+  const pageCtx = {
+    ...ctx,
+    dest: draft,
+    done: new Set(),
+    html: false,
+    line: 0,
+    name,
+    page,
+  };
+  const { body, needsMdx } = convertBody(
+    pageCtx,
+    readFileSync(path.join(ctx.root, source), "utf-8")
+  );
+  const dest = needsMdx ? draft.replace(/\.md$/u, ".mdx") : draft;
+  const route = ctx.index.routes[name];
+  const slug =
+    derivedRoute(posix.relative(ctx.content, dest)) === route
+      ? null
+      : route.slice(1);
+  if (slug) {
+    edit(page, "slug pinned");
+  }
+  if (needsMdx) {
+    edit(page, "renamed to .mdx");
+  }
+  const head = frontmatter({ label: place.label, slug, title: titleOf(name) });
+  return { dest, page, text: `${head}\n\n${body}\n` };
+};
+
+const leftBehind = (ctx, files, pages, moved) => {
+  const kept = new Set(moved);
+  const lines = [];
+  for (const [name, kind] of ctx.index.kinds) {
+    const file = ctx.files[name];
+    if (kind !== "content" && existsSync(path.join(ctx.root, file))) {
+      lines.push(`${file} (${kind === "moved" ? "moved notice" : "left out"})`);
+    }
+  }
+  const served = new Set(Object.values(ctx.files));
+  for (const file of pages) {
+    if (!served.has(file)) {
+      lines.push(`${file} (never served: another file has its name)`);
+    }
+  }
+  const assets = files.filter(
+    (file) =>
+      !MARKUP.test(file) &&
+      !CHROME.test(posix.basename(file)) &&
+      !PROJECT_FILES.has(file) &&
+      !kept.has(file)
+  );
+  return { assets, pages: lines.toSorted(compareText) };
+};
+
+const siteNotes = (root, files, sidebarFile, layout) => {
+  const notes = [...layout.notes];
+  if (sidebarFile && !MARKDOWN.test(sidebarFile)) {
+    notes.push(`${sidebarFile} isn't Markdown: rebuild the groups by hand`);
+  }
+  for (const file of files) {
+    if (file.includes("/") && CHROME.test(posix.basename(file))) {
+      notes.push(
+        `${file} replaced the sidebar or footer for its folder: map that folder by hand (i18n or a tab)`
+      );
+    }
+  }
+  const footer = findChrome(files, FOOTER);
+  if (footer) {
+    const text = readFileSync(path.join(root, footer), "utf-8")
+      .trim()
+      .split("\n")
+      .slice(0, MAX_NOTICE_LINES);
+    notes.push(
+      `${footer}: ${text.join(" / ")} (links → footer.links; a "contribute to this wiki" footer drops with its link)`
+    );
+  }
+  return notes;
+};
+
+const planAll = (ctx, layout) => {
+  const results = [];
+  const unconverted = [];
+  let already = 0;
+  for (const [name, kind] of ctx.index.kinds) {
+    const source = ctx.files[name];
+    if (kind === "content" && !MARKDOWN.test(source)) {
+      unconverted.push(source);
+    } else if (kind === "content" && existsSync(path.join(ctx.root, source))) {
+      results.push(planPage(ctx, layout, name, source));
+    } else if (kind === "content") {
+      already += 1;
+    }
+  }
+  return { already, results, unconverted };
+};
+
+const writeConversion = (ctx, results, metas) => {
+  const { content, root } = ctx;
+  for (const result of results) {
+    const destination = path.join(root, result.dest);
+    mkdirSync(path.dirname(destination), { recursive: true });
+    writeFileSync(destination, result.text);
+    if (result.dest !== result.page.file) {
+      rmSync(path.join(root, result.page.file));
+    }
+  }
+  for (const image of [...ctx.images].toSorted(compareText)) {
+    const from = path.join(root, image);
+    if (existsSync(from)) {
+      mkdirSync(path.join(root, content, path.dirname(image)), {
+        recursive: true,
+      });
+      renameSync(from, path.join(root, content, image));
+    }
+  }
+  for (const [dir, meta] of metas) {
+    const file = path.join(root, content, dir, "meta.ts");
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, metaSource(meta));
+  }
+};
+
+const convert = (root, options) => {
+  const repo = options.get("repo") ?? "";
+  if (!REPO.test(repo)) {
+    throw new Error("convert needs --repo <owner/repo>");
+  }
+  const content = options.get("content") || "docs";
+  const tables = readTables(root);
+  const { files, pages } = listPages(root, content);
+  const ctx = {
+    content,
+    emoji: loadEmoji(options.get("emoji")),
+    // Files only: after a first run, `docs/<route>/` folders exist, and on a
+    // case-insensitive disk `docs/Some-Page` would otherwise name one.
+    fileExists: (file) =>
+      isFile(path.join(root, file)) || isFile(path.join(root, content, file)),
+    files: tables.files,
+    images: new Set(),
+    index: classify(tables.routes),
+    root,
+    urls: repoUrls(repo, options.get("mirror")),
+  };
+  const sidebarFile = findChrome(files, SIDEBAR);
+  const harvested =
+    sidebarFile === null && existsSync(path.join(root, content, "meta.ts"));
+  const sidebar =
+    sidebarFile && MARKDOWN.test(sidebarFile)
+      ? parseSidebar(readFileSync(path.join(root, sidebarFile), "utf-8"))
+      : null;
+  const layout = layoutPages(ctx, sidebar);
+  const planned = planAll(ctx, layout);
+  const metas = sidebar === null || harvested ? [] : [...layout.metas];
+  if (options.has("write")) {
+    writeConversion(ctx, planned.results, metas);
+  }
+  return {
+    ...planned,
+    featured: layout.featured,
+    images: [...ctx.images].toSorted(compareText),
+    left: leftBehind(ctx, files, pages, ctx.images),
+    metas: metas.map(([dir]) => posix.join(content, dir, "meta.ts")),
+    notes: siteNotes(root, files, sidebarFile, layout),
+  };
+};
+
+// --- routes ----------------------------------------------------------------------------
+
+const noticeTarget = (root, file, urls, routes) => {
+  const text = readFileSync(path.join(root, file), "utf-8");
+  const lines = text.split("\n").filter((line) => line.trim() !== "");
+  if (lines.length > MAX_NOTICE_LINES || !MOVED_NOTICE.test(text)) {
+    return null;
+  }
+  const url = FIRST_URL.exec(text)?.[0] ?? null;
+  const wiki = url && urls ? urls.wiki.exec(url) : null;
+  if (wiki) {
+    const name = decode((wiki.groups.rest ?? "/Home").slice(1));
+    const own = Object.keys(routes).find((key) => keyOf(key) === keyOf(name));
+    return own ? `${routes[own]}${wiki.groups.hash ?? ""}` : url;
+  }
+  return url;
+};
+
+const looksNotContent = (root, file) => {
+  const folders = file.split("/").slice(0, -1);
+  if (folders.some((folder) => NOT_CONTENT_FOLDERS.has(folder.toLowerCase()))) {
+    return true;
+  }
+  if (!file.includes("/") && NOT_CONTENT.has(pageNameOf(file).toLowerCase())) {
+    return true;
+  }
+  const text = readFileSync(path.join(root, file), "utf-8").trim();
+  return (
+    text.split("\n").length === 1 && text.length < 40 && !text.includes("](")
+  );
+};
+
+const routesCommand = (root, options) => {
+  const content = options.get("content") || "docs";
+  const repo = options.get("repo") ?? "";
+  const urls = REPO.test(repo) ? repoUrls(repo, null) : null;
+  const { pages } = listPages(root, content);
+  const table = buildTable(pages);
+  const moved = [];
+  const notContent = [];
+  for (const [name, file] of Object.entries(table.sources)) {
+    const target = MARKDOWN.test(file)
+      ? noticeTarget(root, file, urls, table.routes)
+      : null;
+    if (target) {
+      moved.push(`"${name}": "${target}"`);
+    } else if (looksNotContent(root, file)) {
+      notContent.push(`"${name}": null  (${file})`);
+    }
+  }
+  const digitLed = Object.entries(table.routes)
+    .filter(([, route]) => ORDERING_PREFIX.test(route.slice(1)))
+    .map(([name, route]) => `${name} → ${route} (convert pins its slug)`);
+  const other = pages.filter((file) => !MARKDOWN.test(file));
+  const routesFile = path.join(root, ROUTES_FILE);
+  const existing = existsSync(routesFile) ? readJson(routesFile) : null;
+  const changes = [];
+  if (existing) {
+    for (const name of Object.keys(table.routes)) {
+      if (!(name in existing)) {
+        changes.push(`not in ${ROUTES_FILE}: ${name} (${table.sources[name]})`);
+      }
+    }
+    for (const name of Object.keys(existing)) {
+      if (!(name in table.routes)) {
+        changes.push(`in ${ROUTES_FILE} but not a page here: ${name}`);
+      }
+    }
+  } else if (options.has("write")) {
+    writeJson(routesFile, table.routes);
+    writeJson(path.join(root, FILES_FILE), table.sources);
+  }
+  return {
+    changes,
+    digitLed,
+    existing: existing !== null,
+    moved,
+    notContent,
+    other,
+    table,
+  };
+};
+
+// --- stubs -------------------------------------------------------------------------------
+
+const stubWriter = (root, write, changes) => (file, text) => {
+  const target = path.join(root, file);
+  if (existsSync(target) && readFileSync(target, "utf-8") === text) {
+    return;
+  }
+  changes.push(file);
+  if (write) {
+    writeFileSync(target, text);
+  }
+};
+
+const removeFile = (root, write, changes, file) => {
+  changes.push(`${file} (removed)`);
+  if (write) {
+    rmSync(path.join(root, file));
+  }
+};
+
+const noticeOnly = (root, tables, all, put, notice) => {
+  const home = Object.keys(tables.routes).find(
+    (name) => keyOf(name) === "home"
+  );
+  const targets = [
+    home ? tables.files[home] : null,
+    findChrome(all, SIDEBAR) ?? "_Sidebar.md",
+  ];
+  for (const file of targets.filter(Boolean)) {
+    const target = path.join(root, file);
+    const text = existsSync(target) ? readFileSync(target, "utf-8") : "";
+    if (!text.startsWith(notice)) {
+      put(file, `${notice}\n\n${text}`);
+    }
+  }
+};
+
+const stubsCommand = (root, options) => {
+  const site = (options.get("site") ?? "").replace(/\/+$/u, "");
+  if (!/^https?:\/\//u.test(site)) {
+    throw new Error("stubs needs --site <the new site's URL>");
+  }
+  if (existsSync(path.join(root, "blume.config.ts"))) {
+    throw new Error(
+      "stubs runs in a fresh clone of the wiki, not in the Blume project: clone the wiki elsewhere and copy the two tables in"
+    );
+  }
+  const tables = readTables(root);
+  const changes = [];
+  const left = [];
+  const write = options.has("write");
+  const put = stubWriter(root, write, changes);
+  const notice = `**The docs have moved to <${site}>.**`;
+  const all = walk(root, new Set());
+  if (options.has("notice-only")) {
+    noticeOnly(root, tables, all, put, notice);
+    return { changes, left };
+  }
+  for (const [name, value] of Object.entries(tables.routes)) {
+    const source = tables.files[name];
+    if (value === null) {
+      left.push(source);
+      continue;
+    }
+    const url = URL_SCHEME.test(value) ? value : `${site}${value}`;
+    const stub = source.replace(/\.[^./]+$/u, ".md");
+    put(stub, `**This page has moved to <${url}>.**\n`);
+    if (stub !== source && existsSync(path.join(root, source))) {
+      removeFile(root, write, changes, source);
+    }
+  }
+  for (const file of all) {
+    if (CHROME.test(posix.basename(file)) && file !== "_Sidebar.md") {
+      removeFile(root, write, changes, file);
+    }
+  }
+  put("_Sidebar.md", `${notice}\n`);
+  return { changes, left };
+};
+
+// --- check ---------------------------------------------------------------------------------
+
+const PAGE_IN_URL =
+  /\/wiki(?:\/(?<page>[^?#]*))?(?:\?[^#]*)?(?:#(?<anchor>.*))?$/u;
+
+const idsOf = (html) =>
+  new Set([...html.matchAll(ID_ATTRIBUTE)].map((match) => match.groups.id));
+
+/** Where the pages are: a server build (`vercel()`, `node()`, …) keeps them in `client/`. */
+const pagesRoot = (dist) => {
+  const client = path.join(dist, "client");
+  return existsSync(client) &&
+    statSync(client).isDirectory() &&
+    !existsSync(path.join(dist, "index.html"))
+    ? client
+    : dist;
+};
+
+const checkRoute = (dist, route) => {
+  const [page, anchor = ""] = route.split("#");
+  const file =
+    page === "/"
+      ? path.join(dist, "index.html")
+      : path.join(dist, decode(page), "index.html");
+  if (!existsSync(file)) {
+    return { status: "missing page" };
+  }
+  if (anchor === "") {
+    return { status: "ok" };
+  }
+  const ids = idsOf(readFileSync(file, "utf-8"));
+  if (ids.has(decode(anchor))) {
+    return { status: "ok" };
+  }
+  const words = decode(anchor)
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean);
+  const suggestions = [...ids]
+    .filter(
+      (id) => words.length > 0 && words.every((word) => id.includes(word))
+    )
+    .slice(0, MAX_ID_SUGGESTIONS);
+  return { status: "missing anchor", suggestions };
+};
+
+const checkCommand = (root, options, urls) => {
+  const dist = pagesRoot(path.join(root, options.get("dist") || "dist"));
+  const { routes } = readTables(root);
+  const index = classify(routes);
+  const lines = [];
+  let problems = 0;
+  const report = (label, route) => {
+    const result = checkRoute(dist, route);
+    if (result.status !== "ok") {
+      problems += 1;
+    }
+    const hint = result.suggestions?.length
+      ? ` (ids like: ${result.suggestions.join(", ")})`
+      : "";
+    lines.push(
+      `${result.status === "ok" ? "ok" : result.status.toUpperCase()}  ${label} → ${route}${hint}`
+    );
+  };
+  if (urls.length === 0) {
+    for (const [name, value] of Object.entries(routes)) {
+      if (value !== null && !URL_SCHEME.test(value)) {
+        report(name, value);
+      }
+    }
+    return { lines, problems };
+  }
+  for (const url of urls) {
+    const match = PAGE_IN_URL.exec(url);
+    const target = `${decode(match?.groups.page || "Home")}${match?.groups.anchor ? `#${match.groups.anchor}` : ""}`;
+    const result = resolvePage(index, target, "Home");
+    if (result.href?.startsWith("/")) {
+      report(url, result.href);
+    } else if (result.kind === "moved") {
+      lines.push(`moved  ${url} → ${result.href}`);
+    } else {
+      problems += 1;
+      lines.push(`${result.kind.toUpperCase()}  ${url}`);
+    }
+  }
+  return { lines, problems };
+};
+
+// --- Reports -----------------------------------------------------------------------------
+
+const printList = (heading, items) => {
+  if (items.length === 0) {
+    return;
+  }
+  process.stdout.write(`\n${heading}\n`);
+  for (const item of items) {
+    process.stdout.write(`  ${item}\n`);
+  }
+};
+
+const printRoutes = (result, write) => {
+  const { table } = result;
+  process.stdout.write(`${Object.keys(table.routes).length} page(s)\n`);
+  printList(
+    "Never served (GitHub served another file with the same name): leave them out",
+    table.shadowed
+  );
+  printList(
+    "Same route: give one of them another route in the table",
+    table.clashes
+  );
+  printList(
+    "Looks like a moved notice: set its entry to the target",
+    result.moved
+  );
+  printList(
+    "Looks like it isn't content (check it): set its entry to null",
+    result.notContent
+  );
+  printList("Starts with digits", result.digitLed);
+  printList(
+    "Not Markdown: convert to Markdown first (pandoc), then rerun",
+    result.other
+  );
+  printList("The table and the pages differ", result.changes);
+  let verdict = `\nWrote ${ROUTES_FILE} and ${FILES_FILE}. Classify the pages, then run convert.\n`;
+  if (result.existing) {
+    verdict = `\n${ROUTES_FILE} exists, so nothing was written.\n`;
+  } else if (!write) {
+    verdict = "\nRe-run with --write to write the table.\n";
+  }
+  process.stdout.write(verdict);
+};
+
+const printConvert = (result, write) => {
+  const totals = new Map();
+  let reviews = 0;
+  for (const { dest, page } of result.results) {
+    process.stdout.write(`\n${page.file} → ${dest}\n`);
+    for (const [kind, count] of Object.entries(page.edits).toSorted()) {
+      process.stdout.write(`  ${count} × ${kind}\n`);
+      totals.set(kind, (totals.get(kind) ?? 0) + count);
+    }
+    for (const { line, message } of page.reviews) {
+      process.stdout.write(`  REVIEW line ${line}: ${message}\n`);
+    }
+    reviews += page.reviews.length;
+  }
+  printList(
+    "Site",
+    result.notes.map((note) => `REVIEW ${note}`)
+  );
+  if (result.featured.length > 0) {
+    process.stdout.write(
+      `\nnavigation.featured for blume.config.ts:\n  ${JSON.stringify(result.featured)}\n`
+    );
+  }
+  printList("meta.ts files", result.metas);
+  printList("Images moved beside the pages", result.images);
+  printList(
+    "Not Markdown: convert to Markdown first (pandoc), then rerun",
+    result.unconverted
+  );
+  printList(
+    "Pages left behind: delete them from the project (the wiki keeps them)",
+    result.left.pages
+  );
+  printList(
+    "Other files left in place: wiki tooling or unreferenced files to delete or keep",
+    result.left.assets
+  );
+  printList(
+    "Totals",
+    [...totals].toSorted().map(([kind, count]) => `${count} × ${kind}`)
+  );
+  const verb = write ? "converted" : "would convert";
+  const hint = write ? "" : " Re-run with --write to apply.";
+  const done =
+    result.already > 0 ? ` ${result.already} already converted.` : "";
+  process.stdout.write(
+    `\n${result.results.length} page(s) ${verb},${done} ${reviews + result.notes.length} item(s) to review.${hint}\n`
+  );
+};
+
+const main = () => {
+  const { options, positional } = parseArgs(process.argv.slice(2));
+  const [command, ...rest] = positional;
+  const root = process.cwd();
+  const write = options.has("write");
+  if (options.has("help") || command === undefined) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  try {
+    if (command === "routes") {
+      printRoutes(routesCommand(root, options), write);
+    } else if (command === "convert") {
+      printConvert(convert(root, options), write);
+    } else if (command === "stubs") {
+      const result = stubsCommand(root, options);
+      printList(write ? "Changed" : "Would change", result.changes);
+      printList(
+        "Left as they are (entries set to null): decide by hand",
+        result.left
+      );
+      process.stdout.write(
+        write
+          ? "\nDone. Nothing was committed or pushed: the stubs reach the wiki only when the user reviews them and pushes, after the new site is live.\n"
+          : "\nRe-run with --write to apply.\n"
+      );
+    } else if (command === "check") {
+      const result = checkCommand(root, options, rest);
+      process.stdout.write(
+        `${result.lines.join("\n")}\n\n${result.problems} problem(s).\n`
+      );
+      process.exitCode = result.problems > 0 ? 1 : 0;
+    } else {
+      process.stdout.write(`${HELP}\n`);
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    process.stderr.write(`github-wiki-codemod: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+};
+
+main();