codealmanac 0.1.1 → 0.1.3

package/dist/codealmanac.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { createRequire as createRequire4 } from "module";
 import { basename as basename6 } from "path";
 import { Command } from "commander";
 
@@ -225,7 +226,7 @@ function findNearestAlmanacDir(startDir) {
   }
 }
 
-// src/commands/init.ts
+// 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";
@@ -239,10 +240,10 @@ function toKebabCase(input) {
 import { mkdir, readFile as readFile2, rename, writeFile } from "fs/promises";
 import { dirname as dirname3 } from "path";
 async function readRegistry() {
-  const path3 = getRegistryPath();
+  const path6 = getRegistryPath();
   let raw;
   try {
-    raw = await readFile2(path3, "utf8");
+    raw = await readFile2(path6, "utf8");
   } catch (err) {
     if (isNodeError(err) && err.code === "ENOENT") {
       return [];
@@ -258,10 +259,10 @@ async function readRegistry() {
     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}`);
+    throw new Error(`registry at ${path6} is not valid JSON: ${message}`);
   }
   if (!Array.isArray(parsed)) {
-    throw new Error(`registry at ${path3} must be a JSON array`);
+    throw new Error(`registry at ${path6} must be a JSON array`);
   }
   return parsed.map((item, idx) => {
     if (typeof item !== "object" || item === null) {
@@ -269,29 +270,29 @@ async function readRegistry() {
     }
     const e = item;
     const name = typeof e.name === "string" ? e.name : "";
-    const path4 = typeof e.path === "string" ? e.path : "";
+    const path7 = 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) {
+    if (path7.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,
+      path: path7,
       registered_at: typeof e.registered_at === "string" ? e.registered_at : ""
     };
   });
 }
 async function writeRegistry(entries) {
-  const path3 = getRegistryPath();
-  await mkdir(dirname3(path3), { recursive: true });
+  const path6 = getRegistryPath();
+  await mkdir(dirname3(path6), { recursive: true });
   const body = `${JSON.stringify(entries, null, 2)}
 `;
-  const tmpPath = `${path3}.tmp`;
+  const tmpPath = `${path6}.tmp`;
   await writeFile(tmpPath, body, "utf8");
-  await rename(tmpPath, path3);
+  await rename(tmpPath, path6);
 }
 function pathsEqual(a, b) {
   if (process.platform === "darwin" || process.platform === "win32") {
@@ -335,7 +336,7 @@ function isNodeError(err) {
   return err instanceof Error && "code" in err;
 }
 
-// src/commands/init.ts
+// src/commands/_init.ts
 async function initWiki(options) {
   const repoRoot = findNearestAlmanacDir(options.cwd) ?? options.cwd;
   const almanacDir = getRepoAlmanacDir(repoRoot);
@@ -365,15 +366,15 @@ async function initWiki(options) {
   return { entry, almanacDir, created: !alreadyExisted };
 }
 async function ensureGitignoreHasIndexDb(cwd) {
-  const path3 = join3(cwd, ".gitignore");
+  const path6 = 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");
+  if (existsSync3(path6)) {
+    existing = await readFile3(path6, "utf8");
   }
   const lines = existing.split(/\r?\n/).map((l) => l.trim());
   const missing = targets.filter((t) => !lines.includes(t));
@@ -383,7 +384,7 @@ async function ensureGitignoreHasIndexDb(cwd) {
 ${missing.join("\n")}
 `;
   const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-  await writeFile2(path3, `${existing}${sep}${block}`, "utf8");
+  await writeFile2(path6, `${existing}${sep}${block}`, "utf8");
 }
 function starterReadme() {
   return `# Wiki
@@ -807,7 +808,7 @@ async function runCapture(options) {
   if (repoRoot === null) {
     return {
       stdout: "",
-      stderr: "almanac: no .almanac/ found in this directory or any parent. Run 'almanac init' or 'almanac bootstrap' first.\n",
+      stderr: "almanac: no .almanac/ found in this directory or any parent. Run 'almanac bootstrap' first.\n",
       exitCode: 1
     };
   }
@@ -986,8 +987,8 @@ async function filterTranscriptsByCwd(transcripts, repoRoot) {
   }
   return hits;
 }
-async function readHead(path3, bytes) {
-  const content = await readFile4(path3, "utf8");
+async function readHead(path6, bytes) {
+  const content = await readFile4(path6, "utf8");
   return content.length > bytes ? content.slice(0, bytes) : content;
 }
 async function snapshotPages(pagesDir) {
@@ -1059,201 +1060,97 @@ function closeStream2(stream) {
   });
 }
 
-// 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 };
+// src/commands/doctor.ts
+import { existsSync as existsSync12, readdirSync, statSync as statSync3 } from "fs";
+import { readFile as readFile10 } from "fs/promises";
+import { createRequire as createRequire3 } from "module";
+import { homedir as homedir5 } from "os";
+import path4 from "path";
+
+// 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");
   }
-  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 };
+  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}`);
   }
-  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);
+  db.exec(SCHEMA_DDL);
+  return db;
 }
 
 // src/commands/health.ts
-import { existsSync as existsSync10 } from "fs";
-import { readFile as readFile8 } from "fs/promises";
+import { existsSync as existsSync9 } from "fs";
+import { readFile as readFile7 } from "fs/promises";
 import { basename as basename4, join as join8 } from "path";
 import fg2 from "fast-glob";
 
@@ -1284,1123 +1181,1857 @@ function parseDuration(input) {
 
 // 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 { existsSync as existsSync7, statSync as statSync2 } from "fs";
+import { readFile as readFile6, 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 { existsSync as existsSync6 } from "fs";
+import { mkdir as mkdir3, readFile as readFile5, rename as rename2, writeFile as writeFile3 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 import yaml2 from "js-yaml";
-async function loadTopicsFile(path3) {
-  if (!existsSync7(path3)) {
+async function loadTopicsFile(path6) {
+  if (!existsSync6(path6)) {
     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: [] };
+    raw = await readFile5(path6, "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 ${path6} 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 ${path6} 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 ${path6} \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(path6, 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 = `${path6}.tmp`;
+  const parent = dirname4(path6);
+  if (!existsSync6(parent)) {
+    await mkdir3(parent, { recursive: true });
+  }
+  await writeFile3(tmpPath, content, "utf8");
+  await rename2(tmpPath, path6);
+}
+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/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 path6 = normalizePath(body, isDir);
+    const originalPath = normalizePathPreservingCase(body, isDir);
+    if (path6.length === 0) return null;
+    return isDir ? { kind: "folder", path: path6, originalPath } : { kind: "file", path: path6, 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 (!existsSync7(pagesDir)) {
+    const db = openIndex(dbPath);
+    db.close();
+    return emptyResult();
+  }
+  if (!existsSync7(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();
   }
-  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 now = /* @__PURE__ */ new Date();
+    await utimes(dbPath, now, now);
+  } catch {
   }
-  const topics = [];
-  for (const item of rawTopics) {
-    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+  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;
     }
-    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);
-          }
-        }
+    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 readFile6(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;
     }
-    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 });
+    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
+    });
   }
-  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;
+  const toDelete = [];
+  for (const slug of existingBySlug.keys()) {
+    if (!seenSlugs.has(slug)) toDelete.push(slug);
   }
-  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: []
+  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 path6 = normalizePath(raw, isDir);
+        const originalPath = normalizePathPreservingCase(raw, isDir);
+        if (path6.length === 0) continue;
+        insertFileRef.run(p.slug, path6, 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
   };
-  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 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 normalizePathPreservingCase(raw, isDir) {
-  return normalizeShape(raw, isDir);
+function hashContent(raw) {
+  return createHash2("sha256").update(raw).digest("hex");
 }
-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}/`;
+function topicsYamlNewerThan(almanacDir, dbPath) {
+  const path6 = join6(almanacDir, "topics.yaml");
+  if (!existsSync7(path6)) return false;
+  let dbMtime;
+  try {
+    dbMtime = statSync2(dbPath).mtimeMs;
+  } catch {
+    return true;
+  }
+  try {
+    const st = statSync2(path6);
+    return st.mtimeMs > dbMtime;
+  } catch {
+    return false;
   }
-  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");
+async function applyTopicsYaml(db, topicsYamlPath2) {
+  if (!existsSync7(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;
   }
-  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 {
+  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);
+      }
     }
-    db.pragma(`user_version = ${SCHEMA_VERSION}`);
-  }
-  db.exec(SCHEMA_DDL);
-  return db;
+    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/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 };
+// src/indexer/resolveWiki.ts
+import { existsSync as existsSync8 } 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 (!existsSync8(join7(entry.path, ".almanac"))) {
+      throw new Error(
+        `wiki "${params.wiki}" path is unreachable (${entry.path})`
+      );
+    }
+    return entry.path;
   }
-  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);
+  const nearest = findNearestAlmanacDir(params.cwd);
+  if (nearest === null) {
+    throw new Error(
+      "no .almanac/ found in this directory or any parent; run `almanac bootstrap` first"
+    );
   }
-  return out;
+  return nearest;
 }
 
-// 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();
+// 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);
   }
-  if (!existsSync8(dbPath) || pagesNewerThan(pagesDir, dbPath) || topicsYamlNewerThan(almanacDir, dbPath)) {
-    return runIndexer(ctx);
+  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 emptyResult();
+  return ancestors;
 }
-function emptyResult() {
-  return {
-    changed: 0,
-    removed: 0,
-    total: 0,
-    pagesIndexed: 0,
-    filesSeen: 0,
-    filesSkipped: 0
-  };
+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;
 }
-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;
+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 {
-    result = await indexPagesInto(db, pagesDir);
-    await applyTopicsYaml(db, join6(almanacDir, TOPICS_YAML_FILENAME));
+    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();
   }
-  try {
-    const now = /* @__PURE__ */ new Date();
-    await utimes(dbPath, now, now);
-  } catch {
+}
+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));
+    }
   }
-  return result;
+  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 };
 }
-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;
+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 (!existsSync9(abs)) {
+      out.push({ slug: r.slug, path: r.original_path });
     }
-    if (slug !== base) {
-      process.stderr.write(
-        `almanac: warning \u2014 "${rel}" is not canonical; indexed as slug "${slug}"
-`
-      );
+  }
+  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 && existsSync9(join8(entry.path, ".almanac"));
+      reachableCache.set(r.target_wiki, ok);
     }
-    if (seenSlugs.has(slug)) {
-      process.stderr.write(
-        `almanac: warning \u2014 slug "${slug}" collides with an earlier file; skipping "${rel}"
-`
-      );
-      filesSkipped++;
-      continue;
+    if (!ok) {
+      out.push({
+        source_slug: r.source_slug,
+        target_wiki: r.target_wiki,
+        target_slug: r.target_slug
+      });
     }
-    let st;
+  }
+  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 {
-      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) {
+      raw = await readFile7(r.file_path, "utf8");
+    } catch {
       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 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;
     });
-  }
-  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);
+    if (!hasSubstance) {
+      out.push({ slug: r.slug });
     }
-  });
-  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, {
+  return out;
+}
+async function findSlugCollisions(pagesDir) {
+  if (!existsSync9(pagesDir)) return [];
+  const files = await fg2("**/*.md", {
     cwd: pagesDir,
-    absolute: true,
+    absolute: false,
     onlyFiles: true,
-    stats: true
+    caseSensitiveMatch: 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;
+  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);
   }
-  try {
-    const st = statSync2(path3);
-    return st.mtimeMs > dbMtime;
-  } catch {
-    return false;
+  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;
 }
-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`
+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)`)
+    )
   );
-  const clearParents = db.prepare(
-    "DELETE FROM topic_parents WHERE child_slug = ?"
+  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)`
+      )
+    )
   );
-  const insertParent = db.prepare(
-    "INSERT OR IGNORE INTO topic_parents (child_slug, parent_slug) VALUES (?, ?)"
+  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)`
+      )
+    )
   );
-  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();
+  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/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;
+// src/commands/setup.ts
+import { existsSync as existsSync11 } from "fs";
+import {
+  copyFile,
+  mkdir as mkdir5,
+  readFile as readFile9,
+  writeFile as writeFile5
+} from "fs/promises";
+import { createRequire as createRequire2 } from "module";
+import { homedir as homedir4 } from "os";
+import path3 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+
+// src/commands/hook.ts
+import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir4, readFile as readFile8, rename as rename3, writeFile as writeFile4 } 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 nearest = findNearestAlmanacDir(params.cwd);
-  if (nearest === null) {
-    throw new Error(
-      "no .almanac/ found in this directory or any parent; run `almanac init` first"
-    );
+  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
+    };
   }
-  return nearest;
+  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
+  };
 }
-
-// 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);
+async function runHookUninstall(options = {}) {
+  const settingsPath = resolveSettingsPath(options);
+  if (!existsSync10(settingsPath)) {
+    return {
+      stdout: `almanac: SessionEnd hook not installed (no settings file)
+`,
+      stderr: "",
+      exitCode: 0
+    };
   }
-  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);
+  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;
     }
-    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)];
+  await writeSettings(settingsPath, settings);
+  return {
+    stdout: `almanac: SessionEnd hook removed
+`,
+    stderr: "",
+    exitCode: 0
+  };
 }
-
-// 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)
+async function runHookStatus(options = {}) {
+  const script = resolveHookScriptPath(options);
+  const settingsPath = resolveSettingsPath(options);
+  if (!existsSync10(settingsPath)) {
+    return {
+      stdout: `SessionEnd hook: not installed
+settings: ${settingsPath} (does not exist)
+` + (script.ok ? `script would be: ${script.path}
+` : ""),
+      stderr: "",
+      exitCode: 0
     };
-    if (options.json === true) {
-      return {
-        stdout: `${JSON.stringify(report, null, 2)}
-`,
-        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: formatReport(report),
+      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
     };
-  } finally {
-    db.close();
   }
+  return {
+    stdout: `SessionEnd hook: installed
+script: ${ours.command}
+settings: ${settingsPath}
+`,
+    stderr: "",
+    exitCode: 0
+  };
 }
-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));
-    }
+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 };
   }
-  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;
+  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 (existsSync10(candidate)) {
+      return { ok: true, path: candidate };
     }
   }
-  return { pages, topics };
-}
-function inPageScope(scope, slug) {
-  if (scope.pages === null) return true;
-  return scope.pages.has(slug);
+  return {
+    ok: false,
+    error: `could not locate hooks/almanac-capture.sh. Tried:
+` + candidates.map((c) => `  - ${c}`).join("\n")
+  };
 }
-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));
+async function readSettings(settingsPath) {
+  if (!existsSync10(settingsPath)) return {};
+  try {
+    const raw = await readFile8(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}`);
+  }
 }
-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 writeSettings(settingsPath, settings) {
+  const dir = path2.dirname(settingsPath);
+  await mkdir4(dir, { recursive: true });
+  const tmp = `${settingsPath}.almanac-tmp-${process.pid}`;
+  const body = `${JSON.stringify(settings, null, 2)}
+`;
+  await writeFile4(tmp, body, "utf8");
+  await rename3(tmp, settingsPath);
 }
-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 });
-    }
+
+// src/commands/setup.ts
+var RST = "\x1B[0m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var WHITE_BOLD = "\x1B[1;37m";
+var BLUE = "\x1B[38;5;75m";
+var BLUE_DIM = "\x1B[38;5;69m";
+var ACCENT_BG = "\x1B[48;5;252m\x1B[38;5;16m";
+var GRADIENT = [
+  "\x1B[38;5;255m",
+  "\x1B[38;5;253m",
+  "\x1B[38;5;251m",
+  "\x1B[38;5;249m",
+  "\x1B[38;5;246m",
+  "\x1B[38;5;243m"
+];
+var LOGO_LINES = [
+  "  ___ ___  ___  ___   _   _    __  __   _   _  _   _   ___ ",
+  " / __/ _ \\|   \\| __| /_\\ | |  |  \\/  | /_\\ | \\| | /_\\ / __|",
+  "| (_| (_) | |) | _| / _ \\| |__| |\\/| |/ _ \\| .` |/ _ \\ (__ ",
+  " \\___\\___/|___/|___/_/ \\_\\____|_|  |_/_/ \\_\\_|\\_/_/ \\_\\___|",
+  "                                                           ",
+  "        a living wiki for codebases, for your agent         "
+];
+var BAR = `  ${DIM}\u2502${RST}`;
+function printBanner(out) {
+  out.write("\n");
+  for (let i = 0; i < LOGO_LINES.length; i++) {
+    const color = GRADIENT[Math.min(i, GRADIENT.length - 1)] ?? "";
+    out.write(`${color}${LOGO_LINES[i]}${RST}
+`);
   }
-  return out;
+  out.write(`
+${WHITE_BOLD}  Install the hook + agent guides${RST}
+`);
 }
-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));
+function printBadge(out) {
+  out.write(`
+   ${ACCENT_BG} codealmanac ${RST}
+
+`);
 }
-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);
+function stepDone(out, msg) {
+  out.write(`  ${BLUE}\u25C7${RST}  ${msg}
+`);
+}
+function stepActive(out, msg) {
+  out.write(`  ${BLUE}\u25C6${RST}  ${msg}
+`);
+}
+function stepSkipped(out, msg) {
+  out.write(`  ${DIM}\u25CB  ${msg}${RST}
+`);
+}
+async function runSetup(options = {}) {
+  const out = options.stdout ?? process.stdout;
+  const isTTY = options.isTTY ?? process.stdin.isTTY === true;
+  const interactive = isTTY && options.yes !== true;
+  if (options.skipHook === true && options.skipGuides === true) {
+    out.write(
+      "codealmanac: nothing to install \u2014 use --help to see what setup does\n"
+    );
+    return { stdout: "", stderr: "", exitCode: 0 };
+  }
+  printBanner(out);
+  printBadge(out);
+  const auth = await safeCheckAuth(options.spawnCli);
+  reportAuth(out, auth);
+  out.write(BAR + "\n");
+  let hookAction = "install";
+  if (options.skipHook === true) {
+    hookAction = "skip";
+  } else if (interactive) {
+    hookAction = await confirm(
+      out,
+      "Install the SessionEnd hook so capture runs at the end of every Claude Code session?",
+      true
+    );
+  }
+  let hookResultLine = "";
+  if (hookAction === "install") {
+    const res = await runHookInstall({
+      settingsPath: options.settingsPath,
+      hookScriptPath: options.hookScriptPath
+    });
+    if (res.exitCode !== 0) {
+      stepActive(out, `SessionEnd hook: ${res.stderr.trim()}`);
+      return {
+        stdout: "",
+        stderr: res.stderr,
+        exitCode: res.exitCode
+      };
     }
-    if (!ok) {
-      out.push({
-        source_slug: r.source_slug,
-        target_wiki: r.target_wiki,
-        target_slug: r.target_slug
+    hookResultLine = res.stdout.includes("already installed") ? `SessionEnd hook ${DIM}already installed${RST}` : `SessionEnd hook installed`;
+    stepDone(out, hookResultLine);
+  } else {
+    stepSkipped(out, `SessionEnd hook ${DIM}skipped${RST}`);
+  }
+  out.write(BAR + "\n");
+  let guidesAction = "install";
+  if (options.skipGuides === true) {
+    guidesAction = "skip";
+  } else if (interactive) {
+    guidesAction = await confirm(
+      out,
+      "Install the codealmanac usage guides into ~/.claude/ and import them from CLAUDE.md?",
+      true
+    );
+  }
+  let guidesSummary;
+  if (guidesAction === "install") {
+    try {
+      const summary = await installGuides({
+        claudeDir: options.claudeDir ?? path3.join(homedir4(), ".claude"),
+        guidesDir: options.guidesDir ?? resolveGuidesDir()
       });
+      guidesSummary = summary.anyChanges ? `Guides installed (${summary.filesWritten.join(", ")})` : `Guides ${DIM}already installed${RST}`;
+      stepDone(out, guidesSummary);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        stdout: "",
+        stderr: `almanac: guide install failed: ${msg}
+`,
+        exitCode: 1
+      };
     }
+  } else {
+    stepSkipped(out, `Guides ${DIM}skipped${RST}`);
   }
-  return out;
+  out.write(BAR + "\n");
+  stepDone(out, `${BLUE}Setup complete${RST}`);
+  out.write("\n");
+  printNextSteps(out);
+  return { stdout: "", stderr: "", exitCode: 0 };
 }
-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 safeCheckAuth(spawnCli) {
+  try {
+    return await checkClaudeAuth(spawnCli);
+  } catch {
+    return { loggedIn: false };
+  }
 }
-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 });
-    }
+function reportAuth(out, auth) {
+  if (auth.loggedIn) {
+    const who = auth.email ?? "Claude account";
+    const plan = auth.subscriptionType !== void 0 ? ` ${DIM}(${auth.subscriptionType})${RST}` : "";
+    stepDone(out, `Claude auth: ${WHITE_BOLD}${who}${RST}${plan}`);
+    return;
+  }
+  if (process.env.ANTHROPIC_API_KEY !== void 0 && process.env.ANTHROPIC_API_KEY.length > 0) {
+    stepDone(out, `Claude auth: ${WHITE_BOLD}ANTHROPIC_API_KEY${RST} set`);
+    return;
   }
-  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);
+  stepActive(out, `Claude auth: ${DIM}not signed in${RST}`);
+  for (const line of UNAUTHENTICATED_MESSAGE.split("\n")) {
+    out.write(`  ${DIM}\u2502   ${line}${RST}
+`);
   }
-  const out = [];
-  for (const [slug, paths] of bySlug.entries()) {
-    if (paths.length > 1) {
-      out.push({ slug, paths: paths.sort() });
+}
+async function installGuides(options) {
+  await mkdir5(options.claudeDir, { recursive: true });
+  const srcMini = path3.join(options.guidesDir, "mini.md");
+  const srcRef = path3.join(options.guidesDir, "reference.md");
+  if (!existsSync11(srcMini)) {
+    throw new Error(`missing bundled guide: ${srcMini}`);
+  }
+  if (!existsSync11(srcRef)) {
+    throw new Error(`missing bundled guide: ${srcRef}`);
+  }
+  const destMini = path3.join(options.claudeDir, "codealmanac.md");
+  const destRef = path3.join(options.claudeDir, "codealmanac-reference.md");
+  const miniChanged = await copyIfChanged(srcMini, destMini);
+  const refChanged = await copyIfChanged(srcRef, destRef);
+  const claudeMd = path3.join(options.claudeDir, "CLAUDE.md");
+  const importChanged = await ensureImport(claudeMd);
+  const filesWritten = [];
+  if (miniChanged) filesWritten.push("codealmanac.md");
+  if (refChanged) filesWritten.push("codealmanac-reference.md");
+  if (importChanged) filesWritten.push("CLAUDE.md");
+  return { anyChanges: filesWritten.length > 0, filesWritten };
+}
+async function copyIfChanged(src, dest) {
+  const srcBytes = await readFile9(src);
+  if (existsSync11(dest)) {
+    try {
+      const destBytes = await readFile9(dest);
+      if (srcBytes.equals(destBytes)) return false;
+    } catch {
     }
   }
-  out.sort((a, b) => a.slug.localeCompare(b.slug));
-  return out;
+  await copyFile(src, dest);
+  return true;
 }
-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)`
-      )
-    )
+var IMPORT_LINE = "@~/.claude/codealmanac.md";
+async function ensureImport(claudeMdPath) {
+  let existing = "";
+  if (existsSync11(claudeMdPath)) {
+    existing = await readFile9(claudeMdPath, "utf8");
+  }
+  if (hasImportLine(existing)) return false;
+  const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  const body = `${existing}${sep}${IMPORT_LINE}
+`;
+  await writeFile5(claudeMdPath, body, "utf8");
+  return true;
+}
+function hasImportLine(contents) {
+  const lines = contents.split(/\r?\n/).map((l) => l.trim());
+  return lines.some((line) => {
+    if (line === IMPORT_LINE) return true;
+    if (!line.startsWith(IMPORT_LINE)) return false;
+    const next = line[IMPORT_LINE.length];
+    return next === " " || next === "	";
+  });
+}
+function confirm(out, question, defaultYes) {
+  return new Promise((resolve2) => {
+    const hint = defaultYes ? "[Y/n]" : "[y/N]";
+    out.write(`  ${BLUE}\u25C6${RST}  ${question} ${DIM}${hint}${RST} `);
+    let buf = "";
+    const onData = (chunk) => {
+      buf += chunk.toString("utf8");
+      const nl = buf.indexOf("\n");
+      if (nl === -1) return;
+      process.stdin.removeListener("data", onData);
+      process.stdin.pause();
+      const answer = buf.slice(0, nl).trim().toLowerCase();
+      const accepted = answer.length === 0 ? defaultYes : answer === "y" || answer === "yes";
+      resolve2(accepted ? "install" : "skip");
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+function printNextSteps(out) {
+  const innerW = 62;
+  const vis = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
+  const row = (content) => {
+    const padding = Math.max(0, innerW - vis(content));
+    return `  ${BLUE_DIM}\u2502${RST}${content}${" ".repeat(padding)}${BLUE_DIM}\u2502${RST}
+`;
+  };
+  const empty = row("");
+  out.write(`  ${BLUE_DIM}\u256D${"\u2500".repeat(innerW)}\u256E${RST}
+`);
+  out.write(empty);
+  out.write(row(`  ${WHITE_BOLD}Next steps${RST}`));
+  out.write(empty);
+  out.write(
+    row(`  ${BLUE}1.${RST}  ${BOLD}cd${RST} into a repo you want to document`)
   );
-  sections.push(
-    section(
-      "empty-topics",
-      r.empty_topics.length,
-      r.empty_topics.map((e) => `  ${e.slug}`)
+  out.write(
+    row(
+      `  ${BLUE}2.${RST}  ${BOLD}almanac bootstrap${RST}  ${DIM}# scaffold the wiki${RST}`
     )
   );
-  sections.push(
-    section(
-      "empty-pages",
-      r.empty_pages.length,
-      r.empty_pages.map((e) => `  ${e.slug}`)
+  out.write(
+    row(
+      `  ${BLUE}3.${RST}  Work normally \u2014 capture runs on session end`
     )
   );
-  sections.push(
-    section(
-      "slug-collisions",
-      r.slug_collisions.length,
-      r.slug_collisions.map((c) => `  ${c.slug}: ${c.paths.join(", ")}`)
-    )
+  out.write(empty);
+  out.write(`  ${BLUE_DIM}\u2570${"\u2500".repeat(innerW)}\u256F${RST}
+
+`);
+}
+function resolveGuidesDir() {
+  const here = path3.dirname(fileURLToPath3(import.meta.url));
+  const candidates = [
+    path3.resolve(here, "..", "guides"),
+    // dist layout
+    path3.resolve(here, "..", "..", "guides"),
+    // src layout
+    path3.resolve(here, "..", "..", "..", "guides")
+  ];
+  for (const dir of candidates) {
+    if (looksLikeGuidesDir(dir)) return dir;
+  }
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const pkgJson = require2.resolve("codealmanac/package.json");
+    const guides = path3.join(path3.dirname(pkgJson), "guides");
+    if (looksLikeGuidesDir(guides)) return guides;
+  } catch {
+  }
+  throw new Error(
+    "could not locate bundled guides/ directory. Tried:\n" + candidates.map((c) => `  - ${c}`).join("\n")
   );
-  return `${sections.join("\n\n")}
-`;
 }
-function section(label, count, lines) {
-  if (count === 0) return `${label} (0): (ok)`;
-  return `${label} (${count}):
-${lines.join("\n")}`;
+function looksLikeGuidesDir(dir) {
+  return existsSync11(path3.join(dir, "mini.md"));
 }
 
-// src/commands/info.ts
-import { join as join9 } from "path";
-async function runInfo(options) {
-  const repoRoot = await resolveWikiRoot({
-    cwd: options.cwd,
-    wiki: options.wiki
+// src/commands/doctor.ts
+var RST2 = "\x1B[0m";
+var BOLD2 = "\x1B[1m";
+var DIM2 = "\x1B[2m";
+var GREEN = "\x1B[38;5;35m";
+var RED = "\x1B[38;5;167m";
+var BLUE2 = "\x1B[38;5;75m";
+async function runDoctor(options) {
+  const version = options.versionOverride ?? readPackageVersion() ?? "unknown";
+  const install = options.wikiOnly === true ? [] : await gatherInstallChecks(options);
+  const wiki = options.installOnly === true ? [] : await gatherWikiChecks(options);
+  const report = { version, install, wiki };
+  if (options.json === true) {
+    return {
+      stdout: `${JSON.stringify(report, null, 2)}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    stdout: formatReport2(report, options),
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function gatherInstallChecks(options) {
+  const checks = [];
+  const installPath = options.installPath ?? detectInstallPath();
+  checks.push({
+    status: installPath !== null ? "ok" : "problem",
+    key: "install.path",
+    message: installPath !== null ? `codealmanac installed at ${installPath}` : "could not detect codealmanac install path",
+    fix: installPath === null ? "reinstall with: npm install -g codealmanac" : void 0
   });
-  await ensureFreshIndex({ repoRoot });
-  const dbPath = join9(repoRoot, ".almanac", "index.db");
-  const db = openIndex(dbPath);
+  const nodeVersion = options.nodeVersion ?? process.version;
+  const sqlite = options.sqliteProbe ?? probeBetterSqlite3();
+  checks.push({
+    status: sqlite.ok ? "ok" : "problem",
+    key: "install.sqlite",
+    message: sqlite.ok ? `better-sqlite3 native binding OK (Node ${nodeVersion})` : `better-sqlite3 native binding failed: ${sqlite.summary}`,
+    fix: sqlite.ok ? void 0 : "run: npm rebuild better-sqlite3 (in the install directory)"
+  });
+  const auth = await safeCheckAuth2(options.spawnCli);
+  checks.push(describeAuth(auth));
+  const settingsPath = options.settingsPath ?? path4.join(homedir5(), ".claude", "settings.json");
+  checks.push(await describeHook(settingsPath));
+  const claudeDir = options.claudeDir ?? path4.join(homedir5(), ".claude");
+  checks.push(describeGuides(claudeDir));
+  checks.push(await describeImportLine(claudeDir));
+  return checks;
+}
+function describeAuth(auth) {
+  if (auth.loggedIn) {
+    if (auth.authMethod === "apiKey") {
+      return {
+        status: "ok",
+        key: "install.auth",
+        message: "claude auth: ANTHROPIC_API_KEY set"
+      };
+    }
+    const who = auth.email ?? "Claude account";
+    const plan = auth.subscriptionType !== void 0 ? ` (${auth.subscriptionType} subscription)` : "";
+    return {
+      status: "ok",
+      key: "install.auth",
+      message: `claude auth: ${who}${plan}`
+    };
+  }
+  if (process.env.ANTHROPIC_API_KEY !== void 0 && process.env.ANTHROPIC_API_KEY.length > 0) {
+    return {
+      status: "ok",
+      key: "install.auth",
+      message: "claude auth: ANTHROPIC_API_KEY set"
+    };
+  }
+  return {
+    status: "problem",
+    key: "install.auth",
+    message: "claude auth: not signed in",
+    fix: "run: claude auth login --claudeai  (or export ANTHROPIC_API_KEY)"
+  };
+}
+async function describeHook(settingsPath) {
+  if (!existsSync12(settingsPath)) {
+    return {
+      status: "problem",
+      key: "install.hook",
+      message: "SessionEnd hook not installed",
+      fix: "run: almanac setup --yes"
+    };
+  }
   try {
-    const slugs = collectSlugs(options);
-    if (slugs.length === 0) {
+    const raw = await readFile10(settingsPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const entries = parsed.hooks?.SessionEnd ?? [];
+    const ours = entries.find(
+      (e) => typeof e.command === "string" && e.command.endsWith("almanac-capture.sh")
+    );
+    if (ours === void 0) {
       return {
-        stdout: "",
-        stderr: "almanac: info requires a slug (or --stdin)\n",
-        exitCode: 1
+        status: "problem",
+        key: "install.hook",
+        message: "SessionEnd hook not installed",
+        fix: "run: almanac setup --yes"
       };
     }
-    const records = [];
-    const missing = [];
-    for (const slug of slugs) {
-      const rec = fetchInfo(db, slug);
-      if (rec === null) {
-        missing.push(slug);
-        continue;
-      }
-      records.push(rec);
+    return {
+      status: "ok",
+      key: "install.hook",
+      message: `SessionEnd hook installed at ${settingsPath}`
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: "problem",
+      key: "install.hook",
+      message: `could not read ${settingsPath}: ${msg}`,
+      fix: "check the file for malformed JSON"
+    };
+  }
+}
+function describeGuides(claudeDir) {
+  const mini = path4.join(claudeDir, "codealmanac.md");
+  const ref = path4.join(claudeDir, "codealmanac-reference.md");
+  const haveMini = existsSync12(mini);
+  const haveRef = existsSync12(ref);
+  if (haveMini && haveRef) {
+    return {
+      status: "ok",
+      key: "install.guides",
+      message: `Agent guides installed (${path4.basename(mini)}, ${path4.basename(ref)})`
+    };
+  }
+  const missing = [
+    haveMini ? null : "codealmanac.md",
+    haveRef ? null : "codealmanac-reference.md"
+  ].filter((s) => s !== null);
+  return {
+    status: "problem",
+    key: "install.guides",
+    message: `Agent guides missing (${missing.join(", ")})`,
+    fix: "run: almanac setup --yes"
+  };
+}
+async function describeImportLine(claudeDir) {
+  const claudeMd = path4.join(claudeDir, "CLAUDE.md");
+  if (!existsSync12(claudeMd)) {
+    return {
+      status: "problem",
+      key: "install.import",
+      message: "CLAUDE.md import not present (no ~/.claude/CLAUDE.md)",
+      fix: "run: almanac setup --yes"
+    };
+  }
+  try {
+    const contents = await readFile10(claudeMd, "utf8");
+    const lines = contents.split(/\r?\n/).map((l) => l.trim());
+    const present = lines.some((line) => {
+      if (line === IMPORT_LINE) return true;
+      if (!line.startsWith(IMPORT_LINE)) return false;
+      const next = line[IMPORT_LINE.length];
+      return next === " " || next === "	";
+    });
+    if (present) {
+      return {
+        status: "ok",
+        key: "install.import",
+        message: "CLAUDE.md import present"
+      };
     }
-    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)}
-`;
+    return {
+      status: "problem",
+      key: "install.import",
+      message: "CLAUDE.md import line missing",
+      fix: "run: almanac setup --yes"
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: "problem",
+      key: "install.import",
+      message: `could not read ${claudeMd}: ${msg}`
+    };
+  }
+}
+async function gatherWikiChecks(options) {
+  const checks = [];
+  const repoRoot = findNearestAlmanacDir(options.cwd);
+  if (repoRoot === null) {
+    checks.push({
+      status: "info",
+      key: "wiki.none",
+      message: "No wiki in current directory",
+      fix: "run: almanac bootstrap  (to create one in this repo)"
+    });
+    return checks;
+  }
+  checks.push({
+    status: "info",
+    key: "wiki.repo",
+    message: `repo: ${repoRoot}`
+  });
+  const entry = await findEntry({ path: repoRoot });
+  if (entry !== null) {
+    checks.push({
+      status: "ok",
+      key: "wiki.registered",
+      message: `registered as '${entry.name}'`
+    });
+  } else {
+    checks.push({
+      status: "info",
+      key: "wiki.registered",
+      message: "not yet registered (will register on first command)"
+    });
+  }
+  const almanacDir = path4.join(repoRoot, ".almanac");
+  const dbPath = path4.join(almanacDir, "index.db");
+  let pageCount = null;
+  let topicCount = null;
+  if (existsSync12(dbPath)) {
+    try {
+      const db = openIndex(dbPath);
+      try {
+        pageCount = countRows(db, "pages");
+        topicCount = countRows(db, "topics");
+      } finally {
+        db.close();
       }
+    } catch {
+      pageCount = null;
+    }
+  }
+  if (pageCount !== null) {
+    checks.push({
+      status: "info",
+      key: "wiki.pages",
+      message: `pages: ${pageCount}`
+    });
+  }
+  if (topicCount !== null) {
+    checks.push({
+      status: "info",
+      key: "wiki.topics",
+      message: `topics: ${topicCount}`
+    });
+  }
+  checks.push(describeIndexFreshness(dbPath));
+  checks.push(describeLastCapture(almanacDir, options.now));
+  const healthFn = options.runHealthFn ?? runHealth;
+  try {
+    const healthRes = await healthFn({
+      cwd: repoRoot,
+      json: true
+    });
+    const problems = countHealthProblems(healthRes.stdout);
+    if (problems === 0) {
+      checks.push({
+        status: "ok",
+        key: "wiki.health",
+        message: "almanac health reports 0 problems"
+      });
     } else {
-      stdout = records.map(formatHumanReadable).join("\n");
+      checks.push({
+        status: "problem",
+        key: "wiki.health",
+        message: `almanac health reports ${problems} problem${problems === 1 ? "" : "s"}`,
+        fix: "run: almanac health"
+      });
     }
-    const stderr = missing.map((s) => `almanac: no such page "${s}"
-`).join("");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    checks.push({
+      status: "info",
+      key: "wiki.health",
+      message: `could not run almanac health: ${msg}`
+    });
+  }
+  return checks;
+}
+function countRows(db, table) {
+  const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+  return row?.n ?? 0;
+}
+function describeIndexFreshness(dbPath) {
+  if (!existsSync12(dbPath)) {
     return {
-      stdout,
-      stderr,
-      exitCode: missing.length > 0 ? 1 : 0
+      status: "info",
+      key: "wiki.index",
+      message: "index: not built yet (run any query command)"
+    };
+  }
+  try {
+    const dbMtime = statSync3(dbPath).mtimeMs;
+    const age = Date.now() - dbMtime;
+    return {
+      status: "info",
+      key: "wiki.index",
+      message: `index: rebuilt ${formatDuration(age)} ago`
+    };
+  } catch {
+    return {
+      status: "info",
+      key: "wiki.index",
+      message: "index: present"
+    };
+  }
+}
+function describeLastCapture(almanacDir, nowFn) {
+  if (!existsSync12(almanacDir)) {
+    return {
+      status: "info",
+      key: "wiki.capture",
+      message: "last capture: never"
+    };
+  }
+  let entries;
+  try {
+    entries = readdirSync(almanacDir);
+  } catch {
+    return {
+      status: "info",
+      key: "wiki.capture",
+      message: "last capture: unknown"
+    };
+  }
+  const captures = entries.filter((e) => e.startsWith(".capture-") && e.endsWith(".log")).map((e) => {
+    try {
+      return {
+        name: e,
+        mtime: statSync3(path4.join(almanacDir, e)).mtimeMs
+      };
+    } catch {
+      return null;
+    }
+  }).filter((e) => e !== null);
+  if (captures.length === 0) {
+    return {
+      status: "info",
+      key: "wiki.capture",
+      message: "last capture: never"
     };
-  } 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);
+  captures.sort((a, b) => b.mtime - a.mtime);
+  const latest = captures[0];
+  const now = (nowFn?.() ?? /* @__PURE__ */ new Date()).getTime();
+  const age = now - latest.mtime;
   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
+    status: "info",
+    key: "wiki.capture",
+    message: `last capture: ${formatDuration(age)} ago (${latest.name})`
   };
 }
-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);
+var req = createRequire3(import.meta.url);
+function countHealthProblems(jsonStdout) {
+  try {
+    const report = JSON.parse(jsonStdout);
+    let total = 0;
+    for (const arr of Object.values(report)) {
+      if (Array.isArray(arr)) total += arr.length;
+    }
+    return total;
+  } catch {
+    return 0;
   }
-  if (options.slug !== void 0 && options.slug.length > 0) {
-    return [options.slug];
+}
+function detectInstallPath() {
+  try {
+    const entry = req.resolve("codealmanac");
+    return path4.dirname(path4.dirname(entry));
+  } catch {
+    return null;
   }
-  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()}`
-    );
+function probeBetterSqlite3() {
+  try {
+    const Database2 = req("better-sqlite3");
+    const db = new Database2(":memory:");
+    db.close();
+    return { ok: true, summary: "native binding loads cleanly" };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const firstLine = msg.split("\n")[0] ?? msg;
+    return { ok: false, summary: firstLine };
   }
-  if (rec.superseded_by !== null) {
-    lines.push(`superseded_by: ${rec.superseded_by}`);
+}
+async function safeCheckAuth2(spawnCli) {
+  try {
+    return await checkClaudeAuth(spawnCli);
+  } catch {
+    return { loggedIn: false };
   }
-  if (rec.supersedes.length > 0) {
-    lines.push(`supersedes:    ${rec.supersedes.join(", ")}`);
+}
+function readPackageVersion() {
+  try {
+    const pkg = req("../../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
   }
-  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)" : ""}`);
+  try {
+    const pkg = req("../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
     }
+  } catch {
   }
-  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 null;
+}
+function formatReport2(report, options) {
+  const color = options.stdout === void 0 && process.stdout.isTTY === true;
+  const lines = [];
+  lines.push(`codealmanac v${report.version}`);
+  lines.push("");
+  if (report.install.length > 0) {
+    lines.push(color ? `${BOLD2}## Install${RST2}` : "## Install");
+    for (const c of report.install) {
+      lines.push(formatCheck(c, color));
+    }
+    lines.push("");
+  }
+  if (report.wiki.length > 0) {
+    lines.push(color ? `${BOLD2}## Current wiki${RST2}` : "## Current wiki");
+    for (const c of report.wiki) {
+      lines.push(formatCheck(c, color));
     }
+    lines.push("");
   }
   return `${lines.join("\n")}
 `;
 }
+function formatCheck(c, color) {
+  const { icon, tint } = iconFor(c.status, color);
+  const head = `  ${tint}${icon}${color ? RST2 : ""} ${c.message}`;
+  if (c.fix === void 0) return head;
+  const fixLine = color ? `    ${DIM2}${c.fix}${RST2}` : `    ${c.fix}`;
+  return `${head}
+${fixLine}`;
+}
+function iconFor(status, color) {
+  switch (status) {
+    case "ok":
+      return { icon: "\u2713", tint: color ? GREEN : "" };
+    case "problem":
+      return { icon: "\u2717", tint: color ? RED : "" };
+    case "info":
+      return { icon: "\u25C7", tint: color ? BLUE2 : "" };
+  }
+}
+function formatDuration(ms) {
+  if (ms < 0) return "just now";
+  const seconds = Math.floor(ms / 1e3);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
 
 // src/commands/list.ts
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 async function listWikis(options) {
   if (options.drop !== void 0) {
     return handleDrop(options.drop);
@@ -2430,11 +3061,11 @@ async function handleDrop(name) {
 }
 function isReachable(entry) {
   if (entry.path.length === 0) return false;
-  return existsSync11(entry.path);
+  return existsSync13(entry.path);
 }
 function formatPretty(entries) {
   if (entries.length === 0) {
-    return "no wikis registered. run `almanac init` in a repo to create one.\n";
+    return "no wikis registered. run `almanac bootstrap` in a repo to create one.\n";
   }
   const nameWidth = Math.min(
     30,
@@ -2451,61 +3082,6 @@ function formatPretty(entries) {
 `;
 }
 
-// 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({
@@ -2520,14 +3096,14 @@ async function runReindex(options) {
 }
 
 // src/commands/search.ts
-import { join as join11 } from "path";
+import { join as join9 } 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 dbPath = join9(repoRoot, ".almanac", "index.db");
   const db = openIndex(dbPath);
   try {
     const rows = executeQuery(db, options);
@@ -2687,6 +3263,9 @@ function formatResults(rows, options) {
 }
 function buildStderr(rows, options) {
   if (options.json === true) return "";
+  if (rows.length === 0) {
+    return "# 0 results\n";
+  }
   if (options.limit !== void 0) return "";
   if (rows.length > 50) {
     return `almanac: ${rows.length} results \u2014 consider --limit or a narrower query
@@ -2696,18 +3275,18 @@ function buildStderr(rows, options) {
 }
 
 // src/commands/show.ts
-import { readFile as readFile9 } from "fs/promises";
-import { join as join12 } from "path";
+import { readFile as readFile11 } from "fs/promises";
+import { join as join10 } 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 dbPath = join10(repoRoot, ".almanac", "index.db");
   const db = openIndex(dbPath);
   try {
-    const slugs = collectSlugs3(options);
+    const slugs = collectSlugs(options);
     if (slugs.length === 0) {
       return {
         stdout: "",
@@ -2715,44 +3294,291 @@ async function runShow(options) {
         exitCode: 1
       };
     }
-    const stmt = db.prepare(
-      "SELECT file_path FROM pages WHERE slug = ?"
+    const records = [];
+    const missing = [];
+    for (const slug of slugs) {
+      const rec = await fetchRecord(db, slug);
+      if (rec === null) {
+        missing.push(slug);
+        continue;
+      }
+      records.push(rec);
+    }
+    const bulk = options.stdin === true;
+    const stdout = bulk ? formatBulk(records) : formatSingle(records, options);
+    const stderr = missing.map((s) => `almanac: no such page "${s}"
+`).join("");
+    return {
+      stdout,
+      stderr,
+      exitCode: missing.length > 0 ? 1 : 0
+    };
+  } finally {
+    db.close();
+  }
+}
+async function fetchRecord(db, slug) {
+  const pageRow = db.prepare(
+    "SELECT slug, title, file_path, updated_at, archived_at, superseded_by FROM pages WHERE slug = ?"
+  ).get(slug);
+  if (pageRow === void 0) return null;
+  const topics = db.prepare(
+    "SELECT topic_slug FROM page_topics WHERE page_slug = ? ORDER BY topic_slug"
+  ).all(slug).map((r) => r.topic_slug);
+  const refs = db.prepare(
+    "SELECT original_path, is_dir FROM file_refs WHERE page_slug = ? ORDER BY original_path"
+  ).all(slug).map((r) => ({ path: r.original_path, is_dir: r.is_dir === 1 }));
+  const linksOut = db.prepare(
+    "SELECT target_slug FROM wikilinks WHERE source_slug = ? ORDER BY target_slug"
+  ).all(slug).map((r) => r.target_slug);
+  const linksIn = db.prepare(
+    "SELECT source_slug FROM wikilinks WHERE target_slug = ? ORDER BY source_slug"
+  ).all(slug).map((r) => r.source_slug);
+  const xwiki = db.prepare(
+    "SELECT target_wiki, target_slug FROM cross_wiki_links WHERE source_slug = ? ORDER BY target_wiki, target_slug"
+  ).all(slug).map((r) => ({ wiki: r.target_wiki, target: r.target_slug }));
+  const supersedesRows = db.prepare(
+    "SELECT slug FROM pages WHERE superseded_by = ? ORDER BY slug"
+  ).all(slug).map((r) => r.slug);
+  let body = "";
+  try {
+    body = stripFrontmatter(await readFile11(pageRow.file_path, "utf8"));
+  } catch {
+  }
+  return {
+    slug: pageRow.slug,
+    title: pageRow.title,
+    file_path: pageRow.file_path,
+    updated_at: pageRow.updated_at,
+    archived_at: pageRow.archived_at,
+    superseded_by: pageRow.superseded_by,
+    supersedes: supersedesRows,
+    topics,
+    file_refs: refs,
+    wikilinks_out: linksOut,
+    wikilinks_in: linksIn,
+    cross_wiki_links: xwiki,
+    body
+  };
+}
+function formatBulk(records) {
+  if (records.length === 0) return "";
+  return records.map((r) => JSON.stringify(r)).join("\n") + "\n";
+}
+function formatSingle(records, options) {
+  if (options.json === true) {
+    const only = records[0] ?? null;
+    return `${JSON.stringify(only, null, 2)}
+`;
+  }
+  return records.map((r) => formatRecord(r, options)).join("");
+}
+var FIELD_ORDER = [
+  "title",
+  "topics",
+  "files",
+  "links",
+  "backlinks",
+  "xwiki",
+  "lineage",
+  "updated",
+  "path"
+];
+function selectedFields(options) {
+  const selected = [];
+  for (const f of FIELD_ORDER) {
+    if (options[f] === true) selected.push(f);
+  }
+  return selected;
+}
+function formatRecord(rec, options) {
+  if (options.raw === true) {
+    if (rec.body.length === 0) return "";
+    return rec.body.endsWith("\n") ? rec.body : `${rec.body}
+`;
+  }
+  const fields = selectedFields(options);
+  if (fields.length > 0) {
+    if (fields.length === 1) {
+      return bareField(rec, fields[0]);
+    }
+    return labeledFields(rec, fields);
+  }
+  if (options.meta === true) {
+    return metadataHeader(rec) + "\n";
+  }
+  if (options.lead === true) {
+    return firstParagraph(rec.body) + "\n";
+  }
+  const header = metadataHeader(rec);
+  const body = rec.body;
+  const sep = body.length > 0 ? "\n\n---\n\n" : "\n";
+  return header + sep + body;
+}
+function bareField(rec, field) {
+  switch (field) {
+    case "title":
+      return (rec.title ?? "") + "\n";
+    case "topics":
+      return rec.topics.map((t) => `${t}
+`).join("");
+    case "files":
+      return rec.file_refs.map((r) => `${r.path}
+`).join("");
+    case "links":
+      return rec.wikilinks_out.map((t) => `${t}
+`).join("");
+    case "backlinks":
+      return rec.wikilinks_in.map((t) => `${t}
+`).join("");
+    case "xwiki":
+      return rec.cross_wiki_links.map((x) => `${x.wiki}:${x.target}
+`).join("");
+    case "lineage": {
+      const lines = [];
+      if (rec.archived_at !== null) {
+        lines.push(
+          `archived_at: ${new Date(rec.archived_at * 1e3).toISOString()}`
+        );
+      }
+      if (rec.superseded_by !== null) {
+        lines.push(`superseded_by: ${rec.superseded_by}`);
+      }
+      if (rec.supersedes.length > 0) {
+        lines.push(`supersedes: ${rec.supersedes.join(", ")}`);
+      }
+      return lines.length > 0 ? `${lines.join("\n")}
+` : "";
+    }
+    case "updated":
+      return `${new Date(rec.updated_at * 1e3).toISOString()}
+`;
+    case "path":
+      return `${rec.file_path}
+`;
+  }
+}
+function labeledFields(rec, fields) {
+  const parts = [];
+  for (const f of fields) {
+    parts.push(labeledSection(rec, f));
+  }
+  return parts.join("\n");
+}
+function labeledSection(rec, field) {
+  switch (field) {
+    case "title":
+      return `title: ${rec.title ?? "\u2014"}
+`;
+    case "topics":
+      return rec.topics.length > 0 ? `topics: ${rec.topics.join(", ")}
+` : `topics: \u2014
+`;
+    case "files":
+      return formatListSection(
+        "files",
+        rec.file_refs.map((r) => `${r.path}`)
+      );
+    case "links":
+      return formatListSection("links", rec.wikilinks_out);
+    case "backlinks":
+      return formatListSection("backlinks", rec.wikilinks_in);
+    case "xwiki":
+      return formatListSection(
+        "xwiki",
+        rec.cross_wiki_links.map((x) => `${x.wiki}:${x.target}`)
+      );
+    case "lineage": {
+      const lines = ["lineage:"];
+      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(", ")}`);
+      }
+      if (lines.length === 1) lines.push("  \u2014");
+      return lines.join("\n") + "\n";
+    }
+    case "updated":
+      return `updated: ${new Date(rec.updated_at * 1e3).toISOString()}
+`;
+    case "path":
+      return `path: ${rec.file_path}
+`;
+  }
+}
+function formatListSection(label, items) {
+  if (items.length === 0) return `${label}: \u2014
+`;
+  if (items.length <= 3) return `${label}: ${items.join(", ")}
+`;
+  return `${label}:
+${items.map((i) => `  ${i}`).join("\n")}
+`;
+}
+function metadataHeader(rec) {
+  const lines = [];
+  lines.push(`slug:       ${rec.slug}`);
+  lines.push(`title:      ${rec.title ?? "\u2014"}`);
+  lines.push(
+    `topics:     ${rec.topics.length > 0 ? rec.topics.join(", ") : "\u2014"}`
+  );
+  if (rec.file_refs.length > 0) {
+    const parts = rec.file_refs.map(
+      (r) => `${r.path}`
+    );
+    lines.push(`files:      ${parts.join(", ")}`);
+  }
+  lines.push(
+    `updated:    ${new Date(rec.updated_at * 1e3).toISOString()}`
+  );
+  if (rec.wikilinks_out.length > 0) {
+    lines.push(`links:      ${rec.wikilinks_out.join(", ")}`);
+  }
+  if (rec.wikilinks_in.length > 0) {
+    lines.push(`backlinks:  ${rec.wikilinks_in.join(", ")}`);
+  }
+  if (rec.cross_wiki_links.length > 0) {
+    lines.push(
+      `xwiki:      ${rec.cross_wiki_links.map((x) => `${x.wiki}:${x.target}`).join(", ")}`
     );
-    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();
   }
+  if (rec.archived_at !== null) {
+    lines.push(
+      `archived:   ${new Date(rec.archived_at * 1e3).toISOString()}`
+    );
+  }
+  if (rec.superseded_by !== null) {
+    lines.push(`superseded_by: ${rec.superseded_by}`);
+  }
+  if (rec.supersedes.length > 0) {
+    lines.push(`supersedes: ${rec.supersedes.join(", ")}`);
+  }
+  return lines.join("\n");
 }
-function collectSlugs3(options) {
+function stripFrontmatter(src) {
+  if (!src.startsWith("---\n") && !src.startsWith("---\r\n")) return src;
+  const afterOpen = src.replace(/^---\r?\n/, "");
+  const endMatch = afterOpen.match(/^---[ \t]*\r?\n/m);
+  if (endMatch === null || endMatch.index === void 0) return src;
+  return afterOpen.slice(endMatch.index + endMatch[0].length);
+}
+function firstParagraph(body) {
+  let src = body.trimStart();
+  if (src.startsWith("# ")) {
+    const nl = src.indexOf("\n");
+    src = nl === -1 ? "" : src.slice(nl + 1).trimStart();
+  }
+  const blank = src.search(/\n[ \t]*\n/);
+  if (blank === -1) return src.trimEnd();
+  return src.slice(0, blank).trimEnd();
+}
+function collectSlugs(options) {
   if (options.stdin === true && options.stdinInput !== void 0) {
     return options.stdinInput.split(/\r?\n/).map((s) => s.trim()).filter((s) => s.length > 0);
   }
@@ -2763,17 +3589,17 @@ function collectSlugs3(options) {
 }
 
 // src/topics/frontmatterRewrite.ts
-import { readFile as readFile10, rename as rename4, writeFile as writeFile5 } from "fs/promises";
+import { readFile as readFile12, rename as rename4, writeFile as writeFile6 } from "fs/promises";
 import yaml3 from "js-yaml";
 async function rewritePageTopics(filePath, transform) {
-  const raw = await readFile10(filePath, "utf8");
+  const raw = await readFile12(filePath, "utf8");
   const { before, after, output, changed } = applyTopicsTransform(
     raw,
     transform
   );
   if (changed) {
     const tmp = `${filePath}.tmp`;
-    await writeFile5(tmp, output, "utf8");
+    await writeFile6(tmp, output, "utf8");
     await rename4(tmp, filePath);
   }
   return { before, after, changed };
@@ -2980,12 +3806,12 @@ function arraysEqual(a, b) {
 }
 
 // src/topics/paths.ts
-import { join as join13 } from "path";
+import { join as join11 } from "path";
 function topicsYamlPath(repoRoot) {
-  return join13(repoRoot, ".almanac", "topics.yaml");
+  return join11(repoRoot, ".almanac", "topics.yaml");
 }
 function indexDbPath(repoRoot) {
-  return join13(repoRoot, ".almanac", "index.db");
+  return join11(repoRoot, ".almanac", "index.db");
 }
 
 // src/commands/tag.ts
@@ -3144,8 +3970,8 @@ async function runUntag(options) {
 }
 
 // src/commands/topics.ts
-import { readFile as readFile11 } from "fs/promises";
-import { join as join14 } from "path";
+import { readFile as readFile13 } from "fs/promises";
+import { join as join12 } from "path";
 import fg3 from "fast-glob";
 async function runTopicsList(options) {
   const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
@@ -3617,7 +4443,7 @@ async function runTopicsDescribe(options) {
   };
 }
 async function rewriteTopicOnPages(repoRoot, transform) {
-  const pagesDir = join14(repoRoot, ".almanac", "pages");
+  const pagesDir = join12(repoRoot, ".almanac", "pages");
   const files = await fg3("**/*.md", {
     cwd: pagesDir,
     absolute: true,
@@ -3625,7 +4451,7 @@ async function rewriteTopicOnPages(repoRoot, transform) {
   });
   let changed = 0;
   for (const filePath of files) {
-    const raw = await readFile11(filePath, "utf8");
+    const raw = await readFile13(filePath, "utf8");
     const applied = applyTopicsTransform(raw, transform);
     if (!applied.changed) continue;
     await rewritePageTopics(filePath, transform);
@@ -3634,14 +4460,146 @@ async function rewriteTopicOnPages(repoRoot, transform) {
   return changed;
 }
 
+// src/commands/uninstall.ts
+import { existsSync as existsSync14 } from "fs";
+import { readFile as readFile14, rm, writeFile as writeFile7 } from "fs/promises";
+import { homedir as homedir6 } from "os";
+import path5 from "path";
+var BLUE3 = "\x1B[38;5;75m";
+var DIM3 = "\x1B[2m";
+var RST3 = "\x1B[0m";
+async function runUninstall(options = {}) {
+  const out = options.stdout ?? process.stdout;
+  const isTTY = options.isTTY ?? process.stdin.isTTY === true;
+  const interactive = isTTY && options.yes !== true;
+  const claudeDir = options.claudeDir ?? path5.join(homedir6(), ".claude");
+  out.write("\n");
+  let removeHook = true;
+  if (options.keepHook === true) {
+    removeHook = false;
+  } else if (interactive) {
+    removeHook = await confirm2(
+      out,
+      "Remove the SessionEnd hook from ~/.claude/settings.json?",
+      true
+    );
+  }
+  if (removeHook) {
+    const res = await runHookUninstall({
+      settingsPath: options.settingsPath,
+      hookScriptPath: options.hookScriptPath
+    });
+    if (res.exitCode !== 0) {
+      return { stdout: "", stderr: res.stderr, exitCode: res.exitCode };
+    }
+    out.write(`  ${BLUE3}\u25C7${RST3}  ${res.stdout.trim()}
+`);
+  } else {
+    out.write(`  ${DIM3}\u25CB  Hook kept${RST3}
+`);
+  }
+  let removeGuides = true;
+  if (options.keepGuides === true) {
+    removeGuides = false;
+  } else if (interactive) {
+    removeGuides = await confirm2(
+      out,
+      "Remove the guides + CLAUDE.md import line?",
+      true
+    );
+  }
+  if (removeGuides) {
+    const summary = await removeGuideFiles(claudeDir);
+    if (summary.anyChanges) {
+      out.write(
+        `  ${BLUE3}\u25C7${RST3}  Guides removed (${summary.filesTouched.join(", ")})
+`
+      );
+    } else {
+      out.write(`  ${DIM3}\u25CB  Guides not installed${RST3}
+`);
+    }
+  } else {
+    out.write(`  ${DIM3}\u25CB  Guides kept${RST3}
+`);
+  }
+  out.write(`
+  ${BLUE3}\u25C7${RST3}  ${BLUE3}Uninstall complete${RST3}
+
+`);
+  return { stdout: "", stderr: "", exitCode: 0 };
+}
+async function removeGuideFiles(claudeDir) {
+  const touched = [];
+  const mini = path5.join(claudeDir, "codealmanac.md");
+  const ref = path5.join(claudeDir, "codealmanac-reference.md");
+  const claudeMd = path5.join(claudeDir, "CLAUDE.md");
+  if (existsSync14(mini)) {
+    await rm(mini, { force: true });
+    touched.push("codealmanac.md");
+  }
+  if (existsSync14(ref)) {
+    await rm(ref, { force: true });
+    touched.push("codealmanac-reference.md");
+  }
+  if (existsSync14(claudeMd)) {
+    const existing = await readFile14(claudeMd, "utf8");
+    const { changed, body } = removeImportLine(existing);
+    if (changed) {
+      if (body.trim().length === 0) {
+        await rm(claudeMd, { force: true });
+        touched.push("CLAUDE.md (deleted)");
+      } else {
+        await writeFile7(claudeMd, body, "utf8");
+        touched.push("CLAUDE.md");
+      }
+    }
+  }
+  return { anyChanges: touched.length > 0, filesTouched: touched };
+}
+function removeImportLine(contents) {
+  const eol = contents.includes("\r\n") ? "\r\n" : "\n";
+  const lines = contents.split(/\r?\n/);
+  const indices = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === IMPORT_LINE) indices.push(i);
+  }
+  if (indices.length === 0) return { changed: false, body: contents };
+  for (let i = indices.length - 1; i >= 0; i--) {
+    lines.splice(indices[i], 1);
+  }
+  let body = lines.join(eol);
+  body = body.replace(/\n\n\n+/g, "\n\n");
+  return { changed: true, body };
+}
+function confirm2(out, question, defaultYes) {
+  return new Promise((resolve2) => {
+    const hint = defaultYes ? "[Y/n]" : "[y/N]";
+    out.write(`  ${BLUE3}\u25C6${RST3}  ${question} ${DIM3}${hint}${RST3} `);
+    let buf = "";
+    const onData = (chunk) => {
+      buf += chunk.toString("utf8");
+      const nl = buf.indexOf("\n");
+      if (nl === -1) return;
+      process.stdin.removeListener("data", onData);
+      process.stdin.pause();
+      const answer = buf.slice(0, nl).trim().toLowerCase();
+      const accepted = answer.length === 0 ? defaultYes : answer === "y" || answer === "yes";
+      resolve2(accepted);
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
 // src/registry/autoregister.ts
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync15 } 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;
+    if (!existsSync15(repoRoot)) return null;
     const entries = await readRegistry();
     const existing = entries.find((e) => samePath(e.path, repoRoot));
     if (existing !== void 0) return existing;
@@ -3686,45 +4644,30 @@ function samePath(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";
+  const program = new Command();
   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;
+  ).version(readPackageVersion2(), "-v, --version", "print version");
+  if (programName === "codealmanac") {
+    const setupInvocation = tryParseSetupShortcut(argv.slice(2));
+    if (setupInvocation !== null) {
+      const result = await runSetup(setupInvocation);
+      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;
+      return;
     }
-  });
-  program.command("search [query]").description("query pages by text, topic, file mentions, or freshness").option(
+  }
+  program.command("search [query]").description("find pages by text, topic, file mentions, freshness").option(
     "--topic <name...>",
     "filter by topic (repeat for intersection)",
     collectOption,
     []
   ).option(
     "--mentions <path>",
-    "pages referencing this file or folder (trailing / = folder)"
+    "pages referencing this path; matches exact file, trailing-slash folders, and any file under a folder prefix"
   ).option(
     "--since <duration>",
     "updated within duration, by file mtime (e.g. 2w, 30d)"
@@ -3748,12 +4691,10 @@ async function run(argv) {
         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;
+      emit(result);
     }
   );
-  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(
+  program.command("show [slug]").description("print a page (metadata + body; flags to narrow)").option("--stdin", "read slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").option("--json", "structured JSON (overrides other view/field flags)").option("--raw", "body only (alias: --body)").option("--body", "body only (alias: --raw)").option("--meta", "metadata only, no body").option("--lead", "first paragraph of the body only").option("--title", "print title").option("--topics", "print topics").option("--files", "print file refs").option("--links", "print outgoing wikilinks").option("--backlinks", "print incoming wikilinks").option("--xwiki", "print cross-wiki links").option("--lineage", "print archived_at / supersedes / superseded_by").option("--updated", "print updated timestamp").option("--path", "print absolute file path").action(
     async (slug, opts) => {
       await autoRegisterIfNeeded(process.cwd());
       const result = await runShow({
@@ -3761,54 +4702,85 @@ async function run(argv) {
         slug,
         stdin: opts.stdin,
         stdinInput: opts.stdin === true ? await readStdin() : void 0,
-        wiki: opts.wiki
+        wiki: opts.wiki,
+        json: opts.json,
+        // `--body` is a surface alias for `--raw`. Fold it into one
+        // field at the CLI boundary so the implementation never has
+        // to care which spelling the user typed.
+        raw: opts.raw === true || opts.body === true,
+        meta: opts.meta,
+        lead: opts.lead,
+        title: opts.title,
+        topics: opts.topics,
+        files: opts.files,
+        links: opts.links,
+        backlinks: opts.backlinks,
+        xwiki: opts.xwiki,
+        lineage: opts.lineage,
+        updated: opts.updated,
+        path: opts.path
       });
-      if (result.stderr.length > 0) process.stderr.write(result.stderr);
-      process.stdout.write(result.stdout);
-      if (result.exitCode !== 0) process.exitCode = result.exitCode;
+      emit(result);
     }
   );
-  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) => {
+  program.command("health").description("report graph integrity problems").option("--topic <name>", "scope to a topic + its descendants").option("--stale <duration>", "stale threshold (default 90d)").option("--stdin", "read page slugs from stdin (limit to these pages)").option("--json", "emit structured JSON").option("--wiki <name>", "target a specific registered wiki").action(
+    async (opts) => {
       await autoRegisterIfNeeded(process.cwd());
-      const result = await runPath({
+      const result = await runHealth({
         cwd: process.cwd(),
-        slug,
+        topic: opts.topic,
+        stale: opts.stale,
         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;
+      emit(result);
     }
   );
-  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) => {
+  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("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 result = await runInfo({
+      const resolvedTopics = opts.stdin === true ? [page, ...topicsArg].filter(
+        (t) => typeof t === "string" && t.length > 0
+      ) : topicsArg;
+      const result = await runTag({
         cwd: process.cwd(),
-        slug,
+        page: opts.stdin === true ? void 0 : page,
+        topics: resolvedTopics,
         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;
+      emit(result);
     }
   );
-  program.command("reindex").description("force a full rebuild of .almanac/index.db").option("--wiki <name>", "target a specific registered wiki").action(async (opts) => {
-    await autoRegisterIfNeeded(process.cwd());
-    const result = await runReindex({
-      cwd: process.cwd(),
-      wiki: opts.wiki
-    });
-    process.stdout.write(result.stdout);
-    if (result.exitCode !== 0) process.exitCode = result.exitCode;
-  });
-  const topics = program.command("topics").description("manage the topic DAG (list, create, link, rename, delete)");
+  program.command("untag <page> <topic>").description("remove a topic from a page's frontmatter").option("--wiki <name>", "target a specific registered wiki").action(
+    async (page, topic, opts) => {
+      await autoRegisterIfNeeded(process.cwd());
+      const result = await runUntag({
+        cwd: process.cwd(),
+        page,
+        topic,
+        wiki: opts.wiki
+      });
+      emit(result);
+    }
+  );
+  const topics = program.command("topics").description("manage the topic DAG");
   topics.command("list", { isDefault: true }).description("list all topics with page counts").option("--wiki <name>", "target a specific registered wiki").option("--json", "emit structured JSON").action(async (opts) => {
     await autoRegisterIfNeeded(process.cwd());
     const result = await runTopicsList({
@@ -3905,37 +4877,8 @@ async function run(argv) {
       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)"
+    "scaffold a wiki in this repo via an AI agent (requires ANTHROPIC_API_KEY or Claude subscription)"
   ).option("--quiet", "suppress per-tool streaming; print only the final line").option("--model <model>", "override the agent model").option(
     "--force",
     "overwrite an existing populated wiki (default: refuse)"
@@ -3951,7 +4894,7 @@ async function run(argv) {
     }
   );
   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)"
+    "run the writer/reviewer pipeline on a session (usually automatic)"
   ).option("--session <id>", "target a specific session by ID").option(
     "--quiet",
     "suppress per-tool streaming; print only the final summary"
@@ -3968,9 +4911,7 @@ async function run(argv) {
       emit(result);
     }
   );
-  const hook = program.command("hook").description(
-    "install, uninstall, or inspect the SessionEnd hook in ~/.claude/settings.json"
-  );
+  const hook = program.command("hook").description("manage the SessionEnd auto-capture hook");
   hook.command("install").description("add a SessionEnd entry that runs 'almanac capture' on session end").action(async () => {
     const result = await runHookInstall();
     emit(result);
@@ -3983,23 +4924,182 @@ async function run(argv) {
     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(
+  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;
+  });
+  program.command("setup").description("install the hook + CLAUDE.md guides (bare codealmanac alias)").option("-y, --yes", "skip prompts; install everything").option("--skip-hook", "opt out of the SessionEnd hook").option("--skip-guides", "opt out of the CLAUDE.md guides").action(
     async (opts) => {
-      await autoRegisterIfNeeded(process.cwd());
-      const result = await runHealth({
+      const result = await runSetup({
+        yes: opts.yes,
+        skipHook: opts.skipHook,
+        skipGuides: opts.skipGuides
+      });
+      emit(result);
+    }
+  );
+  program.command("doctor").description("report on the codealmanac install + current wiki health").option("--json", "emit structured JSON").option("--install-only", "report only on the install (skip wiki checks)").option("--wiki-only", "report only on the current wiki (skip install checks)").action(
+    async (opts) => {
+      const result = await runDoctor({
         cwd: process.cwd(),
-        topic: opts.topic,
-        stale: opts.stale,
-        stdin: opts.stdin,
-        stdinInput: opts.stdin === true ? await readStdin() : void 0,
         json: opts.json,
-        wiki: opts.wiki
+        installOnly: opts.installOnly,
+        wikiOnly: opts.wikiOnly
+      });
+      emit(result);
+    }
+  );
+  program.command("uninstall").description("remove the hook + guides + import line").option("-y, --yes", "skip confirmations; remove everything").option(
+    "--keep-hook",
+    "don't remove the SessionEnd hook (guides still prompted unless --yes)"
+  ).option(
+    "--keep-guides",
+    "don't remove the guides or CLAUDE.md import (hook still prompted unless --yes)"
+  ).action(
+    async (opts) => {
+      const result = await runUninstall({
+        yes: opts.yes,
+        keepHook: opts.keepHook,
+        keepGuides: opts.keepGuides
       });
       emit(result);
     }
   );
+  configureGroupedHelp(program);
   await program.parseAsync(argv);
 }
+var HELP_GROUPS = [
+  {
+    title: "Query",
+    commands: ["search", "show", "health", "list"]
+  },
+  {
+    title: "Edit",
+    commands: ["tag", "untag", "topics"]
+  },
+  {
+    title: "Wiki lifecycle",
+    commands: ["bootstrap", "capture", "hook", "reindex"]
+  },
+  {
+    title: "Setup",
+    commands: ["setup", "uninstall", "doctor"]
+  }
+];
+function configureGroupedHelp(program) {
+  program.configureHelp({
+    formatHelp(cmd, helper) {
+      if (cmd.parent !== null) {
+        return renderDefault(cmd, helper);
+      }
+      const termWidth = helper.padWidth(cmd, helper);
+      const helpWidth = helper.helpWidth ?? process.stdout.columns ?? 80;
+      const itemSepWidth = 2;
+      const out = [];
+      out.push(`Usage: ${helper.commandUsage(cmd)}
+`);
+      const description = helper.commandDescription(cmd);
+      if (description.length > 0) {
+        out.push(
+          helper.wrap(description, helpWidth, 0) + "\n"
+        );
+      }
+      const optionList = helper.visibleOptions(cmd).map(
+        (o) => `${helper.optionTerm(o)}${" ".repeat(Math.max(0, termWidth - helper.optionTerm(o).length) + itemSepWidth)}${helper.optionDescription(o)}`
+      );
+      if (optionList.length > 0) {
+        out.push("Options:");
+        for (const l of optionList) out.push(`  ${l}`);
+        out.push("");
+      }
+      const visible = helper.visibleCommands(cmd);
+      const byName = /* @__PURE__ */ new Map();
+      for (const c of visible) byName.set(c.name(), c);
+      for (const group of HELP_GROUPS) {
+        const members = group.commands.map((n) => byName.get(n)).filter((c) => c !== void 0);
+        if (members.length === 0) continue;
+        out.push(`${group.title}:`);
+        for (const c of members) {
+          const term = helper.subcommandTerm(c);
+          const desc = helper.subcommandDescription(c);
+          const padding = Math.max(
+            0,
+            termWidth - term.length + itemSepWidth
+          );
+          out.push(`  ${term}${" ".repeat(padding)}${desc}`);
+          byName.delete(c.name());
+        }
+        out.push("");
+      }
+      if (byName.size > 0) {
+        out.push("Other:");
+        for (const c of byName.values()) {
+          const term = helper.subcommandTerm(c);
+          const desc = helper.subcommandDescription(c);
+          const padding = Math.max(
+            0,
+            termWidth - term.length + itemSepWidth
+          );
+          out.push(`  ${term}${" ".repeat(padding)}${desc}`);
+        }
+        out.push("");
+      }
+      return out.join("\n");
+    }
+  });
+}
+function renderDefault(cmd, helper) {
+  const termWidth = helper.padWidth(cmd, helper);
+  const helpWidth = helper.helpWidth ?? process.stdout.columns ?? 80;
+  const itemSepWidth = 2;
+  const lines = [`Usage: ${helper.commandUsage(cmd)}
+`];
+  const description = helper.commandDescription(cmd);
+  if (description.length > 0) {
+    lines.push(helper.wrap(description, helpWidth, 0) + "\n");
+  }
+  const args = helper.visibleArguments(cmd).map(
+    (a) => `${helper.argumentTerm(a)}${" ".repeat(Math.max(0, termWidth - helper.argumentTerm(a).length) + itemSepWidth)}${helper.argumentDescription(a)}`
+  );
+  if (args.length > 0) {
+    lines.push("Arguments:");
+    for (const a of args) lines.push(`  ${a}`);
+    lines.push("");
+  }
+  const opts = helper.visibleOptions(cmd).map(
+    (o) => `${helper.optionTerm(o)}${" ".repeat(Math.max(0, termWidth - helper.optionTerm(o).length) + itemSepWidth)}${helper.optionDescription(o)}`
+  );
+  if (opts.length > 0) {
+    lines.push("Options:");
+    for (const o of opts) lines.push(`  ${o}`);
+    lines.push("");
+  }
+  const subs = helper.visibleCommands(cmd).map(
+    (c) => `${helper.subcommandTerm(c)}${" ".repeat(Math.max(0, termWidth - helper.subcommandTerm(c).length) + itemSepWidth)}${helper.subcommandDescription(c)}`
+  );
+  if (subs.length > 0) {
+    lines.push("Commands:");
+    for (const s of subs) lines.push(`  ${s}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function readPackageVersion2() {
+  try {
+    const require2 = createRequire4(import.meta.url);
+    const pkg = require2("../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return "unknown";
+}
 function emit(result) {
   if (result.stderr.length > 0) process.stderr.write(result.stderr);
   if (result.stdout.length > 0) process.stdout.write(result.stdout);
@@ -4023,6 +5123,26 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
+function tryParseSetupShortcut(args) {
+  if (args.length === 0) return {};
+  const opts = {};
+  for (const arg of args) {
+    if (arg === "--yes" || arg === "-y") {
+      opts.yes = true;
+      continue;
+    }
+    if (arg === "--skip-hook") {
+      opts.skipHook = true;
+      continue;
+    }
+    if (arg === "--skip-guides") {
+      opts.skipGuides = true;
+      continue;
+    }
+    return null;
+  }
+  return opts;
+}
 
 // bin/codealmanac.ts
 run(process.argv).catch((err) => {