codealmanac 0.1.5 → 0.1.7

package/dist/register-commands-PZMQNGCH.js

@@ -0,0 +1,2644 @@
+#!/usr/bin/env node
+import {
+  addEntry,
+  ancestorsInFile,
+  descendantsInDb,
+  dropEntry,
+  ensureFreshIndex,
+  ensureGlobalDir,
+  ensureTopic,
+  findTopic,
+  loadTopicsFile,
+  looksLikeDir,
+  normalizePath,
+  openIndex,
+  parseDuration,
+  parseFrontmatter,
+  readRegistry,
+  resolveWikiRoot,
+  runHealth,
+  runIndexer,
+  titleCase,
+  toKebabCase,
+  writeTopicsFile
+} from "./chunk-3C5SY5SE.js";
+import {
+  runDoctor
+} from "./chunk-H6WU6PYH.js";
+import "./chunk-4CODZRHH.js";
+import {
+  runUninstall
+} from "./chunk-A6PUCAVJ.js";
+import {
+  runUpdate
+} from "./chunk-Z6MBJ3D2.js";
+import {
+  collectOption,
+  emit,
+  parsePositiveInt,
+  readStdin
+} from "./chunk-P3LDTCLB.js";
+import "./chunk-QHQ6YH7U.js";
+import {
+  BLUE,
+  BOLD,
+  DIM,
+  RST
+} from "./chunk-FM3VRDK7.js";
+import {
+  assertClaudeAuth,
+  runSetup
+} from "./chunk-2JJTTN7P.js";
+import {
+  runHookInstall,
+  runHookStatus,
+  runHookUninstall
+} from "./chunk-Z4MWLVS2.js";
+import "./chunk-AXFPUHBN.js";
+import {
+  findNearestAlmanacDir,
+  getRepoAlmanacDir
+} from "./chunk-7JUX4ADQ.js";
+
+// src/topics/frontmatter-rewrite.ts
+import { readFile, rename, writeFile } from "fs/promises";
+import yaml from "js-yaml";
+async function rewritePageTopics(filePath, transform) {
+  const raw = await readFile(filePath, "utf8");
+  const { before, after, output, changed } = applyTopicsTransform(
+    raw,
+    transform
+  );
+  if (changed) {
+    const tmp = `${filePath}.tmp`;
+    await writeFile(tmp, output, "utf8");
+    await rename(tmp, filePath);
+  }
+  return { before, after, changed };
+}
+function applyTopicsTransform(raw, transform) {
+  const parsed = splitFrontmatter(raw);
+  if (parsed === null) {
+    const next = dedupeSlugs(transform([]));
+    if (next.length === 0) {
+      return { before: [], after: [], output: raw, changed: false };
+    }
+    const fm = `---
+topics: ${flowList(next)}
+---
+
+`;
+    return {
+      before: [],
+      after: next,
+      output: `${fm}${raw}`,
+      changed: true
+    };
+  }
+  const { opener, fmLines, closer, body, eol } = parsed;
+  const { before, existingRange } = readTopicsFromLines(fmLines);
+  const beforeDeduped = dedupeSlugs(before);
+  const after = dedupeSlugs(transform(beforeDeduped));
+  if (arraysEqual(beforeDeduped, after)) {
+    return { before: beforeDeduped, after, output: raw, changed: false };
+  }
+  let nextFmLines;
+  if (existingRange === null) {
+    if (after.length === 0) {
+      return { before: beforeDeduped, after, output: raw, changed: false };
+    }
+    nextFmLines = [...fmLines, `topics: ${flowList(after)}`];
+  } else {
+    const replacement = after.length === 0 ? null : `topics: ${flowList(after)}`;
+    const preservedTail = replacement === null ? [] : existingRange.preserved;
+    nextFmLines = [
+      ...fmLines.slice(0, existingRange.start),
+      ...replacement === null ? [] : [replacement],
+      ...preservedTail,
+      ...fmLines.slice(existingRange.end)
+    ];
+  }
+  const fmBlock = nextFmLines.length === 0 ? "" : `${nextFmLines.join(eol)}${eol}`;
+  const output = `${opener}${fmBlock}${closer}${body}`;
+  return {
+    before: beforeDeduped,
+    after,
+    output,
+    changed: true
+  };
+}
+function splitFrontmatter(raw) {
+  if (!raw.startsWith("---")) return null;
+  const openerMatch = raw.match(/^---(\r?\n)/);
+  if (openerMatch === null) return null;
+  const opener = `---${openerMatch[1] ?? "\n"}`;
+  const rest = raw.slice(opener.length);
+  let fenceIdx;
+  if (rest.startsWith("---")) {
+    fenceIdx = 0;
+  } else {
+    const m = rest.match(/\r?\n---(\r?\n|$)/);
+    if (m === null || m.index === void 0) return null;
+    const leadingNewlineLen = (m[0] ?? "").startsWith("\r\n") ? 2 : 1;
+    fenceIdx = m.index + leadingNewlineLen;
+  }
+  const fmBlock = rest.slice(0, fenceIdx);
+  const afterDashes = rest.slice(fenceIdx + 3);
+  let closerTail = "";
+  if (afterDashes.startsWith("\r\n")) {
+    closerTail = "\r\n";
+  } else if (afterDashes.startsWith("\n")) {
+    closerTail = "\n";
+  }
+  const closer = `---${closerTail}`;
+  const body = afterDashes.slice(closerTail.length);
+  const fmLines = fmBlock.length === 0 ? [] : fmBlock.replace(/\r?\n$/, "").split(/\r?\n/);
+  const eol = opener.endsWith("\r\n") || /\r\n/.test(fmBlock) ? "\r\n" : "\n";
+  return { opener, fmLines, closer, body, eol };
+}
+function readTopicsFromLines(fmLines) {
+  const keyLineIdx = findTopKey(fmLines, "topics");
+  if (keyLineIdx === -1) {
+    return { before: [], existingRange: null };
+  }
+  const keyLine = fmLines[keyLineIdx] ?? "";
+  const colonIdx = keyLine.indexOf(":");
+  const after = keyLine.slice(colonIdx + 1).trim();
+  const afterNoComment = stripTrailingComment(after);
+  if (afterNoComment.length === 0) {
+    const values2 = [];
+    const preserved = [];
+    let i = keyLineIdx + 1;
+    let endIdx = i;
+    let pendingNonEntries = [];
+    while (i < fmLines.length) {
+      const line = fmLines[i] ?? "";
+      const trimmed = line.trim();
+      if (trimmed.length === 0 || trimmed.startsWith("#")) {
+        pendingNonEntries.push(line);
+        i += 1;
+        continue;
+      }
+      const m = line.match(/^\s*-\s+(.*)$/);
+      if (m === null) break;
+      if (pendingNonEntries.length > 0) {
+        preserved.push(...pendingNonEntries);
+        pendingNonEntries = [];
+      }
+      const raw = stripTrailingComment((m[1] ?? "").trim());
+      const parsed2 = parseScalar(raw);
+      if (parsed2.length > 0) values2.push(parsed2);
+      i += 1;
+      endIdx = i;
+    }
+    return {
+      before: values2,
+      existingRange: { start: keyLineIdx, end: endIdx, preserved }
+    };
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(afterNoComment);
+  } catch {
+    parsed = null;
+  }
+  const values = [];
+  if (Array.isArray(parsed)) {
+    for (const v of parsed) {
+      if (typeof v === "string" && v.trim().length > 0) {
+        values.push(v.trim());
+      }
+    }
+  } else if (typeof parsed === "string" && parsed.trim().length > 0) {
+    values.push(parsed.trim());
+  }
+  return {
+    before: values,
+    existingRange: { start: keyLineIdx, end: keyLineIdx + 1, preserved: [] }
+  };
+}
+function findTopKey(fmLines, key) {
+  const re = new RegExp(`^${escapeRegex(key)}\\s*:`);
+  for (let i = 0; i < fmLines.length; i += 1) {
+    if (re.test(fmLines[i] ?? "")) return i;
+  }
+  return -1;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function stripTrailingComment(s) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === "#" && !inSingle && !inDouble) {
+      return s.slice(0, i).trimEnd();
+    }
+  }
+  return s;
+}
+function parseScalar(s) {
+  if (s.length === 0) return s;
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    return s.slice(1, -1);
+  }
+  if (s.length >= 2 && s[0] === "'" && s[s.length - 1] === "'") {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+function flowList(items) {
+  return `[${items.map((t) => formatScalar(t)).join(", ")}]`;
+}
+function formatScalar(s) {
+  if (/^[a-z0-9][a-z0-9-]*$/.test(s)) return s;
+  return yaml.dump(s, { flowLevel: 0, lineWidth: Number.MAX_SAFE_INTEGER }).trimEnd();
+}
+function dedupeSlugs(list) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const raw of list) {
+    const s = raw.trim();
+    if (s.length === 0) continue;
+    if (seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+// src/topics/paths.ts
+import { join } from "path";
+function topicsYamlPath(repoRoot) {
+  return join(repoRoot, ".almanac", "topics.yaml");
+}
+function indexDbPath(repoRoot) {
+  return join(repoRoot, ".almanac", "index.db");
+}
+
+// src/commands/tag.ts
+async function runTag(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  const topics = options.topics.map((t) => toKebabCase(t)).filter((t) => t.length > 0);
+  if (topics.length === 0) {
+    return {
+      stdout: "",
+      stderr: "almanac: tag requires at least one topic\n",
+      exitCode: 1
+    };
+  }
+  const pages = [];
+  if (options.stdin === true) {
+    if (options.stdinInput === void 0) {
+      return {
+        stdout: "",
+        stderr: "almanac: tag --stdin called without stdin input\n",
+        exitCode: 1
+      };
+    }
+    for (const line of options.stdinInput.split(/\r?\n/)) {
+      const s = line.trim();
+      if (s.length > 0) pages.push(s);
+    }
+  } else if (options.page !== void 0 && options.page.length > 0) {
+    pages.push(options.page);
+  } else {
+    return {
+      stdout: "",
+      stderr: "almanac: tag requires a page slug (or --stdin)\n",
+      exitCode: 1
+    };
+  }
+  await ensureFreshIndex({ repoRoot });
+  const db = openIndex(indexDbPath(repoRoot));
+  const stmt = db.prepare(
+    "SELECT file_path FROM pages WHERE slug = ?"
+  );
+  const resolved = [];
+  const missing = [];
+  try {
+    for (const page of pages) {
+      const row = stmt.get(toKebabCase(page));
+      if (row === void 0) {
+        missing.push(page);
+      } else {
+        resolved.push({ page, filePath: row.file_path });
+      }
+    }
+  } finally {
+    db.close();
+  }
+  if (resolved.length === 0) {
+    const stderr2 = missing.map((p) => `almanac: no such page "${p}"
+`).join("");
+    return {
+      stdout: "",
+      stderr: stderr2,
+      exitCode: 1
+    };
+  }
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  let fileChanged = false;
+  for (const t of topics) {
+    const before = file.topics.length;
+    ensureTopic(file, t);
+    if (file.topics.length > before) fileChanged = true;
+  }
+  if (fileChanged) {
+    await writeTopicsFile(yamlPath, file);
+  }
+  const summary = [];
+  let taggedPages = 0;
+  for (const { page, filePath } of resolved) {
+    const result = await rewritePageTopics(filePath, (current) => {
+      const out = [...current];
+      for (const t of topics) if (!current.includes(t)) out.push(t);
+      return out;
+    });
+    if (result.changed) {
+      taggedPages += 1;
+      const added = result.after.filter((t) => !result.before.includes(t));
+      summary.push(`tagged ${page}: ${added.join(", ")}`);
+    } else {
+      summary.push(
+        `no change ${page} (already tagged with ${topics.join(", ")})`
+      );
+    }
+  }
+  if (taggedPages > 0 || fileChanged) {
+    await runIndexer({ repoRoot });
+  }
+  const stderr = missing.map((p) => `almanac: no such page "${p}"
+`).join("");
+  return {
+    stdout: summary.length > 0 ? `${summary.join("\n")}
+` : "",
+    stderr,
+    exitCode: missing.length > 0 ? 1 : 0
+  };
+}
+async function runUntag(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  const page = toKebabCase(options.page);
+  const topic = toKebabCase(options.topic);
+  if (page.length === 0) {
+    return {
+      stdout: "",
+      stderr: "almanac: untag requires a page slug\n",
+      exitCode: 1
+    };
+  }
+  if (topic.length === 0) {
+    return {
+      stdout: "",
+      stderr: "almanac: untag requires a topic\n",
+      exitCode: 1
+    };
+  }
+  await ensureFreshIndex({ repoRoot });
+  const db = openIndex(indexDbPath(repoRoot));
+  let filePath;
+  try {
+    const row = db.prepare(
+      "SELECT file_path FROM pages WHERE slug = ?"
+    ).get(page);
+    if (row === void 0) {
+      return {
+        stdout: "",
+        stderr: `almanac: no such page "${page}"
+`,
+        exitCode: 1
+      };
+    }
+    filePath = row.file_path;
+  } finally {
+    db.close();
+  }
+  const result = await rewritePageTopics(
+    filePath,
+    (current) => current.filter((t) => t !== topic)
+  );
+  if (result.changed) {
+    await runIndexer({ repoRoot });
+  }
+  return {
+    stdout: result.changed ? `untagged ${page}: ${topic}
+` : `no change ${page} (not tagged with ${topic})
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+
+// src/commands/topics/workspace.ts
+function resolveTopicsRepo(options) {
+  return resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+}
+async function openFreshTopicsWorkspace(repoRoot) {
+  await ensureFreshIndex({ repoRoot });
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const db = openIndex(indexDbPath(repoRoot));
+  return { repoRoot, yamlPath, file, db };
+}
+function closeWorkspace(workspace) {
+  workspace.db.close();
+}
+function topicExists(file, db, slug) {
+  if (findTopic(file, slug) !== null) return true;
+  const row = db.prepare(
+    "SELECT slug FROM topics WHERE slug = ?"
+  ).get(slug);
+  return row !== void 0;
+}
+
+// src/commands/topics/create.ts
+async function runTopicsCreate(options) {
+  const repoRoot = await resolveTopicsRepo(options);
+  const slug = toKebabCase(options.name);
+  if (slug.length === 0) {
+    return {
+      stdout: "",
+      stderr: `almanac: topic name "${options.name}" has no slug-able characters
+`,
+      exitCode: 1
+    };
+  }
+  const title = options.name.trim().length > 0 ? options.name.trim() : titleCase(slug);
+  const workspace = await openFreshTopicsWorkspace(repoRoot);
+  try {
+    const { repoRoot: repoRoot2, yamlPath, file, db } = workspace;
+    const requestedParents = (options.parents ?? []).map((p) => toKebabCase(p)).filter((p) => p.length > 0);
+    for (const p of requestedParents) {
+      if (p === slug) {
+        return {
+          stdout: "",
+          stderr: `almanac: topic cannot be its own parent
+`,
+          exitCode: 1
+        };
+      }
+      if (!topicExists(file, db, p)) {
+        return {
+          stdout: "",
+          stderr: `almanac: parent topic "${p}" does not exist; create it first with \`almanac topics create ${p}\`
+`,
+          exitCode: 1
+        };
+      }
+      if (findTopic(file, p) === null) {
+        ensureTopic(file, p);
+      }
+    }
+    const existing = findTopic(file, slug);
+    if (existing === null) {
+      const entry = {
+        slug,
+        title,
+        description: null,
+        parents: requestedParents
+      };
+      file.topics.push(entry);
+    } else {
+      for (const p of requestedParents) {
+        if (existing.parents.includes(p)) continue;
+        const ancestors = ancestorsInFile(file, p);
+        if (ancestors.has(slug) || p === slug) {
+          return {
+            stdout: "",
+            stderr: `almanac: adding "${p}" as a parent of "${slug}" would create a cycle
+`,
+            exitCode: 1
+          };
+        }
+        existing.parents.push(p);
+      }
+      if (existing.title === titleCase(existing.slug) && title !== titleCase(slug) && title !== existing.title) {
+        existing.title = title;
+      }
+    }
+    await writeTopicsFile(yamlPath, file);
+    await runIndexer({ repoRoot: repoRoot2 });
+    return {
+      stdout: existing === null ? `created topic "${slug}"
+` : `updated topic "${slug}"
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  } finally {
+    closeWorkspace(workspace);
+  }
+}
+
+// src/commands/topics/page-rewrite.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2 } from "path";
+import fg from "fast-glob";
+async function rewriteTopicOnPages(repoRoot, transform) {
+  const pagesDir = join2(repoRoot, ".almanac", "pages");
+  const files = await fg("**/*.md", {
+    cwd: pagesDir,
+    absolute: true,
+    onlyFiles: true
+  });
+  let changed = 0;
+  for (const filePath of files) {
+    const raw = await readFile2(filePath, "utf8");
+    const applied = applyTopicsTransform(raw, transform);
+    if (!applied.changed) continue;
+    await rewritePageTopics(filePath, transform);
+    changed += 1;
+  }
+  return changed;
+}
+
+// src/commands/topics/delete.ts
+async function runTopicsDelete(options) {
+  const repoRoot = await resolveTopicsRepo(options);
+  const slug = toKebabCase(options.slug);
+  if (slug.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  const workspace = await openFreshTopicsWorkspace(repoRoot);
+  let pagesUpdated;
+  try {
+    const { repoRoot: repoRoot2, yamlPath, file, db } = workspace;
+    if (!topicExists(file, db, slug)) {
+      return {
+        stdout: "",
+        stderr: `almanac: no such topic "${slug}"
+`,
+        exitCode: 1
+      };
+    }
+    file.topics = file.topics.filter((t) => t.slug !== slug);
+    for (const t of file.topics) {
+      t.parents = t.parents.filter((p) => p !== slug);
+    }
+    await writeTopicsFile(yamlPath, file);
+    pagesUpdated = await rewriteTopicOnPages(
+      repoRoot2,
+      (topics) => topics.filter((t) => t !== slug)
+    );
+  } finally {
+    closeWorkspace(workspace);
+  }
+  await runIndexer({ repoRoot: workspace.repoRoot });
+  return {
+    stdout: `deleted topic "${slug}" (${pagesUpdated} page${pagesUpdated === 1 ? "" : "s"} untagged)
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+
+// src/commands/topics/describe.ts
+async function runTopicsDescribe(options) {
+  const repoRoot = await resolveTopicsRepo(options);
+  const slug = toKebabCase(options.slug);
+  if (slug.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  const workspace = await openFreshTopicsWorkspace(repoRoot);
+  try {
+    const { yamlPath, file, db } = workspace;
+    if (!topicExists(file, db, slug)) {
+      return {
+        stdout: "",
+        stderr: `almanac: no such topic "${slug}"
+`,
+        exitCode: 1
+      };
+    }
+    const entry = ensureTopic(file, slug);
+    const text = options.description.trim();
+    entry.description = text.length === 0 ? null : text;
+    await writeTopicsFile(yamlPath, file);
+  } finally {
+    closeWorkspace(workspace);
+  }
+  await runIndexer({ repoRoot: workspace.repoRoot });
+  return {
+    stdout: `described ${slug}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+
+// src/commands/topics/link.ts
+async function runTopicsLink(options) {
+  const repoRoot = await resolveTopicsRepo(options);
+  const child = toKebabCase(options.child);
+  const parent = toKebabCase(options.parent);
+  if (child.length === 0 || parent.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  if (child === parent) {
+    return {
+      stdout: "",
+      stderr: `almanac: topic cannot be its own parent
+`,
+      exitCode: 1
+    };
+  }
+  const workspace = await openFreshTopicsWorkspace(repoRoot);
+  try {
+    const { repoRoot: repoRoot2, yamlPath, file, db } = workspace;
+    for (const slug of [child, parent]) {
+      if (!topicExists(file, db, slug)) {
+        return {
+          stdout: "",
+          stderr: `almanac: topic "${slug}" does not exist
+`,
+          exitCode: 1
+        };
+      }
+      if (findTopic(file, slug) === null) {
+        ensureTopic(file, slug);
+      }
+    }
+    const childEntry = findTopic(file, child);
+    if (childEntry === null) {
+      return {
+        stdout: "",
+        stderr: `almanac: topic "${child}" not found
+`,
+        exitCode: 1
+      };
+    }
+    if (childEntry.parents.includes(parent)) {
+      return {
+        stdout: `edge ${child} \u2192 ${parent} already exists
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    const parentAncestors = ancestorsInFile(file, parent);
+    if (parentAncestors.has(child) || parent === child) {
+      return {
+        stdout: "",
+        stderr: `almanac: adding ${parent} as parent of ${child} would create a cycle
+`,
+        exitCode: 1
+      };
+    }
+    childEntry.parents.push(parent);
+    await writeTopicsFile(yamlPath, file);
+    await runIndexer({ repoRoot: repoRoot2 });
+    return {
+      stdout: `linked ${child} \u2192 ${parent}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  } finally {
+    closeWorkspace(workspace);
+  }
+}
+
+// src/commands/topics/list.ts
+async function runTopicsList(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  await ensureFreshIndex({ repoRoot });
+  const db = openIndex(indexDbPath(repoRoot));
+  try {
+    const rows = db.prepare(
+      // page_count excludes archived pages — matches the policy used
+      // by `topics show` (see `pagesDirectlyTagged`) and by every
+      // page-scoped check in `health`. Pick one rule and apply it
+      // everywhere; a topic with "5 pages" in `topics list` and "3
+      // pages" in `topics show` is a trust-eroding inconsistency.
+      `SELECT t.slug, t.title, t.description,
+                (SELECT COUNT(*)
+                   FROM page_topics pt
+                   JOIN pages p ON p.slug = pt.page_slug
+                   WHERE pt.topic_slug = t.slug AND p.archived_at IS NULL
+                ) AS page_count
+         FROM topics t
+         ORDER BY t.slug`
+    ).all();
+    if (options.json === true) {
+      return {
+        stdout: `${JSON.stringify(rows, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    if (rows.length === 0) {
+      return {
+        stdout: "no topics. create one with `almanac topics create <name>` or tag a page.\n",
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    const slugWidth = rows.reduce((w, r) => Math.max(w, r.slug.length), 0);
+    const lines = rows.map((r) => {
+      const slug = r.slug.padEnd(slugWidth);
+      const count = `(${r.page_count} page${r.page_count === 1 ? "" : "s"})`;
+      return `${BLUE}${slug}${RST}  ${DIM}${count}${RST}`;
+    });
+    return { stdout: `${lines.join("\n")}
+`, stderr: "", exitCode: 0 };
+  } finally {
+    db.close();
+  }
+}
+
+// src/commands/topics/rename.ts
+async function runTopicsRename(options) {
+  const repoRoot = await resolveTopicsRepo(options);
+  const oldSlug = toKebabCase(options.oldSlug);
+  const newSlug = toKebabCase(options.newSlug);
+  if (oldSlug.length === 0 || newSlug.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  if (oldSlug === newSlug) {
+    return {
+      stdout: `topic "${oldSlug}" unchanged
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const workspace = await openFreshTopicsWorkspace(repoRoot);
+  let pagesUpdated;
+  try {
+    const { repoRoot: repoRoot2, yamlPath, file, db } = workspace;
+    const oldInYaml = findTopic(file, oldSlug);
+    if (!topicExists(file, db, oldSlug)) {
+      return {
+        stdout: "",
+        stderr: `almanac: no such topic "${oldSlug}"
+`,
+        exitCode: 1
+      };
+    }
+    if (topicExists(file, db, newSlug)) {
+      return {
+        stdout: "",
+        stderr: `almanac: topic "${newSlug}" already exists; delete it first if you intend to merge
+`,
+        exitCode: 1
+      };
+    }
+    if (oldInYaml !== null) {
+      oldInYaml.slug = newSlug;
+      if (oldInYaml.title === titleCase(oldSlug)) {
+        oldInYaml.title = titleCase(newSlug);
+      }
+    }
+    for (const t of file.topics) {
+      t.parents = t.parents.map((p) => p === oldSlug ? newSlug : p);
+    }
+    await writeTopicsFile(yamlPath, file);
+    pagesUpdated = await rewriteTopicOnPages(
+      repoRoot2,
+      (topics) => topics.map((t) => t === oldSlug ? newSlug : t)
+    );
+  } finally {
+    closeWorkspace(workspace);
+  }
+  await runIndexer({ repoRoot: workspace.repoRoot });
+  return {
+    stdout: `renamed ${oldSlug} \u2192 ${newSlug} (${pagesUpdated} page${pagesUpdated === 1 ? "" : "s"} updated)
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+
+// src/commands/topics/read.ts
+function pagesDirectlyTagged(db, slug) {
+  return db.prepare(
+    `SELECT pt.page_slug
+       FROM page_topics pt
+       JOIN pages p ON p.slug = pt.page_slug
+       WHERE pt.topic_slug = ? AND p.archived_at IS NULL
+       ORDER BY pt.page_slug`
+  ).all(slug).map((r) => r.page_slug);
+}
+function pagesForSubtree(db, slug) {
+  const slugs = [slug, ...descendantsInDb(db, slug)];
+  const placeholders = slugs.map(() => "?").join(", ");
+  const rows = db.prepare(
+    `SELECT DISTINCT pt.page_slug
+       FROM page_topics pt
+       JOIN pages p ON p.slug = pt.page_slug
+       WHERE pt.topic_slug IN (${placeholders}) AND p.archived_at IS NULL
+       ORDER BY pt.page_slug`
+  ).all(...slugs);
+  return rows.map((r) => r.page_slug);
+}
+function formatShow(r) {
+  const lines = [];
+  lines.push(`${DIM}slug:${RST}         ${BLUE}${r.slug}${RST}`);
+  lines.push(`${DIM}title:${RST}        ${r.title ?? titleCase(r.slug)}`);
+  lines.push(`${DIM}description:${RST}  ${r.description ?? "\u2014"}`);
+  lines.push(
+    `${DIM}parents:${RST}      ${r.parents.length > 0 ? r.parents.join(", ") : "\u2014"}`
+  );
+  lines.push(
+    `${DIM}children:${RST}     ${r.children.length > 0 ? r.children.join(", ") : "\u2014"}`
+  );
+  const pagesLabel = r.descendants_used === true ? "pages (incl. descendants)" : "pages";
+  lines.push(`${DIM}${pagesLabel}:${RST}`);
+  if (r.pages.length === 0) {
+    lines.push("  \u2014");
+  } else {
+    for (const p of r.pages) lines.push(`  ${BLUE}${p}${RST}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/topics/show.ts
+async function runTopicsShow(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  await ensureFreshIndex({ repoRoot });
+  const slug = toKebabCase(options.slug);
+  if (slug.length === 0) {
+    return {
+      stdout: "",
+      stderr: `almanac: empty topic slug
+`,
+      exitCode: 1
+    };
+  }
+  const db = openIndex(indexDbPath(repoRoot));
+  try {
+    const row = db.prepare("SELECT slug, title, description FROM topics WHERE slug = ?").get(slug);
+    if (row === void 0) {
+      return {
+        stdout: "",
+        stderr: `almanac: no such topic "${slug}"
+`,
+        exitCode: 1
+      };
+    }
+    const parents = db.prepare(
+      "SELECT parent_slug FROM topic_parents WHERE child_slug = ? ORDER BY parent_slug"
+    ).all(slug).map((r) => r.parent_slug);
+    const children = db.prepare(
+      "SELECT child_slug FROM topic_parents WHERE parent_slug = ? ORDER BY child_slug"
+    ).all(slug).map((r) => r.child_slug);
+    const pageSlugs = options.descendants === true ? pagesForSubtree(db, slug) : pagesDirectlyTagged(db, slug);
+    const record = {
+      slug: row.slug,
+      title: row.title,
+      description: row.description,
+      parents,
+      children,
+      pages: pageSlugs,
+      descendants_used: options.descendants === true
+    };
+    if (options.json === true) {
+      return {
+        stdout: `${JSON.stringify(record, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    return { stdout: formatShow(record), stderr: "", exitCode: 0 };
+  } finally {
+    db.close();
+  }
+}
+
+// src/commands/topics/unlink.ts
+async function runTopicsUnlink(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  const child = toKebabCase(options.child);
+  const parent = toKebabCase(options.parent);
+  if (child.length === 0 || parent.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const childEntry = findTopic(file, child);
+  if (childEntry === null || !childEntry.parents.includes(parent)) {
+    return {
+      stdout: `no edge ${child} \u2192 ${parent}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  childEntry.parents = childEntry.parents.filter((p) => p !== parent);
+  await writeTopicsFile(yamlPath, file);
+  await runIndexer({ repoRoot });
+  return {
+    stdout: `unlinked ${child} \u2192 ${parent}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+
+// src/registry/autoregister.ts
+import { existsSync } from "fs";
+import { basename } from "path";
+async function autoRegisterIfNeeded(cwd) {
+  try {
+    const repoRoot = findNearestAlmanacDir(cwd);
+    if (repoRoot === null) return null;
+    if (!existsSync(repoRoot)) return null;
+    const entries = await readRegistry();
+    const existing = entries.find((e) => samePath(e.path, repoRoot));
+    if (existing !== void 0) return existing;
+    const name = toKebabCase(basename(repoRoot));
+    if (name.length === 0) return null;
+    const finalName = resolveNameCollision(entries, name, repoRoot);
+    if (finalName === null) return null;
+    const entry = {
+      name: finalName,
+      description: "",
+      path: repoRoot,
+      registered_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await addEntry(entry);
+    return entry;
+  } catch (err) {
+    if (err instanceof Error && "code" in err && (err.code === "ENOENT" || err.code === "EACCES" || err.code === "EPERM")) {
+      return null;
+    }
+    throw err;
+  }
+}
+function resolveNameCollision(entries, baseName, repoPath) {
+  const owner = entries.find((e) => e.name === baseName);
+  if (owner === void 0 || samePath(owner.path, repoPath)) {
+    return baseName;
+  }
+  const taken = new Set(entries.map((e) => e.name));
+  const MAX_ATTEMPTS = 1e3;
+  for (let suffix = 2; suffix < MAX_ATTEMPTS + 2; suffix += 1) {
+    const candidate = `${baseName}-${suffix}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  return null;
+}
+function samePath(a, b) {
+  if (process.platform === "darwin" || process.platform === "win32") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+
+// src/cli/register-edit-commands.ts
+function registerEditCommands(program) {
+  program.command("tag [page] [topics...]").description("add topics to a page (auto-creates missing topics)").option("--stdin", "read page slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").action(
+    async (page, topicsArg, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const resolvedTopics = opts.stdin === true ? [page, ...topicsArg].filter(
+        (t) => typeof t === "string" && t.length > 0
+      ) : topicsArg;
+      const result = await runTag({
+        cwd: process.cwd(),
+        page: opts.stdin === true ? void 0 : page,
+        topics: resolvedTopics,
+        stdin: opts.stdin,
+        stdinInput: opts.stdin === true ? await readStdin() : void 0,
+        wiki: opts.wiki
+      });
+      emit(result);
+    }
+  );
+  program.command("untag <page> <topic>").description("remove a topic from a page's frontmatter").option("--wiki <name>", "target a specific registered wiki").action(
+    async (page, topic, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runUntag({
+        cwd: process.cwd(),
+        page,
+        topic,
+        wiki: opts.wiki
+      });
+      emit(result);
+    }
+  );
+  const topics = program.command("topics").description("manage the topic DAG");
+  topics.command("list", { isDefault: true }).description("list all topics with page counts").option("--wiki <name>", "target a specific registered wiki").option("--json", "emit structured JSON").action(async (opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runTopicsList({
+      cwd: process.cwd(),
+      wiki: opts.wiki,
+      json: opts.json
+    });
+    emit(result);
+  });
+  topics.command("show <slug>").description("print a topic's metadata, parents, children, and pages").option("--descendants", "include pages tagged with descendant topics").option("--wiki <name>", "target a specific registered wiki").option("--json", "emit structured JSON").action(
+    async (slug, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runTopicsShow({
+        cwd: process.cwd(),
+        slug,
+        descendants: opts.descendants,
+        wiki: opts.wiki,
+        json: opts.json
+      });
+      emit(result);
+    }
+  );
+  topics.command("create <name>").description("create a topic (rejects if --parent slug does not exist)").option("--parent <slug>", "parent topic slug (repeat for multiple parents)", collectOption, []).option("--wiki <name>", "target a specific registered wiki").action(
+    async (name, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runTopicsCreate({
+        cwd: process.cwd(),
+        name,
+        parents: opts.parent,
+        wiki: opts.wiki
+      });
+      emit(result);
+    }
+  );
+  topics.command("link <child> <parent>").description("add a DAG edge (cycle-checked)").option("--wiki <name>", "target a specific registered wiki").action(async (child, parent, opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runTopicsLink({
+      cwd: process.cwd(),
+      child,
+      parent,
+      wiki: opts.wiki
+    });
+    emit(result);
+  });
+  topics.command("unlink <child> <parent>").description("remove a DAG edge").option("--wiki <name>", "target a specific registered wiki").action(async (child, parent, opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runTopicsUnlink({
+      cwd: process.cwd(),
+      child,
+      parent,
+      wiki: opts.wiki
+    });
+    emit(result);
+  });
+  topics.command("rename <old> <new>").description("rename a topic; rewrites every affected page's frontmatter").option("--wiki <name>", "target a specific registered wiki").action(async (oldSlug, newSlug, opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runTopicsRename({
+      cwd: process.cwd(),
+      oldSlug,
+      newSlug,
+      wiki: opts.wiki
+    });
+    emit(result);
+  });
+  topics.command("delete <slug>").description("delete a topic; untags every affected page").option("--wiki <name>", "target a specific registered wiki").action(async (slug, opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runTopicsDelete({
+      cwd: process.cwd(),
+      slug,
+      wiki: opts.wiki
+    });
+    emit(result);
+  });
+  topics.command("describe <slug> <text>").description("set a topic's one-line description").option("--wiki <name>", "target a specific registered wiki").action(async (slug, text, opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runTopicsDescribe({
+      cwd: process.cwd(),
+      slug,
+      description: text,
+      wiki: opts.wiki
+    });
+    emit(result);
+  });
+}
+
+// src/commands/list.ts
+import { existsSync as existsSync2 } from "fs";
+async function listWikis(options) {
+  if (options.drop !== void 0) {
+    return handleDrop(options.drop);
+  }
+  const entries = await readRegistry();
+  const reachable = entries.filter((e) => isReachable(e));
+  if (options.json === true) {
+    return { stdout: `${JSON.stringify(reachable, null, 2)}
+`, exitCode: 0 };
+  }
+  return { stdout: formatPretty(reachable), exitCode: 0 };
+}
+async function handleDrop(name) {
+  const removed = await dropEntry(name);
+  if (removed === null) {
+    return {
+      stdout: `no registry entry named "${name}"
+`,
+      exitCode: 1
+    };
+  }
+  return {
+    stdout: `removed "${removed.name}" (${removed.path})
+`,
+    exitCode: 0
+  };
+}
+function isReachable(entry) {
+  if (entry.path.length === 0) return false;
+  return existsSync2(entry.path);
+}
+function formatPretty(entries) {
+  if (entries.length === 0) {
+    return `${DIM}no wikis registered. run \`almanac bootstrap\` in a repo to create one.${RST}
+`;
+  }
+  const nameWidth = Math.min(
+    30,
+    entries.reduce((w, e) => Math.max(w, e.name.length), 0)
+  );
+  const lines = [];
+  for (const entry of entries) {
+    const name = entry.name.padEnd(nameWidth);
+    const desc = entry.description.length > 0 ? entry.description : "\u2014";
+    lines.push(`${BLUE}${BOLD}${name}${RST}  ${desc}`);
+    lines.push(`${" ".repeat(nameWidth)}  ${DIM}${entry.path}${RST}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/search.ts
+import { join as join3 } from "path";
+async function runSearch(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join3(repoRoot, ".almanac", "index.db");
+  const db = openIndex(dbPath);
+  try {
+    const rows = executeQuery(db, options);
+    const limited = options.limit !== void 0 && options.limit >= 0 ? rows.slice(0, options.limit) : rows;
+    const stdout = formatResults(limited, options);
+    const stderr = buildStderr(limited, options);
+    return { stdout, stderr, exitCode: 0 };
+  } finally {
+    db.close();
+  }
+}
+function executeQuery(db, options) {
+  const whereClauses = [];
+  const params = [];
+  if (options.archived === true) {
+    whereClauses.push("p.archived_at IS NOT NULL");
+  } else if (options.includeArchive !== true) {
+    whereClauses.push("p.archived_at IS NULL");
+  }
+  for (const rawTopic of options.topics) {
+    const topicSlug = slugForTopic(rawTopic);
+    if (topicSlug.length === 0) continue;
+    whereClauses.push(
+      "EXISTS (SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug AND pt.topic_slug = ?)"
+    );
+    params.push(topicSlug);
+  }
+  if (options.mentions !== void 0 && options.mentions.length > 0) {
+    const isDir = looksLikeDir(options.mentions);
+    const norm = normalizePath(options.mentions, isDir);
+    if (isDir) {
+      const escaped = escapeGlobMeta(norm);
+      whereClauses.push(
+        `EXISTS (
+           SELECT 1 FROM file_refs r
+           WHERE r.page_slug = p.slug
+             AND (r.path = ? OR r.path GLOB ?)
+         )`
+      );
+      params.push(norm, `${escaped}*`);
+    } else {
+      const prefixes = parentFolderPrefixes(norm);
+      if (prefixes.length === 0) {
+        whereClauses.push(
+          `EXISTS (
+             SELECT 1 FROM file_refs r
+             WHERE r.page_slug = p.slug AND r.path = ?
+           )`
+        );
+        params.push(norm);
+      } else {
+        const placeholders = prefixes.map(() => "?").join(", ");
+        whereClauses.push(
+          `EXISTS (
+             SELECT 1 FROM file_refs r
+             WHERE r.page_slug = p.slug
+               AND (
+                 r.path = ?
+                 OR (r.is_dir = 1 AND r.path IN (${placeholders}))
+               )
+           )`
+        );
+        params.push(norm, ...prefixes);
+      }
+    }
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (options.since !== void 0) {
+    const seconds = parseDuration(options.since);
+    whereClauses.push("p.updated_at >= ?");
+    params.push(now - seconds);
+  }
+  if (options.stale !== void 0) {
+    const seconds = parseDuration(options.stale);
+    whereClauses.push("p.updated_at < ?");
+    params.push(now - seconds);
+  }
+  if (options.orphan === true) {
+    whereClauses.push(
+      "NOT EXISTS (SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug)"
+    );
+  }
+  let sql;
+  if (options.query !== void 0 && options.query.trim().length > 0) {
+    const ftsExpr = buildFtsQuery(options.query);
+    sql = `
+      SELECT p.slug, p.title, p.updated_at, p.archived_at, p.superseded_by
+      FROM pages p
+      JOIN fts_pages f ON f.slug = p.slug
+      WHERE fts_pages MATCH ?
+        ${whereClauses.length > 0 ? `AND ${whereClauses.join(" AND ")}` : ""}
+      ORDER BY f.rank ASC, p.updated_at DESC, p.slug ASC
+    `;
+    params.unshift(ftsExpr);
+  } else {
+    sql = buildSql(whereClauses);
+  }
+  const rows = db.prepare(sql).all(...params);
+  const topicStmt = db.prepare(
+    "SELECT topic_slug FROM page_topics WHERE page_slug = ? ORDER BY topic_slug"
+  );
+  const out = rows.map((row) => ({
+    slug: row.slug,
+    title: row.title,
+    updated_at: row.updated_at,
+    archived_at: row.archived_at,
+    superseded_by: row.superseded_by,
+    topics: topicStmt.all(row.slug).map((t) => t.topic_slug)
+  }));
+  return out;
+}
+function buildSql(whereClauses) {
+  const where = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+  return `
+    SELECT p.slug, p.title, p.updated_at, p.archived_at, p.superseded_by
+    FROM pages p
+    ${where}
+    ORDER BY p.updated_at DESC, p.slug ASC
+  `;
+}
+function buildFtsQuery(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    const inner = trimmed.slice(1, -1).toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    if (inner.length === 0) return '""';
+    return `"${inner}"`;
+  }
+  const tokens = trimmed.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+  if (tokens.length === 0) return '""';
+  return tokens.map((t) => `${t}*`).join(" AND ");
+}
+function slugForTopic(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function parentFolderPrefixes(filePath) {
+  const out = [];
+  let cursor = 0;
+  while (true) {
+    const next = filePath.indexOf("/", cursor);
+    if (next === -1) break;
+    out.push(filePath.slice(0, next + 1));
+    cursor = next + 1;
+  }
+  return out;
+}
+function escapeGlobMeta(s) {
+  return s.replace(/[\*\?\[]/g, (ch) => `[${ch}]`);
+}
+function formatResults(rows, options) {
+  if (options.json === true) {
+    return `${JSON.stringify(rows, null, 2)}
+`;
+  }
+  if (rows.length === 0) return "";
+  return `${rows.map((r) => `${BLUE}${r.slug}${RST}`).join("\n")}
+`;
+}
+function buildStderr(rows, options) {
+  if (options.json === true) return "";
+  if (rows.length === 0) {
+    return "# 0 results\n";
+  }
+  if (options.limit !== void 0) return "";
+  if (rows.length > 50) {
+    return `almanac: ${rows.length} results \u2014 consider --limit or a narrower query
+`;
+  }
+  return "";
+}
+
+// src/commands/show.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join as join4 } from "path";
+async function runShow(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join4(repoRoot, ".almanac", "index.db");
+  const db = openIndex(dbPath);
+  try {
+    const slugs = collectSlugs(options);
+    if (slugs.length === 0) {
+      return {
+        stdout: "",
+        stderr: "almanac: show requires a slug (or --stdin)\n",
+        exitCode: 1
+      };
+    }
+    const records = [];
+    const missing = [];
+    for (const slug of slugs) {
+      const rec = await fetchRecord(db, slug);
+      if (rec === null) {
+        missing.push(slug);
+        continue;
+      }
+      records.push(rec);
+    }
+    const bulk = options.stdin === true;
+    const stdout = bulk ? formatBulk(records) : formatSingle(records, options);
+    const stderr = missing.map((s) => `almanac: no such page "${s}"
+`).join("");
+    return {
+      stdout,
+      stderr,
+      exitCode: missing.length > 0 ? 1 : 0
+    };
+  } finally {
+    db.close();
+  }
+}
+async function fetchRecord(db, slug) {
+  const pageRow = db.prepare(
+    "SELECT slug, title, file_path, updated_at, archived_at, superseded_by FROM pages WHERE slug = ?"
+  ).get(slug);
+  if (pageRow === void 0) return null;
+  const topics = db.prepare(
+    "SELECT topic_slug FROM page_topics WHERE page_slug = ? ORDER BY topic_slug"
+  ).all(slug).map((r) => r.topic_slug);
+  const refs = db.prepare(
+    "SELECT original_path, is_dir FROM file_refs WHERE page_slug = ? ORDER BY original_path"
+  ).all(slug).map((r) => ({ path: r.original_path, is_dir: r.is_dir === 1 }));
+  const linksOut = db.prepare(
+    "SELECT target_slug FROM wikilinks WHERE source_slug = ? ORDER BY target_slug"
+  ).all(slug).map((r) => r.target_slug);
+  const linksIn = db.prepare(
+    "SELECT source_slug FROM wikilinks WHERE target_slug = ? ORDER BY source_slug"
+  ).all(slug).map((r) => r.source_slug);
+  const xwiki = db.prepare(
+    "SELECT target_wiki, target_slug FROM cross_wiki_links WHERE source_slug = ? ORDER BY target_wiki, target_slug"
+  ).all(slug).map((r) => ({ wiki: r.target_wiki, target: r.target_slug }));
+  const supersedesRows = db.prepare(
+    "SELECT slug FROM pages WHERE superseded_by = ? ORDER BY slug"
+  ).all(slug).map((r) => r.slug);
+  let body = "";
+  try {
+    body = stripFrontmatter(await readFile3(pageRow.file_path, "utf8"));
+  } catch {
+  }
+  return {
+    slug: pageRow.slug,
+    title: pageRow.title,
+    file_path: pageRow.file_path,
+    updated_at: pageRow.updated_at,
+    archived_at: pageRow.archived_at,
+    superseded_by: pageRow.superseded_by,
+    supersedes: supersedesRows,
+    topics,
+    file_refs: refs,
+    wikilinks_out: linksOut,
+    wikilinks_in: linksIn,
+    cross_wiki_links: xwiki,
+    body
+  };
+}
+function formatBulk(records) {
+  if (records.length === 0) return "";
+  return records.map((r) => JSON.stringify(r)).join("\n") + "\n";
+}
+function formatSingle(records, options) {
+  if (options.json === true) {
+    const only = records[0] ?? null;
+    return `${JSON.stringify(only, null, 2)}
+`;
+  }
+  return records.map((r) => formatRecord(r, options)).join("");
+}
+var FIELD_ORDER = [
+  "title",
+  "topics",
+  "files",
+  "links",
+  "backlinks",
+  "xwiki",
+  "lineage",
+  "updated",
+  "path"
+];
+function selectedFields(options) {
+  const selected = [];
+  for (const f of FIELD_ORDER) {
+    if (options[f] === true) selected.push(f);
+  }
+  return selected;
+}
+function formatRecord(rec, options) {
+  if (options.raw === true) {
+    if (rec.body.length === 0) return "";
+    return rec.body.endsWith("\n") ? rec.body : `${rec.body}
+`;
+  }
+  const fields = selectedFields(options);
+  if (fields.length > 0) {
+    if (fields.length === 1) {
+      return bareField(rec, fields[0]);
+    }
+    return labeledFields(rec, fields);
+  }
+  if (options.meta === true) {
+    return metadataHeader(rec) + "\n";
+  }
+  if (options.lead === true) {
+    return firstParagraph(rec.body) + "\n";
+  }
+  const header = metadataHeader(rec);
+  const body = rec.body;
+  const sep = body.length > 0 ? `
+
+${DIM}---${RST}
+
+` : "\n";
+  return header + sep + body;
+}
+function bareField(rec, field) {
+  switch (field) {
+    case "title":
+      return (rec.title ?? "") + "\n";
+    case "topics":
+      return rec.topics.map((t) => `${t}
+`).join("");
+    case "files":
+      return rec.file_refs.map((r) => `${r.path}
+`).join("");
+    case "links":
+      return rec.wikilinks_out.map((t) => `${t}
+`).join("");
+    case "backlinks":
+      return rec.wikilinks_in.map((t) => `${t}
+`).join("");
+    case "xwiki":
+      return rec.cross_wiki_links.map((x) => `${x.wiki}:${x.target}
+`).join("");
+    case "lineage": {
+      const lines = [];
+      if (rec.archived_at !== null) {
+        lines.push(
+          `archived_at: ${new Date(rec.archived_at * 1e3).toISOString()}`
+        );
+      }
+      if (rec.superseded_by !== null) {
+        lines.push(`superseded_by: ${rec.superseded_by}`);
+      }
+      if (rec.supersedes.length > 0) {
+        lines.push(`supersedes: ${rec.supersedes.join(", ")}`);
+      }
+      return lines.length > 0 ? `${lines.join("\n")}
+` : "";
+    }
+    case "updated":
+      return `${new Date(rec.updated_at * 1e3).toISOString()}
+`;
+    case "path":
+      return `${rec.file_path}
+`;
+  }
+}
+function labeledFields(rec, fields) {
+  const parts = [];
+  for (const f of fields) {
+    parts.push(labeledSection(rec, f));
+  }
+  return parts.join("\n");
+}
+function labeledSection(rec, field) {
+  switch (field) {
+    case "title":
+      return `${DIM}title:${RST} ${rec.title ?? "\u2014"}
+`;
+    case "topics":
+      return rec.topics.length > 0 ? `${DIM}topics:${RST} ${rec.topics.join(", ")}
+` : `${DIM}topics:${RST} \u2014
+`;
+    case "files":
+      return formatListSection(
+        "files",
+        rec.file_refs.map((r) => `${r.path}`)
+      );
+    case "links":
+      return formatListSection("links", rec.wikilinks_out);
+    case "backlinks":
+      return formatListSection("backlinks", rec.wikilinks_in);
+    case "xwiki":
+      return formatListSection(
+        "xwiki",
+        rec.cross_wiki_links.map((x) => `${x.wiki}:${x.target}`)
+      );
+    case "lineage": {
+      const lines = [`${DIM}lineage:${RST}`];
+      if (rec.archived_at !== null) {
+        lines.push(
+          `  ${DIM}archived_at:${RST} ${new Date(rec.archived_at * 1e3).toISOString()}`
+        );
+      }
+      if (rec.superseded_by !== null) {
+        lines.push(`  ${DIM}superseded_by:${RST} ${rec.superseded_by}`);
+      }
+      if (rec.supersedes.length > 0) {
+        lines.push(`  ${DIM}supersedes:${RST} ${rec.supersedes.join(", ")}`);
+      }
+      if (lines.length === 1) lines.push("  \u2014");
+      return lines.join("\n") + "\n";
+    }
+    case "updated":
+      return `${DIM}updated:${RST} ${new Date(rec.updated_at * 1e3).toISOString()}
+`;
+    case "path":
+      return `${DIM}path:${RST} ${rec.file_path}
+`;
+  }
+}
+function formatListSection(label, items) {
+  if (items.length === 0) return `${DIM}${label}:${RST} \u2014
+`;
+  if (items.length <= 3) return `${DIM}${label}:${RST} ${items.join(", ")}
+`;
+  return `${DIM}${label}:${RST}
+${items.map((i) => `  ${i}`).join("\n")}
+`;
+}
+function metadataHeader(rec) {
+  const lines = [];
+  lines.push(`${DIM}slug:${RST}       ${BLUE}${rec.slug}${RST}`);
+  lines.push(`${DIM}title:${RST}      ${rec.title ?? "\u2014"}`);
+  lines.push(
+    `${DIM}topics:${RST}     ${rec.topics.length > 0 ? rec.topics.join(", ") : "\u2014"}`
+  );
+  if (rec.file_refs.length > 0) {
+    const parts = rec.file_refs.map(
+      (r) => `${r.path}`
+    );
+    lines.push(`${DIM}files:${RST}      ${parts.join(", ")}`);
+  }
+  lines.push(
+    `${DIM}updated:${RST}    ${new Date(rec.updated_at * 1e3).toISOString()}`
+  );
+  if (rec.wikilinks_out.length > 0) {
+    lines.push(`${DIM}links:${RST}      ${rec.wikilinks_out.join(", ")}`);
+  }
+  if (rec.wikilinks_in.length > 0) {
+    lines.push(`${DIM}backlinks:${RST}  ${rec.wikilinks_in.join(", ")}`);
+  }
+  if (rec.cross_wiki_links.length > 0) {
+    lines.push(
+      `${DIM}xwiki:${RST}      ${rec.cross_wiki_links.map((x) => `${x.wiki}:${x.target}`).join(", ")}`
+    );
+  }
+  if (rec.archived_at !== null) {
+    lines.push(
+      `${DIM}archived:${RST}   ${new Date(rec.archived_at * 1e3).toISOString()}`
+    );
+  }
+  if (rec.superseded_by !== null) {
+    lines.push(`${DIM}superseded_by:${RST} ${rec.superseded_by}`);
+  }
+  if (rec.supersedes.length > 0) {
+    lines.push(`${DIM}supersedes:${RST} ${rec.supersedes.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function stripFrontmatter(src) {
+  if (!src.startsWith("---\n") && !src.startsWith("---\r\n")) return src;
+  const afterOpen = src.replace(/^---\r?\n/, "");
+  const endMatch = afterOpen.match(/^---[ \t]*\r?\n/m);
+  if (endMatch === null || endMatch.index === void 0) return src;
+  return afterOpen.slice(endMatch.index + endMatch[0].length);
+}
+function firstParagraph(body) {
+  let src = body.trimStart();
+  if (src.startsWith("# ")) {
+    const nl = src.indexOf("\n");
+    src = nl === -1 ? "" : src.slice(nl + 1).trimStart();
+  }
+  const blank = src.search(/\n[ \t]*\n/);
+  if (blank === -1) return src.trimEnd();
+  return src.slice(0, blank).trimEnd();
+}
+function collectSlugs(options) {
+  if (options.stdin === true && options.stdinInput !== void 0) {
+    return options.stdinInput.split(/\r?\n/).map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  if (options.slug !== void 0 && options.slug.length > 0) {
+    return [options.slug];
+  }
+  return [];
+}
+
+// src/cli/register-query-commands.ts
+function registerQueryCommands(program) {
+  program.command("search [query]").description("find pages by text, topic, file mentions, freshness").option(
+    "--topic <name...>",
+    "filter by topic (repeat for intersection)",
+    collectOption,
+    []
+  ).option(
+    "--mentions <path>",
+    "pages referencing this path; matches exact file, trailing-slash folders, and any file under a folder prefix"
+  ).option("--since <duration>", "updated within duration, by file mtime (e.g. 2w, 30d)").option("--stale <duration>", "NOT updated within duration, by file mtime").option("--orphan", "pages with no topics").option("--include-archive", "include archived pages").option("--archived", "archived pages only").option("--wiki <name>", "target a specific registered wiki").option("--json", "emit structured JSON").option("--limit <n>", "cap results", parsePositiveInt).action(
+    async (query2, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runSearch({
+        cwd: process.cwd(),
+        query: query2,
+        topics: opts.topic ?? [],
+        mentions: opts.mentions,
+        since: opts.since,
+        stale: opts.stale,
+        orphan: opts.orphan,
+        includeArchive: opts.includeArchive,
+        archived: opts.archived,
+        wiki: opts.wiki,
+        json: opts.json,
+        limit: opts.limit
+      });
+      emit(result);
+    }
+  );
+  program.command("show [slug]").description("print a page (metadata + body; flags to narrow)").option("--stdin", "read slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").option("--json", "structured JSON (overrides other view/field flags)").option("--raw", "body only (alias: --body)").option("--body", "body only (alias: --raw)").option("--meta", "metadata only, no body").option("--lead", "first paragraph of the body only").option("--title", "print title").option("--topics", "print topics").option("--files", "print file refs").option("--links", "print outgoing wikilinks").option("--backlinks", "print incoming wikilinks").option("--xwiki", "print cross-wiki links").option("--lineage", "print archived_at / supersedes / superseded_by").option("--updated", "print updated timestamp").option("--path", "print absolute file path").action(
+    async (slug, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runShow({
+        cwd: process.cwd(),
+        slug,
+        stdin: opts.stdin,
+        stdinInput: opts.stdin === true ? await readStdin() : void 0,
+        wiki: opts.wiki,
+        json: opts.json,
+        raw: opts.raw === true || opts.body === true,
+        meta: opts.meta,
+        lead: opts.lead,
+        title: opts.title,
+        topics: opts.topics,
+        files: opts.files,
+        links: opts.links,
+        backlinks: opts.backlinks,
+        xwiki: opts.xwiki,
+        lineage: opts.lineage,
+        updated: opts.updated,
+        path: opts.path
+      });
+      emit(result);
+    }
+  );
+  program.command("health").description("report graph integrity problems").option("--topic <name>", "scope to a topic + its descendants").option("--stale <duration>", "stale threshold (default 90d)").option("--stdin", "read page slugs from stdin (limit to these pages)").option("--json", "emit structured JSON").option("--wiki <name>", "target a specific registered wiki").action(
+    async (opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runHealth({
+        cwd: process.cwd(),
+        topic: opts.topic,
+        stale: opts.stale,
+        stdin: opts.stdin,
+        stdinInput: opts.stdin === true ? await readStdin() : void 0,
+        json: opts.json,
+        wiki: opts.wiki
+      });
+      emit(result);
+    }
+  );
+  program.command("list").description("list registered wikis").option("--json", "emit structured JSON").option(
+    "--drop <name>",
+    "remove a wiki from the registry (the only way entries are ever removed)"
+  ).action(async (opts) => {
+    if (opts.drop === void 0) {
+      await autoRegisterIfNeeded(process.cwd());
+    }
+    const result = await listWikis(opts);
+    process.stdout.write(result.stdout);
+    if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode;
+    }
+  });
+}
+
+// src/cli/register-setup-commands.ts
+function registerSetupCommands(program) {
+  program.command("setup").description("install the hook + CLAUDE.md guides (bare codealmanac alias)").option("-y, --yes", "skip prompts; install everything").option("--skip-hook", "opt out of the SessionEnd hook").option("--skip-guides", "opt out of the CLAUDE.md guides").action(
+    async (opts) => {
+      const result = await runSetup({
+        yes: opts.yes,
+        skipHook: opts.skipHook,
+        skipGuides: opts.skipGuides
+      });
+      emit(result);
+    }
+  );
+  program.command("doctor").description("report on the codealmanac install + current wiki health").option("--json", "emit structured JSON").option("--install-only", "report only on the install (skip wiki checks)").option("--wiki-only", "report only on the current wiki (skip install checks)").action(
+    async (opts) => {
+      const result = await runDoctor({
+        cwd: process.cwd(),
+        json: opts.json,
+        installOnly: opts.installOnly,
+        wikiOnly: opts.wikiOnly
+      });
+      emit(result);
+    }
+  );
+  program.command("update").description("install the latest codealmanac (synchronous foreground `npm i -g`)").option(
+    "--dismiss",
+    "silence the update banner for the current `latest_version` without installing"
+  ).option("--check", "force a registry check now (bypasses the 24h cache); no install").option(
+    "--enable-notifier",
+    "re-enable the pre-command update banner (writes ~/.almanac/config.json)"
+  ).option(
+    "--disable-notifier",
+    "silence the pre-command update banner (writes ~/.almanac/config.json)"
+  ).action(
+    async (opts) => {
+      const result = await runUpdate({
+        dismiss: opts.dismiss,
+        check: opts.check,
+        enableNotifier: opts.enableNotifier,
+        disableNotifier: opts.disableNotifier
+      });
+      emit(result);
+    }
+  );
+  program.command("uninstall").description("remove the hook + guides + import line").option("-y, --yes", "skip confirmations; remove everything").option("--keep-hook", "don't remove the SessionEnd hook (guides still prompted unless --yes)").option(
+    "--keep-guides",
+    "don't remove the guides or CLAUDE.md import (hook still prompted unless --yes)"
+  ).action(
+    async (opts) => {
+      const result = await runUninstall({
+        yes: opts.yes,
+        keepHook: opts.keepHook,
+        keepGuides: opts.keepGuides
+      });
+      emit(result);
+    }
+  );
+}
+
+// src/commands/bootstrap.ts
+import { createWriteStream, existsSync as existsSync5 } from "fs";
+import { readdir } from "fs/promises";
+import { join as join6, relative } from "path";
+
+// src/agent/prompts.ts
+import { existsSync as existsSync3 } from "fs";
+import { readFile as readFile4 } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+var PROMPT_NAMES = [
+  "bootstrap",
+  "writer",
+  "reviewer"
+];
+var overrideDir = null;
+var resolvedDir = null;
+function resolvePromptsDir() {
+  if (overrideDir !== null) return overrideDir;
+  if (resolvedDir !== null) return resolvedDir;
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    // Bundled dist layout: `.../<pkg>/dist/codealmanac.js` → `../prompts`
+    path.resolve(here, "..", "prompts"),
+    // Source layout: `.../<pkg>/src/agent/prompts.ts` → `../../prompts`
+    path.resolve(here, "..", "..", "prompts"),
+    // Defensive fallback: if tsup someday emits a nested `dist/src/agent`,
+    // walk up three levels.
+    path.resolve(here, "..", "..", "..", "prompts")
+  ];
+  for (const dir of candidates) {
+    if (isPromptsDir(dir)) {
+      resolvedDir = dir;
+      return dir;
+    }
+  }
+  throw new Error(
+    "could not locate bundled prompts/ directory. Tried:\n" + candidates.map((c) => `  - ${c}`).join("\n")
+  );
+}
+function isPromptsDir(dir) {
+  if (!existsSync3(dir)) return false;
+  return PROMPT_NAMES.every(
+    (name) => existsSync3(path.join(dir, `${name}.md`))
+  );
+}
+async function loadPrompt(name) {
+  const dir = resolvePromptsDir();
+  return readFile4(path.join(dir, `${name}.md`), "utf8");
+}
+
+// src/agent/sdk.ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+async function runAgent(opts) {
+  const q = query({
+    prompt: opts.prompt,
+    options: {
+      systemPrompt: opts.systemPrompt,
+      allowedTools: opts.allowedTools,
+      agents: opts.agents ?? {},
+      cwd: opts.cwd,
+      model: opts.model ?? "claude-sonnet-4-6",
+      maxTurns: opts.maxTurns ?? 100,
+      // REQUIRED for streaming text deltas. Without it, `stream_event`
+      // messages never fire and the CLI has no progress visibility during
+      // long turns. See docs/research/agent-sdk.md §12 pitfall #1.
+      includePartialMessages: true
+    }
+  });
+  let cost = 0;
+  let turns = 0;
+  let result = "";
+  let sessionId;
+  let success = false;
+  let errorMsg;
+  try {
+    for await (const msg of q) {
+      opts.onMessage?.(msg);
+      if (sessionId === void 0 && typeof msg.session_id === "string") {
+        sessionId = msg.session_id;
+      }
+      if (msg.type === "result") {
+        cost = msg.total_cost_usd;
+        turns = msg.num_turns;
+        if (msg.subtype === "success") {
+          success = true;
+          result = msg.result;
+        } else {
+          success = false;
+          errorMsg = // `SDKResultError` variants don't carry a `result` string; the
+          // useful detail lives in `errors` (array of strings) or the
+          // subtype itself (e.g. "error_max_turns").
+          (msg.errors?.join("; ") ?? "") || `agent error: ${msg.subtype}`;
+        }
+      }
+    }
+  } catch (err) {
+    errorMsg = err instanceof Error ? err.message : String(err);
+    success = false;
+  }
+  return { success, cost, turns, result, sessionId, error: errorMsg };
+}
+
+// src/commands/init.ts
+import { existsSync as existsSync4 } from "fs";
+import { mkdir, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { basename as basename2, join as join5 } from "path";
+async function initWiki(options) {
+  const repoRoot = findNearestAlmanacDir(options.cwd) ?? options.cwd;
+  const almanacDir = getRepoAlmanacDir(repoRoot);
+  const pagesDir = join5(almanacDir, "pages");
+  const readmePath = join5(almanacDir, "README.md");
+  const alreadyExisted = existsSync4(almanacDir);
+  await mkdir(pagesDir, { recursive: true });
+  if (!existsSync4(readmePath)) {
+    await writeFile2(readmePath, starterReadme(), "utf8");
+  }
+  await ensureGitignoreHasIndexDb(repoRoot);
+  const name = toKebabCase(options.name ?? basename2(repoRoot));
+  if (name.length === 0) {
+    throw new Error(
+      "could not derive a wiki name from the current directory; pass --name"
+    );
+  }
+  const description = (options.description ?? "").trim();
+  await ensureGlobalDir();
+  const entry = {
+    name,
+    description,
+    path: repoRoot,
+    registered_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await addEntry(entry);
+  return { entry, almanacDir, created: !alreadyExisted };
+}
+async function ensureGitignoreHasIndexDb(cwd) {
+  const path2 = join5(cwd, ".gitignore");
+  const targets = [
+    ".almanac/index.db",
+    ".almanac/index.db-wal",
+    ".almanac/index.db-shm",
+    // Capture/bootstrap/ingest log files written by the AI pipeline.
+    // These can be multi-megabyte JSONL files and should never be
+    // committed. Bug #4 from codealmanac-known-bugs.md: a 1.8MB bootstrap
+    // log was accidentally committed before this line was added.
+    ".almanac/.capture-*",
+    ".almanac/.bootstrap-*",
+    ".almanac/.ingest-*"
+  ];
+  let existing = "";
+  if (existsSync4(path2)) {
+    existing = await readFile5(path2, "utf8");
+  }
+  const lines = existing.split(/\r?\n/).map((l) => l.trim());
+  const missing = targets.filter((t) => !lines.includes(t));
+  if (missing.length === 0) return;
+  const hasHeader = lines.includes("# codealmanac");
+  const block = hasHeader ? missing.join("\n") + "\n" : `# codealmanac
+${missing.join("\n")}
+`;
+  const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  await writeFile2(path2, `${existing}${sep}${block}`, "utf8");
+}
+function starterReadme() {
+  return `# Wiki
+
+This is the codealmanac wiki for this repository. It captures the knowledge
+the code itself can't say \u2014 decisions, flows, invariants, gotchas, incidents.
+
+The primary reader is an AI coding agent. The secondary reader is a human
+skimming to understand the shape of the codebase. Write accordingly: dense,
+factual, linked.
+
+## Notability bar
+
+Write a page when there is **non-obvious knowledge that will help a future
+agent**. Specifically:
+
+- A decision that took discussion, research, or trial-and-error
+- A gotcha discovered through failure
+- A cross-cutting flow that spans multiple files and isn't obvious from any
+  one of them
+- A constraint or invariant not visible from the code
+- An entity (technology, service, system) referenced by multiple pages
+
+Do not write pages that restate what the code does. Do not write pages of
+inference \u2014 only of observation. Silence is an acceptable outcome.
+
+## Topic taxonomy
+
+Topics form a DAG; pages can belong to multiple topics. Start with these and
+grow as the wiki does:
+
+- \`stack\` \u2014 technologies and services we use (frameworks, databases, APIs)
+- \`systems\` \u2014 custom systems we built (auth, billing, search)
+- \`flows\` \u2014 multi-file processes end-to-end (checkout-flow, publish-flow)
+- \`decisions\` \u2014 "why X over Y"
+- \`incidents\` \u2014 recorded failures and their fixes
+- \`concepts\` \u2014 shared vocabulary specific to this codebase
+
+Domain topics (\`auth\`, \`payments\`, \`frontend\`, \`backend\`) live alongside
+these. A page about JWT rotation belongs to both \`auth\` and \`decisions\`.
+
+## Page shapes
+
+Four shapes cover most of what gets written. They are suggestions, not a
+schema \u2014 a page that fits none of them is fine.
+
+- **Entity** \u2014 a stable named thing (Supabase, Stripe, the search service)
+- **Decision** \u2014 why we chose X over Y
+- **Flow** \u2014 how a multi-file process works end-to-end
+- **Gotcha** \u2014 a specific surprise, failure, or constraint
+
+## Writing conventions
+
+- Every sentence contains a specific fact. If it doesn't, cut it.
+- Neutral tone. "is", not "serves as". No "plays a pivotal role", no
+  interpretive "-ing" clauses, no vague attribution ("experts argue").
+- No hedging or knowledge-gap disclaimers. If you don't know, don't write
+  the sentence.
+- Prose first. Bullets for genuine lists. Tables only for structured
+  comparison.
+- No formulaic conclusions. End with the last substantive fact.
+
+## Linking
+
+One \`[[...]]\` syntax for everything, disambiguated by content:
+
+- \`[[checkout-flow]]\` \u2014 page slug
+- \`[[src/checkout/handler.ts]]\` \u2014 file reference
+- \`[[src/checkout/]]\` \u2014 folder reference (trailing slash)
+- \`[[other-wiki:slug]]\` \u2014 cross-wiki reference
+
+Every page should link to at least one entity when possible. A page with no
+entity link is suspect.
+
+## Pages live in \`.almanac/pages/\`
+
+One markdown file per page, kebab-case slug. Frontmatter carries \`topics:\`
+and optional \`files:\`. The rest is prose.
+`;
+}
+
+// src/commands/bootstrap.ts
+var BOOTSTRAP_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep", "Bash"];
+async function runBootstrap(options) {
+  try {
+    await assertClaudeAuth(options.spawnCli);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      stdout: "",
+      stderr: `almanac: ${msg}
+`,
+      exitCode: 1
+    };
+  }
+  const repoRoot = findNearestAlmanacDir(options.cwd) ?? options.cwd;
+  const almanacDir = getRepoAlmanacDir(repoRoot);
+  const pagesDir = join6(almanacDir, "pages");
+  if (options.force !== true && existsSync5(pagesDir)) {
+    const existing = await countMarkdownPages(pagesDir);
+    if (existing > 0) {
+      return {
+        stdout: "",
+        stderr: `almanac: .almanac/ already initialized with ${existing} page${existing === 1 ? "" : "s"}. Use 'almanac capture' instead, or --force to overwrite.
+`,
+        exitCode: 1
+      };
+    }
+  }
+  if (!existsSync5(almanacDir)) {
+    try {
+      await initWiki({ cwd: repoRoot });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        stdout: "",
+        stderr: `almanac: init failed during bootstrap: ${msg}
+`,
+        exitCode: 1
+      };
+    }
+  }
+  const systemPrompt = await loadPrompt("bootstrap");
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const logName = `.bootstrap-${formatTimestamp(now)}.log`;
+  const logPath = join6(almanacDir, logName);
+  const logStream = createWriteStream(logPath, { flags: "w" });
+  const out = process.stdout;
+  const formatter = new StreamingFormatter({
+    write: (line) => {
+      if (options.quiet !== true) out.write(line);
+    }
+  });
+  const onMessage = (msg) => {
+    try {
+      logStream.write(`${JSON.stringify(msg)}
+`);
+    } catch {
+    }
+    formatter.handle(msg);
+  };
+  const runner = options.runAgent ?? runAgent;
+  const userPrompt = `Begin the bootstrap now. Working directory: ${repoRoot}.`;
+  let result;
+  try {
+    result = await runner({
+      systemPrompt,
+      prompt: userPrompt,
+      allowedTools: BOOTSTRAP_TOOLS,
+      cwd: repoRoot,
+      model: options.model,
+      onMessage
+    });
+  } finally {
+    await closeStream(logStream);
+  }
+  const finalLine = formatFinalLine(result, logPath, repoRoot);
+  if (result.success) {
+    return {
+      stdout: `${finalLine}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    stdout: options.quiet === true ? "" : `${finalLine}
+`,
+    stderr: `almanac: bootstrap failed: ${result.error ?? "unknown error"}
+`,
+    exitCode: 1
+  };
+}
+function formatFinalLine(result, logPath, repoRoot) {
+  const status = result.success ? "done" : "failed";
+  const rel = relative(repoRoot, logPath);
+  const cost = `$${result.cost.toFixed(3)}`;
+  return `[${status}] cost: ${cost}, turns: ${result.turns} (transcript: ${rel})`;
+}
+async function countMarkdownPages(pagesDir) {
+  try {
+    const entries = await readdir(pagesDir, { withFileTypes: true });
+    return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+function closeStream(stream) {
+  return new Promise((resolve) => {
+    stream.end(() => resolve());
+  });
+}
+function formatTimestamp(d) {
+  const pad = (n) => n.toString().padStart(2, "0");
+  const y = d.getFullYear();
+  const mo = pad(d.getMonth() + 1);
+  const da = pad(d.getDate());
+  const h = pad(d.getHours());
+  const mi = pad(d.getMinutes());
+  const s = pad(d.getSeconds());
+  return `${y}${mo}${da}-${h}${mi}${s}`;
+}
+var StreamingFormatter = class {
+  sink;
+  /**
+   * Current agent label. Starts as "bootstrap"; switches when we see an
+   * `Agent` tool-use (slice 5 will exercise this). We still track it here
+   * so the formatter can stay shared between bootstrap and capture.
+   */
+  currentAgent = "bootstrap";
+  constructor(sink) {
+    this.sink = sink;
+  }
+  /**
+   * Swap the top-level agent label. `capture` uses this to relabel from
+   * the default "bootstrap" to "writer" — otherwise the writer's tool-use
+   * output would render as `[bootstrap] …`, which is confusing when you're
+   * reading capture logs.
+   */
+  setAgent(name) {
+    this.currentAgent = name;
+  }
+  handle(msg) {
+    if (msg.type === "assistant") {
+      for (const block of msg.message.content) {
+        if (block.type !== "tool_use") continue;
+        this.handleToolUse(block.name, block.input);
+      }
+      return;
+    }
+    if (msg.type === "result") {
+      const status = msg.subtype === "success" ? "done" : `failed (${msg.subtype})`;
+      this.sink.write(
+        `[${status}] cost: $${msg.total_cost_usd.toFixed(3)}, turns: ${msg.num_turns}
+`
+      );
+      return;
+    }
+  }
+  handleToolUse(name, rawInput) {
+    const input = normalizeToolInput(rawInput);
+    if (name === "Agent") {
+      const sub = typeof input.subagent_type === "string" ? input.subagent_type : "subagent";
+      this.currentAgent = sub;
+      this.sink.write(`[${sub}] starting
+`);
+      return;
+    }
+    const summary = formatToolSummary(name, input);
+    this.sink.write(`[${this.currentAgent}] ${summary}
+`);
+  }
+};
+function normalizeToolInput(raw) {
+  if (typeof raw === "string") {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed !== null && typeof parsed === "object") {
+        return parsed;
+      }
+    } catch {
+    }
+    return {};
+  }
+  if (raw !== null && typeof raw === "object") {
+    return raw;
+  }
+  return {};
+}
+function formatToolSummary(name, input) {
+  switch (name) {
+    case "Read": {
+      const target = stringField(input, "file_path") ?? "?";
+      return `reading ${target}`;
+    }
+    case "Write": {
+      const target = stringField(input, "file_path") ?? "?";
+      return `writing ${target}`;
+    }
+    case "Edit": {
+      const target = stringField(input, "file_path") ?? "?";
+      return `editing ${target}`;
+    }
+    case "Glob": {
+      const pattern = stringField(input, "pattern") ?? "?";
+      return `glob ${pattern}`;
+    }
+    case "Grep": {
+      const pattern = stringField(input, "pattern") ?? "?";
+      return `grep ${pattern}`;
+    }
+    case "Bash": {
+      const command = stringField(input, "command") ?? "?";
+      const trimmed = command.length > 80 ? `${command.slice(0, 77)}...` : command;
+      return `bash ${trimmed}`;
+    }
+    default: {
+      return name;
+    }
+  }
+}
+function stringField(input, key) {
+  const value = input[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/commands/capture.ts
+import { createHash } from "crypto";
+import {
+  createWriteStream as createWriteStream2,
+  existsSync as existsSync6,
+  statSync
+} from "fs";
+import { readFile as readFile6, readdir as readdir2, stat } from "fs/promises";
+import { homedir } from "os";
+import { basename as basename3, join as join7, relative as relative2 } from "path";
+var WRITER_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Agent"];
+var REVIEWER_TOOLS = ["Read", "Grep", "Glob", "Bash"];
+var REVIEWER_DESCRIPTION = "Reviews proposed wiki changes against the full knowledge base for cohesion, duplication, missing links, notability, and writing conventions.";
+async function runCapture(options) {
+  try {
+    await assertClaudeAuth(options.spawnCli);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      stdout: "",
+      stderr: `almanac: ${msg}
+`,
+      exitCode: 1
+    };
+  }
+  const repoRoot = findNearestAlmanacDir(options.cwd);
+  if (repoRoot === null) {
+    return {
+      stdout: "",
+      stderr: "almanac: no .almanac/ found in this directory or any parent. Run 'almanac bootstrap' first.\n",
+      exitCode: 1
+    };
+  }
+  const almanacDir = getRepoAlmanacDir(repoRoot);
+  const pagesDir = join7(almanacDir, "pages");
+  const transcriptResolution = await resolveTranscript({
+    repoRoot,
+    explicit: options.transcriptPath,
+    sessionId: options.sessionId,
+    claudeProjectsDir: options.claudeProjectsDir
+  });
+  if (!transcriptResolution.ok) {
+    return {
+      stdout: "",
+      stderr: `almanac: ${transcriptResolution.error}
+`,
+      exitCode: 1
+    };
+  }
+  const transcriptPath = transcriptResolution.path;
+  const snapshotBefore = await snapshotPages(pagesDir);
+  const systemPrompt = await loadPrompt("writer");
+  const reviewerPrompt = await loadPrompt("reviewer");
+  const agents = {
+    reviewer: {
+      description: REVIEWER_DESCRIPTION,
+      prompt: reviewerPrompt,
+      tools: REVIEWER_TOOLS
+    }
+  };
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const logStem = options.sessionId !== void 0 && options.sessionId.length > 0 ? options.sessionId : formatTimestamp2(now);
+  const logName = `.capture-${logStem}.jsonl`;
+  const logPath = join7(almanacDir, logName);
+  const logStream = createWriteStream2(logPath, { flags: "w" });
+  const out = process.stdout;
+  const formatter = new StreamingFormatter({
+    write: (line) => {
+      if (options.quiet !== true) out.write(line);
+    }
+  });
+  formatter.setAgent("writer");
+  const onMessage = (msg) => {
+    try {
+      logStream.write(`${JSON.stringify(msg)}
+`);
+    } catch {
+    }
+    formatter.handle(msg);
+  };
+  const userPrompt = `Capture this coding session.
+Transcript: ${transcriptPath}.
+Working directory: ${repoRoot}.`;
+  const runner = options.runAgent ?? runAgent;
+  let result;
+  try {
+    result = await runner({
+      systemPrompt,
+      prompt: userPrompt,
+      allowedTools: WRITER_TOOLS,
+      agents,
+      cwd: repoRoot,
+      model: options.model,
+      // Capture sessions can touch many pages; give it more headroom than
+      // bootstrap. The SDK treats `maxTurns` as a hard stop — better to
+      // overshoot than to cut off mid-review.
+      maxTurns: 150,
+      onMessage
+    });
+  } finally {
+    await closeStream2(logStream);
+  }
+  const snapshotAfter = await snapshotPages(pagesDir);
+  const delta = diffSnapshots(snapshotBefore, snapshotAfter);
+  if (!result.success) {
+    return {
+      stdout: "",
+      stderr: `almanac: capture failed: ${result.error ?? "unknown error"}
+(transcript: ${relative2(repoRoot, logPath)})
+`,
+      exitCode: 1
+    };
+  }
+  const summary = formatSummary(result, delta, logPath, repoRoot);
+  return {
+    stdout: `${summary}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function resolveTranscript(args) {
+  if (args.explicit !== void 0 && args.explicit.length > 0) {
+    if (!existsSync6(args.explicit)) {
+      return {
+        ok: false,
+        error: `transcript not found: ${args.explicit}`
+      };
+    }
+    return { ok: true, path: args.explicit };
+  }
+  const projectsDir = args.claudeProjectsDir ?? join7(homedir(), ".claude", "projects");
+  if (!existsSync6(projectsDir)) {
+    return {
+      ok: false,
+      error: `could not auto-resolve transcript; ${projectsDir} does not exist. Pass --session <id> or <transcript-path>.`
+    };
+  }
+  const allTranscripts = await collectTranscripts(projectsDir);
+  if (args.sessionId !== void 0 && args.sessionId.length > 0) {
+    const expected = `${args.sessionId}.jsonl`;
+    const match = allTranscripts.find((t) => basename3(t.path) === expected);
+    if (match === void 0) {
+      return {
+        ok: false,
+        error: `no transcript found for session ${args.sessionId} under ${projectsDir}`
+      };
+    }
+    return { ok: true, path: match.path };
+  }
+  const matches = await filterTranscriptsByCwd(allTranscripts, args.repoRoot);
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      error: `could not auto-resolve transcript under ${projectsDir}; no session matches cwd ${args.repoRoot}. Pass --session <id> or <transcript-path>.`
+    };
+  }
+  matches.sort((a, b) => b.mtime - a.mtime);
+  return { ok: true, path: matches[0].path };
+}
+async function collectTranscripts(projectsDir) {
+  const out = [];
+  let topLevel;
+  try {
+    topLevel = await readdir2(projectsDir);
+  } catch {
+    return out;
+  }
+  for (const name of topLevel) {
+    const projectDir = join7(projectsDir, name);
+    let entries;
+    try {
+      entries = await readdir2(projectDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".jsonl")) continue;
+      const full = join7(projectDir, entry);
+      try {
+        const st = await stat(full);
+        if (st.isFile()) {
+          out.push({ path: full, mtime: st.mtimeMs });
+        }
+      } catch {
+      }
+    }
+  }
+  return out;
+}
+async function filterTranscriptsByCwd(transcripts, repoRoot) {
+  const dirHash = `-${repoRoot.replace(/^\/+/, "").replace(/\//g, "-")}`;
+  const byDirName = transcripts.filter((t) => {
+    const parent = basename3(join7(t.path, ".."));
+    return parent === dirHash || parent.endsWith(dirHash);
+  });
+  if (byDirName.length > 0) return byDirName;
+  const needle = `"cwd":"${repoRoot}"`;
+  const hits = [];
+  for (const t of transcripts) {
+    try {
+      const head = await readHead(t.path, 4096);
+      if (head.includes(needle)) hits.push(t);
+    } catch {
+      continue;
+    }
+  }
+  return hits;
+}
+async function readHead(path2, bytes) {
+  const content = await readFile6(path2, "utf8");
+  return content.length > bytes ? content.slice(0, bytes) : content;
+}
+async function snapshotPages(pagesDir) {
+  const out = /* @__PURE__ */ new Map();
+  if (!existsSync6(pagesDir)) return out;
+  let entries;
+  try {
+    entries = await readdir2(pagesDir);
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) continue;
+    const slug = entry.slice(0, -3);
+    const full = join7(pagesDir, entry);
+    try {
+      const st = statSync(full);
+      if (!st.isFile()) continue;
+      const content = await readFile6(full, "utf8");
+      const hash = createHash("sha256").update(content).digest("hex");
+      const fm = parseFrontmatter(content);
+      out.set(slug, {
+        slug,
+        hash,
+        archived: fm.archived_at !== null
+      });
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}
+function diffSnapshots(before, after) {
+  let created = 0;
+  let updated = 0;
+  let archived = 0;
+  for (const [slug, entry] of after) {
+    const prev = before.get(slug);
+    if (prev === void 0) {
+      created += 1;
+      continue;
+    }
+    if (prev.hash !== entry.hash) {
+      if (!prev.archived && entry.archived) {
+        archived += 1;
+      } else {
+        updated += 1;
+      }
+    }
+  }
+  return { created, updated, archived };
+}
+function formatSummary(result, delta, logPath, repoRoot) {
+  const rel = relative2(repoRoot, logPath);
+  const cost = `$${result.cost.toFixed(3)}`;
+  const { created, updated, archived } = delta;
+  if (created === 0 && updated === 0 && archived === 0) {
+    return `[capture] no new knowledge met the notability bar (0 pages written), cost: ${cost}, turns: ${result.turns} (transcript: ${rel})`;
+  }
+  return `[done] ${updated} page${updated === 1 ? "" : "s"} updated, ${created} created, ${archived} archived, cost: ${cost}, turns: ${result.turns} (transcript: ${rel})`;
+}
+function formatTimestamp2(d) {
+  const pad = (n) => n.toString().padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+function closeStream2(stream) {
+  return new Promise((resolve) => {
+    stream.end(() => resolve());
+  });
+}
+
+// src/commands/reindex.ts
+async function runReindex(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  const result = await runIndexer({ repoRoot });
+  const skipSuffix = result.filesSkipped > 0 ? `; ${result.filesSkipped} skipped` : "";
+  const stdout = `reindexed: ${result.pagesIndexed} page${result.pagesIndexed === 1 ? "" : "s"} (${result.changed} updated, ${result.removed} removed${skipSuffix})
+`;
+  return { result, stdout, exitCode: 0 };
+}
+
+// src/cli/register-wiki-lifecycle-commands.ts
+function registerWikiLifecycleCommands(program) {
+  program.command("bootstrap").description(
+    "scaffold a wiki in this repo via an AI agent (requires ANTHROPIC_API_KEY or Claude subscription)"
+  ).option("--quiet", "suppress per-tool streaming; print only the final line").option("--model <model>", "override the agent model").option("--force", "overwrite an existing populated wiki (default: refuse)").action(
+    async (opts) => {
+      const result = await runBootstrap({
+        cwd: process.cwd(),
+        quiet: opts.quiet,
+        model: opts.model,
+        force: opts.force
+      });
+      emit(result);
+    }
+  );
+  program.command("capture [transcript]").description("run the writer/reviewer pipeline on a session (usually automatic)").option("--session <id>", "target a specific session by ID").option("--quiet", "suppress per-tool streaming; print only the final summary").option("--model <model>", "override the agent model").action(
+    async (transcript, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runCapture({
+        cwd: process.cwd(),
+        transcriptPath: transcript,
+        sessionId: opts.session,
+        quiet: opts.quiet,
+        model: opts.model
+      });
+      emit(result);
+    }
+  );
+  const hook = program.command("hook").description("manage the SessionEnd auto-capture hook");
+  hook.command("install").description("add a SessionEnd entry that runs 'almanac capture' on session end").action(async () => {
+    const result = await runHookInstall();
+    emit(result);
+  });
+  hook.command("uninstall").description("remove codealmanac's SessionEnd entry; leaves foreign entries alone").action(async () => {
+    const result = await runHookUninstall();
+    emit(result);
+  });
+  hook.command("status").description("report whether the SessionEnd hook is installed").action(async () => {
+    const result = await runHookStatus();
+    emit(result);
+  });
+  program.command("reindex").description("force a full rebuild of .almanac/index.db").option("--wiki <name>", "target a specific registered wiki").action(async (opts) => {
+    await autoRegisterIfNeeded(process.cwd());
+    const result = await runReindex({
+      cwd: process.cwd(),
+      wiki: opts.wiki
+    });
+    process.stdout.write(result.stdout);
+    if (result.exitCode !== 0) process.exitCode = result.exitCode;
+  });
+}
+
+// src/cli/register-commands.ts
+function registerCommands(program) {
+  registerQueryCommands(program);
+  registerEditCommands(program);
+  registerWikiLifecycleCommands(program);
+  registerSetupCommands(program);
+}
+export {
+  registerCommands
+};
+//# sourceMappingURL=register-commands-PZMQNGCH.js.map