codealmanac 0.1.0

package/dist/codealmanac.js

@@ -0,0 +1,4036 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { basename as basename6 } from "path";
+import { Command } from "commander";
+
+// src/commands/bootstrap.ts
+import { createWriteStream, existsSync as existsSync4 } from "fs";
+import { readdir } from "fs/promises";
+import { join as join4, relative } from "path";
+
+// src/agent/auth.ts
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { dirname, join } from "path";
+var AUTH_TIMEOUT_MS = 1e4;
+function resolveCliJsPath() {
+  const require2 = createRequire(import.meta.url);
+  const pkgJsonPath = require2.resolve(
+    "@anthropic-ai/claude-agent-sdk/package.json"
+  );
+  return join(dirname(pkgJsonPath), "cli.js");
+}
+var defaultSpawnCli = (args) => {
+  const cliPath = resolveCliJsPath();
+  const child = spawn(process.execPath, [cliPath, ...args], {
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return child;
+};
+async function checkClaudeAuth(spawnCli = defaultSpawnCli) {
+  let child;
+  try {
+    child = spawnCli(["auth", "status", "--json"]);
+  } catch {
+    return { loggedIn: false };
+  }
+  return new Promise((resolve2) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve2(value);
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+      settle({ loggedIn: false });
+    }, AUTH_TIMEOUT_MS);
+    child.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    child.on("error", () => {
+      settle({ loggedIn: false });
+    });
+    child.on("close", (code) => {
+      if (code !== 0 && stdout.trim().length === 0) {
+        void stderr;
+        settle({ loggedIn: false });
+        return;
+      }
+      try {
+        const parsed = JSON.parse(stdout.trim());
+        const loggedIn = parsed.loggedIn === true;
+        const out = { loggedIn };
+        if (typeof parsed.email === "string") out.email = parsed.email;
+        if (typeof parsed.subscriptionType === "string") {
+          out.subscriptionType = parsed.subscriptionType;
+        }
+        if (typeof parsed.authMethod === "string") {
+          out.authMethod = parsed.authMethod;
+        }
+        settle(out);
+      } catch {
+        settle({ loggedIn: false });
+      }
+    });
+  });
+}
+var UNAUTHENTICATED_MESSAGE = "not authenticated to Claude.\n\nOption 1 \u2014 use your Claude subscription (Pro/Max):\n  claude auth login --claudeai\n\nOption 2 \u2014 use a pay-per-token API key:\n  Get one at https://console.anthropic.com\n  export ANTHROPIC_API_KEY=sk-ant-...\n\nVerify with: claude auth status";
+async function assertClaudeAuth(spawnCli = defaultSpawnCli) {
+  const status = await checkClaudeAuth(spawnCli);
+  if (status.loggedIn) {
+    return status;
+  }
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (apiKey !== void 0 && apiKey.length > 0) {
+    return { loggedIn: true, authMethod: "apiKey" };
+  }
+  const err = new Error(UNAUTHENTICATED_MESSAGE);
+  err.code = "CLAUDE_AUTH_MISSING";
+  throw err;
+}
+
+// src/agent/prompts.ts
+import { existsSync } from "fs";
+import { readFile } 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 (!existsSync(dir)) return false;
+  return PROMPT_NAMES.every(
+    (name) => existsSync(path.join(dir, `${name}.md`))
+  );
+}
+async function loadPrompt(name) {
+  const dir = resolvePromptsDir();
+  return readFile(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/paths.ts
+import { existsSync as existsSync2 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname2, isAbsolute, join as join2, resolve } from "path";
+function getGlobalAlmanacDir() {
+  return join2(homedir(), ".almanac");
+}
+function getRegistryPath() {
+  return join2(getGlobalAlmanacDir(), "registry.json");
+}
+function getRepoAlmanacDir(cwd) {
+  return join2(cwd, ".almanac");
+}
+function findNearestAlmanacDir(startDir) {
+  const globalDir = getGlobalAlmanacDir();
+  let current = isAbsolute(startDir) ? startDir : resolve(startDir);
+  while (true) {
+    const candidate = join2(current, ".almanac");
+    if (candidate !== globalDir && existsSync2(candidate)) {
+      return current;
+    }
+    const parent = dirname2(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+// src/commands/init.ts
+import { existsSync as existsSync3 } from "fs";
+import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { basename, join as join3 } from "path";
+
+// src/slug.ts
+function toKebabCase(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// src/registry/index.ts
+import { mkdir, readFile as readFile2, rename, writeFile } from "fs/promises";
+import { dirname as dirname3 } from "path";
+async function readRegistry() {
+  const path3 = getRegistryPath();
+  let raw;
+  try {
+    raw = await readFile2(path3, "utf8");
+  } catch (err) {
+    if (isNodeError(err) && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`registry at ${path3} is not valid JSON: ${message}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`registry at ${path3} must be a JSON array`);
+  }
+  return parsed.map((item, idx) => {
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`registry entry ${idx} is not an object`);
+    }
+    const e = item;
+    const name = typeof e.name === "string" ? e.name : "";
+    const path4 = typeof e.path === "string" ? e.path : "";
+    if (name.length === 0) {
+      throw new Error(`registry entry ${idx} is missing a non-empty "name"`);
+    }
+    if (path4.length === 0) {
+      throw new Error(`registry entry ${idx} is missing a non-empty "path"`);
+    }
+    return {
+      name,
+      description: typeof e.description === "string" ? e.description : "",
+      path: path4,
+      registered_at: typeof e.registered_at === "string" ? e.registered_at : ""
+    };
+  });
+}
+async function writeRegistry(entries) {
+  const path3 = getRegistryPath();
+  await mkdir(dirname3(path3), { recursive: true });
+  const body = `${JSON.stringify(entries, null, 2)}
+`;
+  const tmpPath = `${path3}.tmp`;
+  await writeFile(tmpPath, body, "utf8");
+  await rename(tmpPath, path3);
+}
+function pathsEqual(a, b) {
+  if (process.platform === "darwin" || process.platform === "win32") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+async function addEntry(entry) {
+  const existing = await readRegistry();
+  const filtered = existing.filter(
+    (e) => e.name !== entry.name && !pathsEqual(e.path, entry.path)
+  );
+  filtered.push(entry);
+  await writeRegistry(filtered);
+  return filtered;
+}
+async function dropEntry(name) {
+  const existing = await readRegistry();
+  const idx = existing.findIndex((e) => e.name === name);
+  if (idx === -1) {
+    return null;
+  }
+  const [removed] = existing.splice(idx, 1);
+  await writeRegistry(existing);
+  return removed ?? null;
+}
+async function findEntry(params) {
+  const entries = await readRegistry();
+  for (const entry of entries) {
+    if (params.name !== void 0 && entry.name === params.name) return entry;
+    if (params.path !== void 0 && pathsEqual(entry.path, params.path)) {
+      return entry;
+    }
+  }
+  return null;
+}
+async function ensureGlobalDir() {
+  await mkdir(getGlobalAlmanacDir(), { recursive: true });
+}
+function isNodeError(err) {
+  return err instanceof Error && "code" in err;
+}
+
+// src/commands/init.ts
+async function initWiki(options) {
+  const repoRoot = findNearestAlmanacDir(options.cwd) ?? options.cwd;
+  const almanacDir = getRepoAlmanacDir(repoRoot);
+  const pagesDir = join3(almanacDir, "pages");
+  const readmePath = join3(almanacDir, "README.md");
+  const alreadyExisted = existsSync3(almanacDir);
+  await mkdir2(pagesDir, { recursive: true });
+  if (!existsSync3(readmePath)) {
+    await writeFile2(readmePath, starterReadme(), "utf8");
+  }
+  await ensureGitignoreHasIndexDb(repoRoot);
+  const name = toKebabCase(options.name ?? basename(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 path3 = join3(cwd, ".gitignore");
+  const targets = [
+    ".almanac/index.db",
+    ".almanac/index.db-wal",
+    ".almanac/index.db-shm"
+  ];
+  let existing = "";
+  if (existsSync3(path3)) {
+    existing = await readFile3(path3, "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(path3, `${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 = join4(almanacDir, "pages");
+  if (options.force !== true && existsSync4(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 (!existsSync4(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 = join4(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((resolve2) => {
+    stream.end(() => resolve2());
+  });
+}
+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 existsSync5,
+  statSync
+} from "fs";
+import { readFile as readFile4, readdir as readdir2, stat } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { basename as basename2, join as join5, relative as relative2 } from "path";
+
+// src/indexer/frontmatter.ts
+import yaml from "js-yaml";
+function parseFrontmatter(raw) {
+  const empty = {
+    topics: [],
+    files: [],
+    archived_at: null,
+    superseded_by: null,
+    supersedes: null,
+    body: raw
+  };
+  if (!raw.startsWith("---")) {
+    return empty;
+  }
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (match === null) {
+    return empty;
+  }
+  const yamlBody = match[1] ?? "";
+  const body = match[2] ?? "";
+  let parsed;
+  try {
+    parsed = yaml.load(yamlBody);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`almanac: malformed frontmatter (${message})
+`);
+    return empty;
+  }
+  if (parsed === null || parsed === void 0) {
+    return { ...empty, body };
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ...empty, body };
+  }
+  const obj = parsed;
+  return {
+    title: coerceString(obj.title),
+    topics: coerceStringArray(obj.topics),
+    files: coerceStringArray(obj.files),
+    archived_at: coerceEpochSeconds(obj.archived_at),
+    superseded_by: coerceString(obj.superseded_by) ?? null,
+    supersedes: coerceString(obj.supersedes) ?? null,
+    body
+  };
+}
+function firstH1(body) {
+  const lines = body.split(/\r?\n/, 40);
+  for (const line of lines) {
+    const m = line.match(/^#\s+(.+?)\s*#*\s*$/);
+    if (m !== null) {
+      return m[1];
+    }
+  }
+  return void 0;
+}
+function coerceString(v) {
+  if (typeof v === "string" && v.trim().length > 0) return v.trim();
+  return void 0;
+}
+function coerceStringArray(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const item of v) {
+    if (typeof item === "string" && item.trim().length > 0) {
+      out.push(item.trim());
+    }
+  }
+  return out;
+}
+function coerceEpochSeconds(v) {
+  if (v instanceof Date) {
+    return Math.floor(v.getTime() / 1e3);
+  }
+  if (typeof v === "number" && Number.isFinite(v)) {
+    return Math.floor(v);
+  }
+  if (typeof v === "string" && v.trim().length > 0) {
+    const t = Date.parse(v.trim());
+    if (!Number.isNaN(t)) {
+      return Math.floor(t / 1e3);
+    }
+  }
+  return null;
+}
+
+// src/commands/capture.ts
+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 init' or 'almanac bootstrap' first.\n",
+      exitCode: 1
+    };
+  }
+  const almanacDir = getRepoAlmanacDir(repoRoot);
+  const pagesDir = join5(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 logName = `.capture-${formatTimestamp2(now)}.log`;
+  const logPath = join5(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 (!existsSync5(args.explicit)) {
+      return {
+        ok: false,
+        error: `transcript not found: ${args.explicit}`
+      };
+    }
+    return { ok: true, path: args.explicit };
+  }
+  const projectsDir = args.claudeProjectsDir ?? join5(homedir2(), ".claude", "projects");
+  if (!existsSync5(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) => basename2(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 = join5(projectsDir, name);
+    let entries;
+    try {
+      entries = await readdir2(projectDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".jsonl")) continue;
+      const full = join5(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 = basename2(join5(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(path3, bytes) {
+  const content = await readFile4(path3, "utf8");
+  return content.length > bytes ? content.slice(0, bytes) : content;
+}
+async function snapshotPages(pagesDir) {
+  const out = /* @__PURE__ */ new Map();
+  if (!existsSync5(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 = join5(pagesDir, entry);
+    try {
+      const st = statSync(full);
+      if (!st.isFile()) continue;
+      const content = await readFile4(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((resolve2) => {
+    stream.end(() => resolve2());
+  });
+}
+
+// src/commands/hook.ts
+import { existsSync as existsSync6 } from "fs";
+import { mkdir as mkdir3, readFile as readFile5, rename as rename2, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import path2 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var HOOK_TIMEOUT_SECONDS = 10;
+async function runHookInstall(options = {}) {
+  const script = resolveHookScriptPath(options);
+  if (!script.ok) {
+    return { stdout: "", stderr: `almanac: ${script.error}
+`, exitCode: 1 };
+  }
+  const settingsPath = resolveSettingsPath(options);
+  const settings = await readSettings(settingsPath);
+  const existing = (settings.hooks?.SessionEnd ?? []).slice();
+  const ourEntries = existing.filter((e) => e.command === script.path);
+  const foreignEntries = existing.filter((e) => e.command !== script.path);
+  const stale = foreignEntries.filter(
+    (e) => e.command.endsWith("almanac-capture.sh")
+  );
+  const unrelated = foreignEntries.filter(
+    (e) => !e.command.endsWith("almanac-capture.sh")
+  );
+  if (unrelated.length > 0) {
+    const existingStr = unrelated.map((e) => `  - ${e.command}`).join("\n");
+    return {
+      stdout: "",
+      stderr: `almanac: SessionEnd hook already has a foreign entry:
+${existingStr}
+Remove it manually from ${settingsPath} if you want almanac to manage the hook.
+`,
+      exitCode: 1
+    };
+  }
+  if (ourEntries.length > 0 && stale.length === 0) {
+    return {
+      stdout: `almanac: SessionEnd hook already installed at ${script.path}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const newEntries = [
+    {
+      type: "command",
+      command: script.path,
+      timeout: HOOK_TIMEOUT_SECONDS
+    }
+  ];
+  settings.hooks = { ...settings.hooks ?? {}, SessionEnd: newEntries };
+  await writeSettings(settingsPath, settings);
+  return {
+    stdout: `almanac: SessionEnd hook installed
+  script: ${script.path}
+  settings: ${settingsPath}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function runHookUninstall(options = {}) {
+  const settingsPath = resolveSettingsPath(options);
+  if (!existsSync6(settingsPath)) {
+    return {
+      stdout: `almanac: SessionEnd hook not installed (no settings file)
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const settings = await readSettings(settingsPath);
+  const existing = (settings.hooks?.SessionEnd ?? []).slice();
+  const kept = existing.filter((e) => !e.command.endsWith("almanac-capture.sh"));
+  const removed = existing.length - kept.length;
+  if (removed === 0) {
+    return {
+      stdout: `almanac: SessionEnd hook not installed
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  if (settings.hooks !== void 0) {
+    if (kept.length === 0) {
+      const { SessionEnd: _dropped, ...rest } = settings.hooks;
+      void _dropped;
+      settings.hooks = rest;
+    } else {
+      settings.hooks = { ...settings.hooks, SessionEnd: kept };
+    }
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+  }
+  await writeSettings(settingsPath, settings);
+  return {
+    stdout: `almanac: SessionEnd hook removed
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function runHookStatus(options = {}) {
+  const script = resolveHookScriptPath(options);
+  const settingsPath = resolveSettingsPath(options);
+  if (!existsSync6(settingsPath)) {
+    return {
+      stdout: `SessionEnd hook: not installed
+settings: ${settingsPath} (does not exist)
+` + (script.ok ? `script would be: ${script.path}
+` : ""),
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const settings = await readSettings(settingsPath);
+  const existing = settings.hooks?.SessionEnd ?? [];
+  const ours = existing.find((e) => e.command.endsWith("almanac-capture.sh"));
+  if (ours === void 0) {
+    const foreign = existing.map((e) => `  - ${e.command}`).join("\n");
+    return {
+      stdout: `SessionEnd hook: not installed
+settings: ${settingsPath}
+` + (existing.length > 0 ? `(${existing.length} foreign entr${existing.length === 1 ? "y" : "ies"} present:
+${foreign})
+` : "") + (script.ok ? `script would be: ${script.path}
+` : ""),
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    stdout: `SessionEnd hook: installed
+script: ${ours.command}
+settings: ${settingsPath}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+function resolveSettingsPath(options) {
+  if (options.settingsPath !== void 0) return options.settingsPath;
+  return path2.join(homedir3(), ".claude", "settings.json");
+}
+function resolveHookScriptPath(options) {
+  if (options.hookScriptPath !== void 0) {
+    return { ok: true, path: options.hookScriptPath };
+  }
+  const here = path2.dirname(fileURLToPath2(import.meta.url));
+  const candidates = [
+    // Bundled: `.../codealmanac/dist/codealmanac.js` → `../hooks/…`
+    path2.resolve(here, "..", "hooks", "almanac-capture.sh"),
+    // Source: `.../codealmanac/src/commands/hook.ts` → `../../hooks/…`
+    path2.resolve(here, "..", "..", "hooks", "almanac-capture.sh"),
+    // Defensive nested fallback.
+    path2.resolve(here, "..", "..", "..", "hooks", "almanac-capture.sh")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync6(candidate)) {
+      return { ok: true, path: candidate };
+    }
+  }
+  return {
+    ok: false,
+    error: `could not locate hooks/almanac-capture.sh. Tried:
+` + candidates.map((c) => `  - ${c}`).join("\n")
+  };
+}
+async function readSettings(settingsPath) {
+  if (!existsSync6(settingsPath)) return {};
+  try {
+    const raw = await readFile5(settingsPath, "utf8");
+    if (raw.trim().length === 0) return {};
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object") return {};
+    return parsed;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`failed to read ${settingsPath}: ${msg}`);
+  }
+}
+async function writeSettings(settingsPath, settings) {
+  const dir = path2.dirname(settingsPath);
+  await mkdir3(dir, { recursive: true });
+  const tmp = `${settingsPath}.almanac-tmp-${process.pid}`;
+  const body = `${JSON.stringify(settings, null, 2)}
+`;
+  await writeFile3(tmp, body, "utf8");
+  await rename2(tmp, settingsPath);
+}
+
+// src/commands/health.ts
+import { existsSync as existsSync10 } from "fs";
+import { readFile as readFile8 } from "fs/promises";
+import { basename as basename4, join as join8 } from "path";
+import fg2 from "fast-glob";
+
+// src/indexer/duration.ts
+function parseDuration(input) {
+  const trimmed = input.trim();
+  const m = trimmed.match(/^(\d+)([mhdw])$/);
+  if (m === null) {
+    throw new Error(
+      `invalid duration "${input}" (expected Nw, Nd, Nh, or Nm \u2014 e.g. 2w, 30d)`
+    );
+  }
+  const n = Number.parseInt(m[1] ?? "0", 10);
+  const unit = m[2];
+  switch (unit) {
+    case "m":
+      return n * 60;
+    case "h":
+      return n * 60 * 60;
+    case "d":
+      return n * 60 * 60 * 24;
+    case "w":
+      return n * 60 * 60 * 24 * 7;
+    default:
+      throw new Error(`invalid duration unit "${unit ?? ""}"`);
+  }
+}
+
+// src/indexer/index.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync8, statSync as statSync2 } from "fs";
+import { readFile as readFile7, utimes } from "fs/promises";
+import { basename as basename3, join as join6, relative as relative3 } from "path";
+import fg from "fast-glob";
+
+// src/topics/yaml.ts
+import { existsSync as existsSync7 } from "fs";
+import { mkdir as mkdir4, readFile as readFile6, rename as rename3, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname4 } from "path";
+import yaml2 from "js-yaml";
+async function loadTopicsFile(path3) {
+  if (!existsSync7(path3)) {
+    return { topics: [] };
+  }
+  let raw;
+  try {
+    raw = await readFile6(path3, "utf8");
+  } catch (err) {
+    if (isNodeError2(err) && err.code === "ENOENT") {
+      return { topics: [] };
+    }
+    throw err;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { topics: [] };
+  }
+  let parsed;
+  try {
+    parsed = yaml2.load(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`topics.yaml at ${path3} is not valid YAML: ${message}`);
+  }
+  if (parsed === null || parsed === void 0) {
+    return { topics: [] };
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`topics.yaml at ${path3} must be a mapping`);
+  }
+  const obj = parsed;
+  const rawTopics = obj.topics;
+  if (rawTopics === void 0 || rawTopics === null) {
+    return { topics: [] };
+  }
+  if (!Array.isArray(rawTopics)) {
+    throw new Error(`topics.yaml at ${path3} \u2014 "topics" must be a list`);
+  }
+  const topics = [];
+  for (const item of rawTopics) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      continue;
+    }
+    const entry = item;
+    const slugRaw = entry.slug;
+    if (typeof slugRaw !== "string" || slugRaw.trim().length === 0) continue;
+    const slug = toKebabCase(slugRaw);
+    if (slug.length === 0) continue;
+    const title = typeof entry.title === "string" && entry.title.trim().length > 0 ? entry.title.trim() : titleCase(slug);
+    const description = typeof entry.description === "string" && entry.description.trim().length > 0 ? entry.description.trim() : null;
+    const parents = [];
+    if (Array.isArray(entry.parents)) {
+      for (const p of entry.parents) {
+        if (typeof p === "string" && p.trim().length > 0) {
+          const ps = toKebabCase(p);
+          if (ps.length > 0 && ps !== slug && !parents.includes(ps)) {
+            parents.push(ps);
+          }
+        }
+      }
+    }
+    topics.push({ slug, title, description, parents });
+  }
+  return { topics };
+}
+async function writeTopicsFile(path3, file) {
+  const sorted = [...file.topics].sort((a, b) => a.slug.localeCompare(b.slug));
+  const doc = {
+    topics: sorted.map((t) => {
+      return {
+        slug: t.slug,
+        title: t.title,
+        description: t.description,
+        parents: t.parents
+      };
+    })
+  };
+  const header = `# .almanac/topics.yaml \u2014 source of truth for topic metadata.
+# Managed by \`almanac topics\` commands. User-added comments
+# between entries will be stripped on the next write (js-yaml
+# doesn't round-trip comments). Edit at your own risk \u2014 or use the
+# CLI (\`almanac topics create|link|describe|rename|delete\`)
+# which preserves the structure correctly.
+`;
+  const body = yaml2.dump(doc, {
+    lineWidth: 100,
+    noRefs: true,
+    sortKeys: false
+  });
+  const content = `${header}${body}`;
+  const tmpPath = `${path3}.tmp`;
+  const parent = dirname4(path3);
+  if (!existsSync7(parent)) {
+    await mkdir4(parent, { recursive: true });
+  }
+  await writeFile4(tmpPath, content, "utf8");
+  await rename3(tmpPath, path3);
+}
+function findTopic(file, slug) {
+  for (const t of file.topics) {
+    if (t.slug === slug) return t;
+  }
+  return null;
+}
+function ensureTopic(file, slug) {
+  const existing = findTopic(file, slug);
+  if (existing !== null) return existing;
+  const entry = {
+    slug,
+    title: titleCase(slug),
+    description: null,
+    parents: []
+  };
+  file.topics.push(entry);
+  return entry;
+}
+function titleCase(slug) {
+  if (slug.length === 0) return slug;
+  return slug.split("-").filter((s) => s.length > 0).map((s) => `${s[0]?.toUpperCase() ?? ""}${s.slice(1)}`).join(" ");
+}
+function isNodeError2(err) {
+  return err instanceof Error && "code" in err;
+}
+
+// src/indexer/paths.ts
+function normalizePath(raw, isDir) {
+  const normalized = normalizeShape(raw, isDir);
+  return normalized.toLowerCase();
+}
+function normalizePathPreservingCase(raw, isDir) {
+  return normalizeShape(raw, isDir);
+}
+function normalizeShape(raw, isDir) {
+  let s = raw.trim();
+  s = s.replace(/\\+/g, "/");
+  while (s.startsWith("./")) s = s.slice(2);
+  s = s.replace(/\/+/g, "/");
+  s = s.replace(/\/+$/, "");
+  if (isDir) {
+    return `${s}/`;
+  }
+  return s;
+}
+function looksLikeDir(raw) {
+  const s = raw.trim().replace(/\\+/g, "/");
+  return s.endsWith("/");
+}
+
+// src/indexer/schema.ts
+import Database from "better-sqlite3";
+var SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS pages (
+  slug          TEXT PRIMARY KEY,
+  title         TEXT,
+  file_path     TEXT NOT NULL,
+  content_hash  TEXT NOT NULL,
+  updated_at    INTEGER NOT NULL,
+  archived_at   INTEGER,
+  superseded_by TEXT
+);
+
+CREATE TABLE IF NOT EXISTS topics (
+  slug        TEXT PRIMARY KEY,
+  title       TEXT,
+  description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS page_topics (
+  page_slug  TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  topic_slug TEXT NOT NULL,
+  PRIMARY KEY (page_slug, topic_slug)
+);
+
+CREATE TABLE IF NOT EXISTS topic_parents (
+  child_slug  TEXT NOT NULL,
+  parent_slug TEXT NOT NULL,
+  PRIMARY KEY (child_slug, parent_slug),
+  CHECK (child_slug != parent_slug)
+);
+
+CREATE TABLE IF NOT EXISTS file_refs (
+  page_slug     TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  path          TEXT NOT NULL,
+  original_path TEXT NOT NULL,
+  is_dir        INTEGER NOT NULL,
+  PRIMARY KEY (page_slug, path)
+);
+CREATE INDEX IF NOT EXISTS idx_file_refs_path ON file_refs(path);
+
+CREATE TABLE IF NOT EXISTS wikilinks (
+  source_slug TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  target_slug TEXT NOT NULL,
+  PRIMARY KEY (source_slug, target_slug)
+);
+
+CREATE TABLE IF NOT EXISTS cross_wiki_links (
+  source_slug TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  target_wiki TEXT NOT NULL,
+  target_slug TEXT NOT NULL,
+  PRIMARY KEY (source_slug, target_wiki, target_slug)
+);
+
+-- NOTE: virtual FTS5 table \u2014 ON DELETE CASCADE from pages does NOT apply.
+-- The indexer must explicitly DELETE FROM fts_pages whenever it removes
+-- or replaces a page row, or we leak orphaned FTS rows.
+CREATE VIRTUAL TABLE IF NOT EXISTS fts_pages USING fts5(slug, title, content);
+`;
+var SCHEMA_VERSION = 2;
+function openIndex(dbPath) {
+  const db = new Database(dbPath);
+  const mode = db.pragma("journal_mode", { simple: true });
+  if (typeof mode !== "string" || mode.toLowerCase() !== "wal") {
+    db.pragma("journal_mode = WAL");
+  }
+  db.pragma("foreign_keys = ON");
+  const rawVersion = db.pragma("user_version", { simple: true });
+  const currentVersion = typeof rawVersion === "number" ? rawVersion : 0;
+  if (currentVersion < SCHEMA_VERSION) {
+    db.exec("DROP TABLE IF EXISTS file_refs");
+    try {
+      db.exec("UPDATE pages SET content_hash = ''");
+    } catch {
+    }
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+  }
+  db.exec(SCHEMA_DDL);
+  return db;
+}
+
+// src/indexer/wikilinks.ts
+function classifyWikilink(raw) {
+  const pipe = raw.indexOf("|");
+  let body = pipe === -1 ? raw : raw.slice(0, pipe);
+  body = body.trim();
+  if (body.length === 0) return null;
+  const firstColon = body.indexOf(":");
+  const firstSlash = body.indexOf("/");
+  if (firstColon !== -1 && (firstSlash === -1 || firstColon < firstSlash)) {
+    const wiki = body.slice(0, firstColon).trim();
+    const target2 = body.slice(firstColon + 1).trim();
+    if (wiki.length === 0 || target2.length === 0) return null;
+    return { kind: "xwiki", wiki, target: target2 };
+  }
+  if (firstSlash !== -1) {
+    const isDir = looksLikeDir(body);
+    const path3 = normalizePath(body, isDir);
+    const originalPath = normalizePathPreservingCase(body, isDir);
+    if (path3.length === 0) return null;
+    return isDir ? { kind: "folder", path: path3, originalPath } : { kind: "file", path: path3, originalPath };
+  }
+  const target = toKebabCase(body);
+  if (target.length === 0) return null;
+  return { kind: "page", target };
+}
+function extractWikilinks(body) {
+  const out = [];
+  const re = /\[\[([^\]\n]+)\]\]/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const ref = classifyWikilink(m[1] ?? "");
+    if (ref !== null) out.push(ref);
+  }
+  return out;
+}
+
+// src/indexer/index.ts
+var TOPICS_YAML_FILENAME = "topics.yaml";
+var PAGES_GLOB = "**/*.md";
+async function ensureFreshIndex(ctx) {
+  const almanacDir = join6(ctx.repoRoot, ".almanac");
+  const dbPath = join6(almanacDir, "index.db");
+  const pagesDir = join6(almanacDir, "pages");
+  if (!existsSync8(pagesDir)) {
+    const db = openIndex(dbPath);
+    db.close();
+    return emptyResult();
+  }
+  if (!existsSync8(dbPath) || pagesNewerThan(pagesDir, dbPath) || topicsYamlNewerThan(almanacDir, dbPath)) {
+    return runIndexer(ctx);
+  }
+  return emptyResult();
+}
+function emptyResult() {
+  return {
+    changed: 0,
+    removed: 0,
+    total: 0,
+    pagesIndexed: 0,
+    filesSeen: 0,
+    filesSkipped: 0
+  };
+}
+async function runIndexer(ctx) {
+  const almanacDir = join6(ctx.repoRoot, ".almanac");
+  const dbPath = join6(almanacDir, "index.db");
+  const pagesDir = join6(almanacDir, "pages");
+  const db = openIndex(dbPath);
+  let result;
+  try {
+    result = await indexPagesInto(db, pagesDir);
+    await applyTopicsYaml(db, join6(almanacDir, TOPICS_YAML_FILENAME));
+  } finally {
+    db.close();
+  }
+  try {
+    const now = /* @__PURE__ */ new Date();
+    await utimes(dbPath, now, now);
+  } catch {
+  }
+  return result;
+}
+async function indexPagesInto(db, pagesDir) {
+  const files = await fg(PAGES_GLOB, {
+    cwd: pagesDir,
+    absolute: false,
+    onlyFiles: true,
+    caseSensitiveMatch: true
+  });
+  const existingRows = db.prepare("SELECT slug, content_hash, file_path FROM pages").all();
+  const existingBySlug = /* @__PURE__ */ new Map();
+  for (const row of existingRows) existingBySlug.set(row.slug, row);
+  const planned = [];
+  const seenSlugs = /* @__PURE__ */ new Set();
+  let filesSkipped = 0;
+  for (const rel of files) {
+    const fullPath = join6(pagesDir, rel);
+    const base = basename3(rel, ".md");
+    const slug = toKebabCase(base);
+    if (slug.length === 0) {
+      process.stderr.write(
+        `almanac: skipping "${rel}" \u2014 filename has no slug-able characters
+`
+      );
+      filesSkipped++;
+      continue;
+    }
+    if (slug !== base) {
+      process.stderr.write(
+        `almanac: warning \u2014 "${rel}" is not canonical; indexed as slug "${slug}"
+`
+      );
+    }
+    if (seenSlugs.has(slug)) {
+      process.stderr.write(
+        `almanac: warning \u2014 slug "${slug}" collides with an earlier file; skipping "${rel}"
+`
+      );
+      filesSkipped++;
+      continue;
+    }
+    let st;
+    let raw;
+    try {
+      st = statSync2(fullPath);
+      raw = await readFile7(fullPath, "utf8");
+    } catch (err) {
+      if (err instanceof Error && "code" in err && (err.code === "ENOENT" || err.code === "EACCES")) {
+        process.stderr.write(
+          `almanac: skipping "${rel}" \u2014 ${err.message}
+`
+        );
+        filesSkipped++;
+        continue;
+      }
+      throw err;
+    }
+    seenSlugs.add(slug);
+    const updatedAt = Math.floor(st.mtimeMs / 1e3);
+    const contentHash = hashContent(raw);
+    const existing = existingBySlug.get(slug);
+    if (existing !== void 0 && existing.content_hash === contentHash && existing.file_path === fullPath) {
+      continue;
+    }
+    const fm = parseFrontmatter(raw);
+    const title = fm.title ?? firstH1(fm.body) ?? base;
+    const links = extractWikilinks(fm.body);
+    planned.push({
+      slug,
+      title,
+      filePath: rel,
+      fullPath,
+      contentHash,
+      updatedAt,
+      archivedAt: fm.archived_at,
+      supersededBy: fm.superseded_by,
+      topics: fm.topics,
+      frontmatterFiles: fm.files,
+      wikilinks: links,
+      content: fm.body
+    });
+  }
+  const toDelete = [];
+  for (const slug of existingBySlug.keys()) {
+    if (!seenSlugs.has(slug)) toDelete.push(slug);
+  }
+  const deleteByPage = db.prepare("DELETE FROM pages WHERE slug = ?");
+  const deleteFtsByPage = db.prepare(
+    "DELETE FROM fts_pages WHERE slug = ?"
+  );
+  const replacePage = db.prepare(
+    `INSERT INTO pages (slug, title, file_path, content_hash, updated_at, archived_at, superseded_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(slug) DO UPDATE SET
+       title         = excluded.title,
+       file_path     = excluded.file_path,
+       content_hash  = excluded.content_hash,
+       updated_at    = excluded.updated_at,
+       archived_at   = excluded.archived_at,
+       superseded_by = excluded.superseded_by`
+  );
+  const deletePageTopics = db.prepare(
+    "DELETE FROM page_topics WHERE page_slug = ?"
+  );
+  const insertPageTopic = db.prepare(
+    "INSERT OR IGNORE INTO page_topics (page_slug, topic_slug) VALUES (?, ?)"
+  );
+  const insertTopic = db.prepare(
+    "INSERT OR IGNORE INTO topics (slug, title) VALUES (?, ?)"
+  );
+  const deleteFileRefs = db.prepare(
+    "DELETE FROM file_refs WHERE page_slug = ?"
+  );
+  const insertFileRef = db.prepare(
+    "INSERT OR IGNORE INTO file_refs (page_slug, path, original_path, is_dir) VALUES (?, ?, ?, ?)"
+  );
+  const deleteWikilinks = db.prepare(
+    "DELETE FROM wikilinks WHERE source_slug = ?"
+  );
+  const insertWikilink = db.prepare(
+    "INSERT OR IGNORE INTO wikilinks (source_slug, target_slug) VALUES (?, ?)"
+  );
+  const deleteXwiki = db.prepare(
+    "DELETE FROM cross_wiki_links WHERE source_slug = ?"
+  );
+  const insertXwiki = db.prepare(
+    "INSERT OR IGNORE INTO cross_wiki_links (source_slug, target_wiki, target_slug) VALUES (?, ?, ?)"
+  );
+  const insertFts = db.prepare(
+    "INSERT INTO fts_pages (slug, title, content) VALUES (?, ?, ?)"
+  );
+  const apply = db.transaction(() => {
+    for (const slug of toDelete) {
+      deleteFtsByPage.run(slug);
+      deleteByPage.run(slug);
+    }
+    for (const p of planned) {
+      deletePageTopics.run(p.slug);
+      deleteFileRefs.run(p.slug);
+      deleteWikilinks.run(p.slug);
+      deleteXwiki.run(p.slug);
+      deleteFtsByPage.run(p.slug);
+      replacePage.run(
+        p.slug,
+        p.title,
+        p.fullPath,
+        p.contentHash,
+        p.updatedAt,
+        p.archivedAt,
+        p.supersededBy
+      );
+      for (const topic of p.topics) {
+        const topicSlug = toKebabCase(topic);
+        if (topicSlug.length === 0) continue;
+        insertTopic.run(topicSlug, titleCase(topicSlug));
+        insertPageTopic.run(p.slug, topicSlug);
+      }
+      for (const raw of p.frontmatterFiles) {
+        const isDir = looksLikeDir(raw);
+        const path3 = normalizePath(raw, isDir);
+        const originalPath = normalizePathPreservingCase(raw, isDir);
+        if (path3.length === 0) continue;
+        insertFileRef.run(p.slug, path3, originalPath, isDir ? 1 : 0);
+      }
+      for (const ref of p.wikilinks) {
+        switch (ref.kind) {
+          case "page":
+            insertWikilink.run(p.slug, ref.target);
+            break;
+          case "file":
+            insertFileRef.run(p.slug, ref.path, ref.originalPath, 0);
+            break;
+          case "folder":
+            insertFileRef.run(p.slug, ref.path, ref.originalPath, 1);
+            break;
+          case "xwiki":
+            insertXwiki.run(p.slug, ref.wiki, ref.target);
+            break;
+        }
+      }
+      insertFts.run(p.slug, p.title, p.content);
+    }
+  });
+  apply();
+  void relative3;
+  const pagesIndexed = seenSlugs.size;
+  return {
+    changed: planned.length,
+    removed: toDelete.length,
+    total: pagesIndexed,
+    pagesIndexed,
+    filesSeen: files.length,
+    filesSkipped
+  };
+}
+function pagesNewerThan(pagesDir, dbPath) {
+  let dbMtime;
+  try {
+    dbMtime = statSync2(dbPath).mtimeMs;
+  } catch {
+    return true;
+  }
+  const entries = fg.sync(PAGES_GLOB, {
+    cwd: pagesDir,
+    absolute: true,
+    onlyFiles: true,
+    stats: true
+  });
+  for (const entry of entries) {
+    const mtime = entry.stats?.mtimeMs;
+    if (mtime !== void 0 && mtime > dbMtime) return true;
+  }
+  return false;
+}
+function hashContent(raw) {
+  return createHash2("sha256").update(raw).digest("hex");
+}
+function topicsYamlNewerThan(almanacDir, dbPath) {
+  const path3 = join6(almanacDir, "topics.yaml");
+  if (!existsSync8(path3)) return false;
+  let dbMtime;
+  try {
+    dbMtime = statSync2(dbPath).mtimeMs;
+  } catch {
+    return true;
+  }
+  try {
+    const st = statSync2(path3);
+    return st.mtimeMs > dbMtime;
+  } catch {
+    return false;
+  }
+}
+async function applyTopicsYaml(db, topicsYamlPath2) {
+  if (!existsSync8(topicsYamlPath2)) return;
+  let file;
+  try {
+    file = await loadTopicsFile(topicsYamlPath2);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`almanac: ${message}
+`);
+    return;
+  }
+  const upsertTopic = db.prepare(
+    `INSERT INTO topics (slug, title, description) VALUES (?, ?, ?)
+     ON CONFLICT(slug) DO UPDATE SET
+       title = excluded.title,
+       description = excluded.description`
+  );
+  const clearParents = db.prepare(
+    "DELETE FROM topic_parents WHERE child_slug = ?"
+  );
+  const insertParent = db.prepare(
+    "INSERT OR IGNORE INTO topic_parents (child_slug, parent_slug) VALUES (?, ?)"
+  );
+  const declared = /* @__PURE__ */ new Set();
+  for (const t of file.topics) declared.add(t.slug);
+  const adHoc = db.prepare(
+    "SELECT DISTINCT topic_slug FROM page_topics"
+  ).all();
+  for (const r of adHoc) declared.add(r.topic_slug);
+  const apply = db.transaction(() => {
+    for (const t of file.topics) {
+      upsertTopic.run(t.slug, t.title, t.description);
+      clearParents.run(t.slug);
+      for (const parent of t.parents) {
+        if (parent === t.slug) continue;
+        insertParent.run(t.slug, parent);
+      }
+    }
+    const existing = db.prepare("SELECT slug FROM topics").all();
+    const deleteTopic = db.prepare("DELETE FROM topics WHERE slug = ?");
+    const deleteEdgesByChild = db.prepare(
+      "DELETE FROM topic_parents WHERE child_slug = ?"
+    );
+    const deleteEdgesByParent = db.prepare(
+      "DELETE FROM topic_parents WHERE parent_slug = ?"
+    );
+    for (const r of existing) {
+      if (declared.has(r.slug)) continue;
+      deleteEdgesByChild.run(r.slug);
+      deleteEdgesByParent.run(r.slug);
+      deleteTopic.run(r.slug);
+    }
+  });
+  apply();
+}
+
+// src/indexer/resolveWiki.ts
+import { existsSync as existsSync9 } from "fs";
+import { join as join7 } from "path";
+async function resolveWikiRoot(params) {
+  if (params.wiki !== void 0) {
+    const entry = await findEntry({ name: params.wiki });
+    if (entry === null) {
+      throw new Error(`no registered wiki named "${params.wiki}"`);
+    }
+    if (!existsSync9(join7(entry.path, ".almanac"))) {
+      throw new Error(
+        `wiki "${params.wiki}" path is unreachable (${entry.path})`
+      );
+    }
+    return entry.path;
+  }
+  const nearest = findNearestAlmanacDir(params.cwd);
+  if (nearest === null) {
+    throw new Error(
+      "no .almanac/ found in this directory or any parent; run `almanac init` first"
+    );
+  }
+  return nearest;
+}
+
+// src/topics/dag.ts
+var DAG_DEPTH_CAP = 32;
+function ancestorsInFile(file, slug) {
+  const parentsOf = /* @__PURE__ */ new Map();
+  for (const t of file.topics) {
+    parentsOf.set(t.slug, t.parents);
+  }
+  const ancestors = /* @__PURE__ */ new Set();
+  let frontier = parentsOf.get(slug) ?? [];
+  let depth = 0;
+  while (frontier.length > 0 && depth < DAG_DEPTH_CAP) {
+    const next = [];
+    for (const node of frontier) {
+      if (ancestors.has(node)) continue;
+      ancestors.add(node);
+      const ps = parentsOf.get(node);
+      if (ps !== void 0) next.push(...ps);
+    }
+    frontier = next;
+    depth += 1;
+  }
+  return ancestors;
+}
+function descendantsInDb(db, slug) {
+  const rows = db.prepare(
+    `WITH RECURSIVE desc(slug, depth) AS (
+         SELECT child_slug, 1 FROM topic_parents WHERE parent_slug = ?
+         UNION
+         SELECT tp.child_slug, d.depth + 1
+         FROM topic_parents tp
+         JOIN desc d ON tp.parent_slug = d.slug
+         WHERE d.depth < ?
+       )
+       SELECT DISTINCT slug FROM desc ORDER BY slug`
+  ).all(slug, DAG_DEPTH_CAP).map((r) => r.slug);
+  return rows;
+}
+function subtreeInDb(db, slug) {
+  return [slug, ...descendantsInDb(db, slug)];
+}
+
+// src/commands/health.ts
+var DEFAULT_STALE_SECONDS = 90 * 24 * 60 * 60;
+async function runHealth(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  await ensureFreshIndex({ repoRoot });
+  const almanacDir = join8(repoRoot, ".almanac");
+  const pagesDir = join8(almanacDir, "pages");
+  const db = openIndex(join8(almanacDir, "index.db"));
+  try {
+    const staleSeconds = options.stale !== void 0 ? parseDuration(options.stale) : DEFAULT_STALE_SECONDS;
+    const scope = resolveScope(db, options);
+    const report = {
+      orphans: findOrphans(db, scope),
+      stale: findStale(db, scope, staleSeconds),
+      dead_refs: await findDeadRefs(db, scope, repoRoot),
+      broken_links: findBrokenLinks(db, scope),
+      broken_xwiki: await findBrokenXwiki(db, scope),
+      empty_topics: findEmptyTopics(db, scope),
+      empty_pages: await findEmptyPages(db, scope, pagesDir),
+      slug_collisions: await findSlugCollisions(pagesDir)
+    };
+    if (options.json === true) {
+      return {
+        stdout: `${JSON.stringify(report, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    return {
+      stdout: formatReport(report),
+      stderr: "",
+      exitCode: 0
+    };
+  } finally {
+    db.close();
+  }
+}
+function resolveScope(db, options) {
+  let pages = null;
+  let topics = null;
+  if (options.topic !== void 0) {
+    const rootSlug = toKebabCase(options.topic);
+    if (rootSlug.length > 0) {
+      const subtree = subtreeInDb(db, rootSlug);
+      topics = new Set(subtree);
+      const placeholders = subtree.map(() => "?").join(", ");
+      const rows = db.prepare(
+        `SELECT DISTINCT page_slug FROM page_topics
+           WHERE topic_slug IN (${placeholders})`
+      ).all(...subtree);
+      pages = new Set(rows.map((r) => r.page_slug));
+    }
+  }
+  if (options.stdin === true && options.stdinInput !== void 0) {
+    const stdinPages = /* @__PURE__ */ new Set();
+    for (const line of options.stdinInput.split(/\r?\n/)) {
+      const s = line.trim();
+      if (s.length > 0) stdinPages.add(s);
+    }
+    if (pages === null) pages = stdinPages;
+    else {
+      const out = /* @__PURE__ */ new Set();
+      for (const s of stdinPages) if (pages.has(s)) out.add(s);
+      pages = out;
+    }
+  }
+  return { pages, topics };
+}
+function inPageScope(scope, slug) {
+  if (scope.pages === null) return true;
+  return scope.pages.has(slug);
+}
+function findOrphans(db, scope) {
+  const rows = db.prepare(
+    `SELECT p.slug FROM pages p
+       WHERE p.archived_at IS NULL
+         AND NOT EXISTS (
+           SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug
+         )
+       ORDER BY p.slug`
+  ).all();
+  return rows.filter((r) => inPageScope(scope, r.slug));
+}
+function findStale(db, scope, staleSeconds) {
+  const now = Math.floor(Date.now() / 1e3);
+  const threshold = now - staleSeconds;
+  const rows = db.prepare(
+    `SELECT slug, updated_at FROM pages
+       WHERE archived_at IS NULL AND updated_at < ?
+       ORDER BY updated_at ASC`
+  ).all(threshold);
+  return rows.filter((r) => inPageScope(scope, r.slug)).map((r) => ({
+    slug: r.slug,
+    days_since_update: Math.floor((now - r.updated_at) / (60 * 60 * 24))
+  }));
+}
+async function findDeadRefs(db, scope, repoRoot) {
+  const rows = db.prepare(
+    `SELECT p.slug, r.path, r.original_path, r.is_dir
+       FROM file_refs r
+       JOIN pages p ON p.slug = r.page_slug
+       WHERE p.archived_at IS NULL
+       ORDER BY p.slug, r.path`
+  ).all();
+  const out = [];
+  for (const r of rows) {
+    if (!inPageScope(scope, r.slug)) continue;
+    const abs = join8(repoRoot, r.original_path);
+    if (!existsSync10(abs)) {
+      out.push({ slug: r.slug, path: r.original_path });
+    }
+  }
+  return out;
+}
+function findBrokenLinks(db, scope) {
+  const rows = db.prepare(
+    `SELECT w.source_slug, w.target_slug
+       FROM wikilinks w
+       JOIN pages src ON src.slug = w.source_slug
+       LEFT JOIN pages tgt ON tgt.slug = w.target_slug
+       WHERE tgt.slug IS NULL AND src.archived_at IS NULL
+       ORDER BY w.source_slug, w.target_slug`
+  ).all();
+  return rows.filter((r) => inPageScope(scope, r.source_slug));
+}
+async function findBrokenXwiki(db, scope) {
+  const rows = db.prepare(
+    // Same archived-source filter as `findBrokenLinks`. Retired pages
+    // shouldn't spam the report with links to wikis that may have
+    // been intentionally retired too.
+    `SELECT x.source_slug, x.target_wiki, x.target_slug
+       FROM cross_wiki_links x
+       JOIN pages src ON src.slug = x.source_slug
+       WHERE src.archived_at IS NULL
+       ORDER BY x.source_slug, x.target_wiki, x.target_slug`
+  ).all();
+  const out = [];
+  const reachableCache = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    if (!inPageScope(scope, r.source_slug)) continue;
+    let ok = reachableCache.get(r.target_wiki);
+    if (ok === void 0) {
+      const entry = await findEntry({ name: r.target_wiki });
+      ok = entry !== null && existsSync10(join8(entry.path, ".almanac"));
+      reachableCache.set(r.target_wiki, ok);
+    }
+    if (!ok) {
+      out.push({
+        source_slug: r.source_slug,
+        target_wiki: r.target_wiki,
+        target_slug: r.target_slug
+      });
+    }
+  }
+  return out;
+}
+function findEmptyTopics(db, scope) {
+  const rows = db.prepare(
+    `SELECT t.slug FROM topics t
+       WHERE NOT EXISTS (
+         SELECT 1 FROM page_topics pt WHERE pt.topic_slug = t.slug
+       )
+       ORDER BY t.slug`
+  ).all();
+  if (scope.topics === null) return rows;
+  return rows.filter((r) => scope.topics.has(r.slug));
+}
+async function findEmptyPages(db, scope, pagesDir) {
+  const rows = db.prepare(
+    `SELECT slug, file_path FROM pages
+       WHERE archived_at IS NULL
+       ORDER BY slug`
+  ).all();
+  const out = [];
+  for (const r of rows) {
+    if (!inPageScope(scope, r.slug)) continue;
+    let raw;
+    try {
+      raw = await readFile8(r.file_path, "utf8");
+    } catch {
+      continue;
+    }
+    const m = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+    const body = m !== null ? m[1] ?? "" : raw;
+    void pagesDir;
+    const hasSubstance = body.split(/\r?\n/).some((l) => {
+      const t = l.trim();
+      if (t.length === 0) return false;
+      if (t.startsWith("#")) return false;
+      return true;
+    });
+    if (!hasSubstance) {
+      out.push({ slug: r.slug });
+    }
+  }
+  return out;
+}
+async function findSlugCollisions(pagesDir) {
+  if (!existsSync10(pagesDir)) return [];
+  const files = await fg2("**/*.md", {
+    cwd: pagesDir,
+    absolute: false,
+    onlyFiles: true,
+    caseSensitiveMatch: true
+  });
+  const bySlug = /* @__PURE__ */ new Map();
+  for (const rel of files) {
+    const slug = toKebabCase(basename4(rel, ".md"));
+    if (slug.length === 0) continue;
+    const list = bySlug.get(slug) ?? [];
+    list.push(rel);
+    bySlug.set(slug, list);
+  }
+  const out = [];
+  for (const [slug, paths] of bySlug.entries()) {
+    if (paths.length > 1) {
+      out.push({ slug, paths: paths.sort() });
+    }
+  }
+  out.sort((a, b) => a.slug.localeCompare(b.slug));
+  return out;
+}
+function formatReport(r) {
+  const sections = [];
+  sections.push(
+    section(
+      "orphans",
+      r.orphans.length,
+      r.orphans.map((o) => `  ${o.slug}`)
+    )
+  );
+  sections.push(
+    section(
+      "stale",
+      r.stale.length,
+      r.stale.map((s) => `  ${s.slug}     (${s.days_since_update} days)`)
+    )
+  );
+  sections.push(
+    section(
+      "dead-refs",
+      r.dead_refs.length,
+      r.dead_refs.map((d) => `  ${d.slug}  references ${d.path} (missing)`)
+    )
+  );
+  sections.push(
+    section(
+      "broken-links",
+      r.broken_links.length,
+      r.broken_links.map(
+        (b) => `  ${b.source_slug} \u2192 ${b.target_slug} (target does not exist)`
+      )
+    )
+  );
+  sections.push(
+    section(
+      "broken-xwiki",
+      r.broken_xwiki.length,
+      r.broken_xwiki.map(
+        (b) => `  ${b.source_slug} \u2192 ${b.target_wiki}:${b.target_slug} (wiki unregistered or unreachable)`
+      )
+    )
+  );
+  sections.push(
+    section(
+      "empty-topics",
+      r.empty_topics.length,
+      r.empty_topics.map((e) => `  ${e.slug}`)
+    )
+  );
+  sections.push(
+    section(
+      "empty-pages",
+      r.empty_pages.length,
+      r.empty_pages.map((e) => `  ${e.slug}`)
+    )
+  );
+  sections.push(
+    section(
+      "slug-collisions",
+      r.slug_collisions.length,
+      r.slug_collisions.map((c) => `  ${c.slug}: ${c.paths.join(", ")}`)
+    )
+  );
+  return `${sections.join("\n\n")}
+`;
+}
+function section(label, count, lines) {
+  if (count === 0) return `${label} (0): (ok)`;
+  return `${label} (${count}):
+${lines.join("\n")}`;
+}
+
+// src/commands/info.ts
+import { join as join9 } from "path";
+async function runInfo(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join9(repoRoot, ".almanac", "index.db");
+  const db = openIndex(dbPath);
+  try {
+    const slugs = collectSlugs(options);
+    if (slugs.length === 0) {
+      return {
+        stdout: "",
+        stderr: "almanac: info requires a slug (or --stdin)\n",
+        exitCode: 1
+      };
+    }
+    const records = [];
+    const missing = [];
+    for (const slug of slugs) {
+      const rec = fetchInfo(db, slug);
+      if (rec === null) {
+        missing.push(slug);
+        continue;
+      }
+      records.push(rec);
+    }
+    const bulk = options.stdin === true;
+    const jsonOut = options.json === true || bulk;
+    let stdout;
+    if (jsonOut) {
+      if (bulk) {
+        stdout = `${JSON.stringify(records, null, 2)}
+`;
+      } else {
+        const only = records[0] ?? null;
+        stdout = `${JSON.stringify(only, null, 2)}
+`;
+      }
+    } else {
+      stdout = records.map(formatHumanReadable).join("\n");
+    }
+    const stderr = missing.map((s) => `almanac: no such page "${s}"
+`).join("");
+    return {
+      stdout,
+      stderr,
+      exitCode: missing.length > 0 ? 1 : 0
+    };
+  } finally {
+    db.close();
+  }
+}
+function fetchInfo(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(
+    // Display the author's casing (`original_path`), not the
+    // lowercased lookup form. The lowercased `path` column is the
+    // query key for `--mentions`; it's not a user-facing string.
+    "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);
+  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
+  };
+}
+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 [];
+}
+function formatHumanReadable(rec) {
+  const lines = [];
+  lines.push(`slug:          ${rec.slug}`);
+  lines.push(`title:         ${rec.title ?? "\u2014"}`);
+  lines.push(`file:          ${rec.file_path}`);
+  lines.push(`updated_at:    ${new Date(rec.updated_at * 1e3).toISOString()}`);
+  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(", ")}`);
+  }
+  lines.push(`topics:        ${rec.topics.length > 0 ? rec.topics.join(", ") : "\u2014"}`);
+  lines.push("file_refs:");
+  if (rec.file_refs.length === 0) {
+    lines.push("  \u2014");
+  } else {
+    for (const r of rec.file_refs) {
+      lines.push(`  ${r.path}${r.is_dir ? "  (dir)" : ""}`);
+    }
+  }
+  lines.push("wikilinks_out:");
+  if (rec.wikilinks_out.length === 0) lines.push("  \u2014");
+  else for (const t of rec.wikilinks_out) lines.push(`  ${t}`);
+  lines.push("wikilinks_in:");
+  if (rec.wikilinks_in.length === 0) lines.push("  \u2014");
+  else for (const s of rec.wikilinks_in) lines.push(`  ${s}`);
+  if (rec.cross_wiki_links.length > 0) {
+    lines.push("cross_wiki_links:");
+    for (const x of rec.cross_wiki_links) {
+      lines.push(`  ${x.wiki}:${x.target}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/list.ts
+import { existsSync as existsSync11 } 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 existsSync11(entry.path);
+}
+function formatPretty(entries) {
+  if (entries.length === 0) {
+    return "no wikis registered. run `almanac init` in a repo to create one.\n";
+  }
+  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(`${name}  ${desc}`);
+    lines.push(`${" ".repeat(nameWidth)}  ${entry.path}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/path.ts
+import { join as join10 } from "path";
+async function runPath(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join10(repoRoot, ".almanac", "index.db");
+  const db = openIndex(dbPath);
+  try {
+    const slugs = collectSlugs2(options);
+    if (slugs.length === 0) {
+      return {
+        stdout: "",
+        stderr: "almanac: path requires a slug (or --stdin)\n",
+        exitCode: 1
+      };
+    }
+    const stmt = db.prepare(
+      "SELECT file_path FROM pages WHERE slug = ?"
+    );
+    const resolved = [];
+    const missing = [];
+    for (const slug of slugs) {
+      const row = stmt.get(slug);
+      if (row === void 0) {
+        missing.push(slug);
+        continue;
+      }
+      resolved.push(row.file_path);
+    }
+    const stdout = resolved.length > 0 ? `${resolved.join("\n")}
+` : "";
+    const stderr = missing.map((s) => `almanac: no such page "${s}"
+`).join("");
+    return {
+      stdout,
+      stderr,
+      exitCode: missing.length > 0 ? 1 : 0
+    };
+  } finally {
+    db.close();
+  }
+}
+function collectSlugs2(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/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/commands/search.ts
+import { join as join11 } from "path";
+async function runSearch(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join11(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) => r.slug).join("\n")}
+`;
+}
+function buildStderr(rows, options) {
+  if (options.json === true) return "";
+  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 readFile9 } from "fs/promises";
+import { join as join12 } from "path";
+async function runShow(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join12(repoRoot, ".almanac", "index.db");
+  const db = openIndex(dbPath);
+  try {
+    const slugs = collectSlugs3(options);
+    if (slugs.length === 0) {
+      return {
+        stdout: "",
+        stderr: "almanac: show requires a slug (or --stdin)\n",
+        exitCode: 1
+      };
+    }
+    const stmt = db.prepare(
+      "SELECT file_path FROM pages WHERE slug = ?"
+    );
+    const records = [];
+    const missing = [];
+    for (const slug of slugs) {
+      const row = stmt.get(slug);
+      if (row === void 0) {
+        missing.push(slug);
+        continue;
+      }
+      try {
+        records.push({ slug, content: await readFile9(row.file_path, "utf8") });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        missing.push(`${slug} (${message})`);
+      }
+    }
+    const bulk = options.stdin === true;
+    let stdout;
+    if (bulk) {
+      stdout = records.map((r) => JSON.stringify(r)).join("\n");
+      if (stdout.length > 0) stdout += "\n";
+    } else {
+      stdout = records.map((r) => r.content).join("");
+    }
+    const stderr = missing.map((s) => `almanac: no such page "${s}"
+`).join("");
+    return {
+      stdout,
+      stderr,
+      exitCode: missing.length > 0 ? 1 : 0
+    };
+  } finally {
+    db.close();
+  }
+}
+function collectSlugs3(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/topics/frontmatterRewrite.ts
+import { readFile as readFile10, rename as rename4, writeFile as writeFile5 } from "fs/promises";
+import yaml3 from "js-yaml";
+async function rewritePageTopics(filePath, transform) {
+  const raw = await readFile10(filePath, "utf8");
+  const { before, after, output, changed } = applyTopicsTransform(
+    raw,
+    transform
+  );
+  if (changed) {
+    const tmp = `${filePath}.tmp`;
+    await writeFile5(tmp, output, "utf8");
+    await rename4(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 = yaml3.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 yaml3.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 as join13 } from "path";
+function topicsYamlPath(repoRoot) {
+  return join13(repoRoot, ".almanac", "topics.yaml");
+}
+function indexDbPath(repoRoot) {
+  return join13(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.ts
+import { readFile as readFile11 } from "fs/promises";
+import { join as join14 } from "path";
+import fg3 from "fast-glob";
+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 `${slug}  ${count}`;
+    });
+    return { stdout: `${lines.join("\n")}
+`, stderr: "", exitCode: 0 };
+  } finally {
+    db.close();
+  }
+}
+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();
+  }
+}
+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(`slug:         ${r.slug}`);
+  lines.push(`title:        ${r.title ?? titleCase(r.slug)}`);
+  lines.push(`description:  ${r.description ?? "\u2014"}`);
+  lines.push(
+    `parents:      ${r.parents.length > 0 ? r.parents.join(", ") : "\u2014"}`
+  );
+  lines.push(
+    `children:     ${r.children.length > 0 ? r.children.join(", ") : "\u2014"}`
+  );
+  const pagesLabel = r.descendants_used === true ? "pages (incl. descendants)" : "pages";
+  lines.push(`${pagesLabel}:`);
+  if (r.pages.length === 0) {
+    lines.push("  \u2014");
+  } else {
+    for (const p of r.pages) lines.push(`  ${p}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+async function runTopicsCreate(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  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);
+  await ensureFreshIndex({ repoRoot });
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const db = openIndex(indexDbPath(repoRoot));
+  try {
+    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 });
+    return {
+      stdout: existing === null ? `created topic "${slug}"
+` : `updated topic "${slug}"
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  } finally {
+    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;
+}
+async function runTopicsLink(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 };
+  }
+  if (child === parent) {
+    return {
+      stdout: "",
+      stderr: `almanac: topic cannot be its own parent
+`,
+      exitCode: 1
+    };
+  }
+  await ensureFreshIndex({ repoRoot });
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const db = openIndex(indexDbPath(repoRoot));
+  try {
+    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 });
+    return {
+      stdout: `linked ${child} \u2192 ${parent}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  } finally {
+    db.close();
+  }
+}
+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
+  };
+}
+async function runTopicsRename(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  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
+    };
+  }
+  await ensureFreshIndex({ repoRoot });
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const db = openIndex(indexDbPath(repoRoot));
+  let pagesUpdated;
+  try {
+    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(
+      repoRoot,
+      (topics) => topics.map((t) => t === oldSlug ? newSlug : t)
+    );
+  } finally {
+    db.close();
+  }
+  await runIndexer({ repoRoot });
+  return {
+    stdout: `renamed ${oldSlug} \u2192 ${newSlug} (${pagesUpdated} page${pagesUpdated === 1 ? "" : "s"} updated)
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function runTopicsDelete(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  const slug = toKebabCase(options.slug);
+  if (slug.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  await ensureFreshIndex({ repoRoot });
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const db = openIndex(indexDbPath(repoRoot));
+  let pagesUpdated;
+  try {
+    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(
+      repoRoot,
+      (topics) => topics.filter((t) => t !== slug)
+    );
+  } finally {
+    db.close();
+  }
+  await runIndexer({ repoRoot });
+  return {
+    stdout: `deleted topic "${slug}" (${pagesUpdated} page${pagesUpdated === 1 ? "" : "s"} untagged)
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function runTopicsDescribe(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  const slug = toKebabCase(options.slug);
+  if (slug.length === 0) {
+    return { stdout: "", stderr: `almanac: empty topic slug
+`, exitCode: 1 };
+  }
+  await ensureFreshIndex({ repoRoot });
+  const yamlPath = topicsYamlPath(repoRoot);
+  const file = await loadTopicsFile(yamlPath);
+  const db = openIndex(indexDbPath(repoRoot));
+  try {
+    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 {
+    db.close();
+  }
+  await runIndexer({ repoRoot });
+  return {
+    stdout: `described ${slug}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function rewriteTopicOnPages(repoRoot, transform) {
+  const pagesDir = join14(repoRoot, ".almanac", "pages");
+  const files = await fg3("**/*.md", {
+    cwd: pagesDir,
+    absolute: true,
+    onlyFiles: true
+  });
+  let changed = 0;
+  for (const filePath of files) {
+    const raw = await readFile11(filePath, "utf8");
+    const applied = applyTopicsTransform(raw, transform);
+    if (!applied.changed) continue;
+    await rewritePageTopics(filePath, transform);
+    changed += 1;
+  }
+  return changed;
+}
+
+// src/registry/autoregister.ts
+import { existsSync as existsSync12 } from "fs";
+import { basename as basename5 } from "path";
+async function autoRegisterIfNeeded(cwd) {
+  try {
+    const repoRoot = findNearestAlmanacDir(cwd);
+    if (repoRoot === null) return null;
+    if (!existsSync12(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(basename5(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.ts
+async function run(argv) {
+  const program = new Command();
+  const invoked = argv[1] !== void 0 ? basename6(argv[1]) : "almanac";
+  const programName = invoked === "codealmanac" ? "codealmanac" : "almanac";
+  program.name(programName).description(
+    "codealmanac \u2014 a living wiki for codebases, maintained by AI agents"
+  ).version("0.1.0", "-v, --version", "print version");
+  program.command("init").description("scaffold .almanac/ in the current directory and register it").option("--name <name>", "wiki name (defaults to the directory name)").option("--description <text>", "one-line description of this wiki").action(async (opts) => {
+    const result = await initWiki({
+      cwd: process.cwd(),
+      name: opts.name,
+      description: opts.description
+    });
+    const verb = result.created ? "initialized" : "updated";
+    process.stdout.write(
+      `${verb} wiki "${result.entry.name}" at ${result.almanacDir}
+`
+    );
+  });
+  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;
+    }
+  });
+  program.command("search [query]").description("query pages by text, topic, file mentions, or freshness").option(
+    "--topic <name...>",
+    "filter by topic (repeat for intersection)",
+    collectOption,
+    []
+  ).option(
+    "--mentions <path>",
+    "pages referencing this file or folder (trailing / = folder)"
+  ).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
+      });
+      if (result.stderr.length > 0) process.stderr.write(result.stderr);
+      process.stdout.write(result.stdout);
+      if (result.exitCode !== 0) process.exitCode = result.exitCode;
+    }
+  );
+  program.command("show [slug]").description("print the markdown content of a page").option("--stdin", "read slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").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
+      });
+      if (result.stderr.length > 0) process.stderr.write(result.stderr);
+      process.stdout.write(result.stdout);
+      if (result.exitCode !== 0) process.exitCode = result.exitCode;
+    }
+  );
+  program.command("path [slug]").description("resolve a slug to its absolute file path").option("--stdin", "read slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").action(
+    async (slug, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runPath({
+        cwd: process.cwd(),
+        slug,
+        stdin: opts.stdin,
+        stdinInput: opts.stdin === true ? await readStdin() : void 0,
+        wiki: opts.wiki
+      });
+      if (result.stderr.length > 0) process.stderr.write(result.stderr);
+      process.stdout.write(result.stdout);
+      if (result.exitCode !== 0) process.exitCode = result.exitCode;
+    }
+  );
+  program.command("info [slug]").description("print metadata for a page (topics, refs, links, lineage)").option("--stdin", "read slugs from stdin (one per line)").option("--json", "emit structured JSON").option("--wiki <name>", "target a specific registered wiki").action(
+    async (slug, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runInfo({
+        cwd: process.cwd(),
+        slug,
+        stdin: opts.stdin,
+        stdinInput: opts.stdin === true ? await readStdin() : void 0,
+        json: opts.json,
+        wiki: opts.wiki
+      });
+      if (result.stderr.length > 0) process.stderr.write(result.stderr);
+      process.stdout.write(result.stdout);
+      if (result.exitCode !== 0) process.exitCode = result.exitCode;
+    }
+  );
+  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;
+  });
+  const topics = program.command("topics").description("manage the topic DAG (list, create, link, rename, delete)");
+  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);
+    }
+  );
+  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);
+    }
+  );
+  program.command("bootstrap").description(
+    "spawn an agent to scan the repo and create initial wiki stubs (requires ANTHROPIC_API_KEY)"
+  ).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(
+    "capture knowledge from a Claude Code session transcript (auto-resolves the most recent session for this repo when no path is given; requires ANTHROPIC_API_KEY)"
+  ).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(
+    "install, uninstall, or inspect the SessionEnd hook in ~/.claude/settings.json"
+  );
+  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("health").description("report wiki problems (orphans, dead refs, broken links, \u2026)").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);
+    }
+  );
+  await program.parseAsync(argv);
+}
+function emit(result) {
+  if (result.stderr.length > 0) process.stderr.write(result.stderr);
+  if (result.stdout.length > 0) process.stdout.write(result.stdout);
+  if (result.exitCode !== 0) process.exitCode = result.exitCode;
+}
+function collectOption(value, previous) {
+  return [...previous, value];
+}
+function parsePositiveInt(value) {
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new Error(`invalid --limit "${value}" (expected a non-negative integer)`);
+  }
+  return n;
+}
+async function readStdin() {
+  if (process.stdin.isTTY === true) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// bin/codealmanac.ts
+run(process.argv).catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`almanac: ${message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=codealmanac.js.map