codealmanac 0.1.2 → 0.1.3

package/dist/codealmanac.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { createRequire as createRequire3 } from "module";
+import { createRequire as createRequire4 } from "module";
 import { basename as basename6 } from "path";
 import { Command } from "commander";
 
@@ -240,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 path5 = getRegistryPath();
+  const path6 = getRegistryPath();
   let raw;
   try {
-    raw = await readFile2(path5, "utf8");
+    raw = await readFile2(path6, "utf8");
   } catch (err) {
     if (isNodeError(err) && err.code === "ENOENT") {
       return [];
@@ -259,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 ${path5} 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 ${path5} 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) {
@@ -270,29 +270,29 @@ async function readRegistry() {
     }
     const e = item;
     const name = typeof e.name === "string" ? e.name : "";
-    const path6 = 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 (path6.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: path6,
+      path: path7,
       registered_at: typeof e.registered_at === "string" ? e.registered_at : ""
     };
   });
 }
 async function writeRegistry(entries) {
-  const path5 = getRegistryPath();
-  await mkdir(dirname3(path5), { recursive: true });
+  const path6 = getRegistryPath();
+  await mkdir(dirname3(path6), { recursive: true });
   const body = `${JSON.stringify(entries, null, 2)}
 `;
-  const tmpPath = `${path5}.tmp`;
+  const tmpPath = `${path6}.tmp`;
   await writeFile(tmpPath, body, "utf8");
-  await rename(tmpPath, path5);
+  await rename(tmpPath, path6);
 }
 function pathsEqual(a, b) {
   if (process.platform === "darwin" || process.platform === "win32") {
@@ -366,15 +366,15 @@ async function initWiki(options) {
   return { entry, almanacDir, created: !alreadyExisted };
 }
 async function ensureGitignoreHasIndexDb(cwd) {
-  const path5 = 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(path5)) {
-    existing = await readFile3(path5, "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));
@@ -384,7 +384,7 @@ async function ensureGitignoreHasIndexDb(cwd) {
 ${missing.join("\n")}
 `;
   const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-  await writeFile2(path5, `${existing}${sep}${block}`, "utf8");
+  await writeFile2(path6, `${existing}${sep}${block}`, "utf8");
 }
 function starterReadme() {
   return `# Wiki
@@ -808,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
     };
   }
@@ -987,8 +987,8 @@ async function filterTranscriptsByCwd(transcripts, repoRoot) {
   }
   return hits;
 }
-async function readHead(path5, bytes) {
-  const content = await readFile4(path5, "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) {
@@ -1060,278 +1060,174 @@ function closeStream2(stream) {
   });
 }
 
-// src/commands/hook.ts
+// 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");
+  }
+  db.pragma("foreign_keys = ON");
+  const rawVersion = db.pragma("user_version", { simple: true });
+  const currentVersion = typeof rawVersion === "number" ? rawVersion : 0;
+  if (currentVersion < SCHEMA_VERSION) {
+    db.exec("DROP TABLE IF EXISTS file_refs");
+    try {
+      db.exec("UPDATE pages SET content_hash = ''");
+    } catch {
+    }
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+  }
+  db.exec(SCHEMA_DDL);
+  return db;
+}
+
+// src/commands/health.ts
+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";
+
+// src/indexer/duration.ts
+function parseDuration(input) {
+  const trimmed = input.trim();
+  const m = trimmed.match(/^(\d+)([mhdw])$/);
+  if (m === null) {
+    throw new Error(
+      `invalid duration "${input}" (expected Nw, Nd, Nh, or Nm \u2014 e.g. 2w, 30d)`
+    );
+  }
+  const n = Number.parseInt(m[1] ?? "0", 10);
+  const unit = m[2];
+  switch (unit) {
+    case "m":
+      return n * 60;
+    case "h":
+      return n * 60 * 60;
+    case "d":
+      return n * 60 * 60 * 24;
+    case "w":
+      return n * 60 * 60 * 24 * 7;
+    default:
+      throw new Error(`invalid duration unit "${unit ?? ""}"`);
+  }
+}
+
+// src/indexer/index.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync as 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 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 };
+import { dirname as dirname4 } from "path";
+import yaml2 from "js-yaml";
+async function loadTopicsFile(path6) {
+  if (!existsSync6(path6)) {
+    return { topics: [] };
   }
-  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
-    };
+  let raw;
+  try {
+    raw = await readFile5(path6, "utf8");
+  } catch (err) {
+    if (isNodeError2(err) && err.code === "ENOENT") {
+      return { topics: [] };
+    }
+    throw err;
   }
-  if (ourEntries.length > 0 && stale.length === 0) {
-    return {
-      stdout: `almanac: SessionEnd hook already installed at ${script.path}
-`,
-      stderr: "",
-      exitCode: 0
-    };
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { topics: [] };
   }
-  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
-    };
+  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}`);
   }
-  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 (parsed === null || parsed === void 0) {
+    return { topics: [] };
   }
-  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;
-    }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`topics.yaml at ${path6} must be a mapping`);
   }
-  await writeSettings(settingsPath, settings);
-  return {
-    stdout: `almanac: SessionEnd hook removed
-`,
-    stderr: "",
-    exitCode: 0
-  };
-}
-async function runHookStatus(options = {}) {
-  const script = resolveHookScriptPath(options);
-  const settingsPath = resolveSettingsPath(options);
-  if (!existsSync6(settingsPath)) {
-    return {
-      stdout: `SessionEnd hook: not installed
-settings: ${settingsPath} (does not exist)
-` + (script.ok ? `script would be: ${script.path}
-` : ""),
-      stderr: "",
-      exitCode: 0
-    };
-  }
-  const settings = await readSettings(settingsPath);
-  const existing = settings.hooks?.SessionEnd ?? [];
-  const ours = existing.find((e) => e.command.endsWith("almanac-capture.sh"));
-  if (ours === void 0) {
-    const foreign = existing.map((e) => `  - ${e.command}`).join("\n");
-    return {
-      stdout: `SessionEnd hook: not installed
-settings: ${settingsPath}
-` + (existing.length > 0 ? `(${existing.length} foreign entr${existing.length === 1 ? "y" : "ies"} present:
-${foreign})
-` : "") + (script.ok ? `script would be: ${script.path}
-` : ""),
-      stderr: "",
-      exitCode: 0
-    };
-  }
-  return {
-    stdout: `SessionEnd hook: installed
-script: ${ours.command}
-settings: ${settingsPath}
-`,
-    stderr: "",
-    exitCode: 0
-  };
-}
-function resolveSettingsPath(options) {
-  if (options.settingsPath !== void 0) return options.settingsPath;
-  return path2.join(homedir3(), ".claude", "settings.json");
-}
-function resolveHookScriptPath(options) {
-  if (options.hookScriptPath !== void 0) {
-    return { ok: true, path: options.hookScriptPath };
-  }
-  const here = path2.dirname(fileURLToPath2(import.meta.url));
-  const candidates = [
-    // Bundled: `.../codealmanac/dist/codealmanac.js` → `../hooks/…`
-    path2.resolve(here, "..", "hooks", "almanac-capture.sh"),
-    // Source: `.../codealmanac/src/commands/hook.ts` → `../../hooks/…`
-    path2.resolve(here, "..", "..", "hooks", "almanac-capture.sh"),
-    // Defensive nested fallback.
-    path2.resolve(here, "..", "..", "..", "hooks", "almanac-capture.sh")
-  ];
-  for (const candidate of candidates) {
-    if (existsSync6(candidate)) {
-      return { ok: true, path: candidate };
-    }
-  }
-  return {
-    ok: false,
-    error: `could not locate hooks/almanac-capture.sh. Tried:
-` + candidates.map((c) => `  - ${c}`).join("\n")
-  };
-}
-async function readSettings(settingsPath) {
-  if (!existsSync6(settingsPath)) return {};
-  try {
-    const raw = await readFile5(settingsPath, "utf8");
-    if (raw.trim().length === 0) return {};
-    const parsed = JSON.parse(raw);
-    if (parsed === null || typeof parsed !== "object") return {};
-    return parsed;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`failed to read ${settingsPath}: ${msg}`);
-  }
-}
-async function writeSettings(settingsPath, settings) {
-  const dir = path2.dirname(settingsPath);
-  await mkdir3(dir, { recursive: true });
-  const tmp = `${settingsPath}.almanac-tmp-${process.pid}`;
-  const body = `${JSON.stringify(settings, null, 2)}
-`;
-  await writeFile3(tmp, body, "utf8");
-  await rename2(tmp, settingsPath);
-}
-
-// src/commands/health.ts
-import { existsSync as existsSync10 } from "fs";
-import { readFile as readFile8 } from "fs/promises";
-import { basename as basename4, join as join8 } from "path";
-import fg2 from "fast-glob";
-
-// src/indexer/duration.ts
-function parseDuration(input) {
-  const trimmed = input.trim();
-  const m = trimmed.match(/^(\d+)([mhdw])$/);
-  if (m === null) {
-    throw new Error(
-      `invalid duration "${input}" (expected Nw, Nd, Nh, or Nm \u2014 e.g. 2w, 30d)`
-    );
-  }
-  const n = Number.parseInt(m[1] ?? "0", 10);
-  const unit = m[2];
-  switch (unit) {
-    case "m":
-      return n * 60;
-    case "h":
-      return n * 60 * 60;
-    case "d":
-      return n * 60 * 60 * 24;
-    case "w":
-      return n * 60 * 60 * 24 * 7;
-    default:
-      throw new Error(`invalid duration unit "${unit ?? ""}"`);
-  }
-}
-
-// src/indexer/index.ts
-import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync8, statSync as statSync2 } from "fs";
-import { readFile as readFile7, utimes } from "fs/promises";
-import { basename as basename3, join as join6, relative as relative3 } from "path";
-import fg from "fast-glob";
-
-// src/topics/yaml.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir4, readFile as readFile6, rename as rename3, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname4 } from "path";
-import yaml2 from "js-yaml";
-async function loadTopicsFile(path5) {
-  if (!existsSync7(path5)) {
-    return { topics: [] };
-  }
-  let raw;
-  try {
-    raw = await readFile6(path5, "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 ${path5} 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 ${path5} must be a mapping`);
-  }
-  const obj = parsed;
-  const rawTopics = obj.topics;
-  if (rawTopics === void 0 || rawTopics === null) {
-    return { topics: [] };
+  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 ${path5} \u2014 "topics" must be a list`);
+    throw new Error(`topics.yaml at ${path6} \u2014 "topics" must be a list`);
   }
   const topics = [];
   for (const item of rawTopics) {
@@ -1360,7 +1256,7 @@ async function loadTopicsFile(path5) {
   }
   return { topics };
 }
-async function writeTopicsFile(path5, file) {
+async function writeTopicsFile(path6, file) {
   const sorted = [...file.topics].sort((a, b) => a.slug.localeCompare(b.slug));
   const doc = {
     topics: sorted.map((t) => {
@@ -1385,13 +1281,13 @@ async function writeTopicsFile(path5, file) {
     sortKeys: false
   });
   const content = `${header}${body}`;
-  const tmpPath = `${path5}.tmp`;
-  const parent = dirname4(path5);
-  if (!existsSync7(parent)) {
-    await mkdir4(parent, { recursive: true });
+  const tmpPath = `${path6}.tmp`;
+  const parent = dirname4(path6);
+  if (!existsSync6(parent)) {
+    await mkdir3(parent, { recursive: true });
   }
-  await writeFile4(tmpPath, content, "utf8");
-  await rename3(tmpPath, path5);
+  await writeFile3(tmpPath, content, "utf8");
+  await rename2(tmpPath, path6);
 }
 function findTopic(file, slug) {
   for (const t of file.topics) {
@@ -1443,87 +1339,6 @@ function looksLikeDir(raw) {
   return s.endsWith("/");
 }
 
-// src/indexer/schema.ts
-import Database from "better-sqlite3";
-var SCHEMA_DDL = `
-CREATE TABLE IF NOT EXISTS pages (
-  slug          TEXT PRIMARY KEY,
-  title         TEXT,
-  file_path     TEXT NOT NULL,
-  content_hash  TEXT NOT NULL,
-  updated_at    INTEGER NOT NULL,
-  archived_at   INTEGER,
-  superseded_by TEXT
-);
-
-CREATE TABLE IF NOT EXISTS topics (
-  slug        TEXT PRIMARY KEY,
-  title       TEXT,
-  description TEXT
-);
-
-CREATE TABLE IF NOT EXISTS page_topics (
-  page_slug  TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
-  topic_slug TEXT NOT NULL,
-  PRIMARY KEY (page_slug, topic_slug)
-);
-
-CREATE TABLE IF NOT EXISTS topic_parents (
-  child_slug  TEXT NOT NULL,
-  parent_slug TEXT NOT NULL,
-  PRIMARY KEY (child_slug, parent_slug),
-  CHECK (child_slug != parent_slug)
-);
-
-CREATE TABLE IF NOT EXISTS file_refs (
-  page_slug     TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
-  path          TEXT NOT NULL,
-  original_path TEXT NOT NULL,
-  is_dir        INTEGER NOT NULL,
-  PRIMARY KEY (page_slug, path)
-);
-CREATE INDEX IF NOT EXISTS idx_file_refs_path ON file_refs(path);
-
-CREATE TABLE IF NOT EXISTS wikilinks (
-  source_slug TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
-  target_slug TEXT NOT NULL,
-  PRIMARY KEY (source_slug, target_slug)
-);
-
-CREATE TABLE IF NOT EXISTS cross_wiki_links (
-  source_slug TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
-  target_wiki TEXT NOT NULL,
-  target_slug TEXT NOT NULL,
-  PRIMARY KEY (source_slug, target_wiki, target_slug)
-);
-
--- NOTE: virtual FTS5 table \u2014 ON DELETE CASCADE from pages does NOT apply.
--- The indexer must explicitly DELETE FROM fts_pages whenever it removes
--- or replaces a page row, or we leak orphaned FTS rows.
-CREATE VIRTUAL TABLE IF NOT EXISTS fts_pages USING fts5(slug, title, content);
-`;
-var SCHEMA_VERSION = 2;
-function openIndex(dbPath) {
-  const db = new Database(dbPath);
-  const mode = db.pragma("journal_mode", { simple: true });
-  if (typeof mode !== "string" || mode.toLowerCase() !== "wal") {
-    db.pragma("journal_mode = WAL");
-  }
-  db.pragma("foreign_keys = ON");
-  const rawVersion = db.pragma("user_version", { simple: true });
-  const currentVersion = typeof rawVersion === "number" ? rawVersion : 0;
-  if (currentVersion < SCHEMA_VERSION) {
-    db.exec("DROP TABLE IF EXISTS file_refs");
-    try {
-      db.exec("UPDATE pages SET content_hash = ''");
-    } catch {
-    }
-    db.pragma(`user_version = ${SCHEMA_VERSION}`);
-  }
-  db.exec(SCHEMA_DDL);
-  return db;
-}
-
 // src/indexer/wikilinks.ts
 function classifyWikilink(raw) {
   const pipe = raw.indexOf("|");
@@ -1540,10 +1355,10 @@ function classifyWikilink(raw) {
   }
   if (firstSlash !== -1) {
     const isDir = looksLikeDir(body);
-    const path5 = normalizePath(body, isDir);
+    const path6 = normalizePath(body, isDir);
     const originalPath = normalizePathPreservingCase(body, isDir);
-    if (path5.length === 0) return null;
-    return isDir ? { kind: "folder", path: path5, originalPath } : { kind: "file", path: path5, originalPath };
+    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;
@@ -1567,12 +1382,12 @@ async function ensureFreshIndex(ctx) {
   const almanacDir = join6(ctx.repoRoot, ".almanac");
   const dbPath = join6(almanacDir, "index.db");
   const pagesDir = join6(almanacDir, "pages");
-  if (!existsSync8(pagesDir)) {
+  if (!existsSync7(pagesDir)) {
     const db = openIndex(dbPath);
     db.close();
     return emptyResult();
   }
-  if (!existsSync8(dbPath) || pagesNewerThan(pagesDir, dbPath) || topicsYamlNewerThan(almanacDir, dbPath)) {
+  if (!existsSync7(dbPath) || pagesNewerThan(pagesDir, dbPath) || topicsYamlNewerThan(almanacDir, dbPath)) {
     return runIndexer(ctx);
   }
   return emptyResult();
@@ -1649,7 +1464,7 @@ async function indexPagesInto(db, pagesDir) {
     let raw;
     try {
       st = statSync2(fullPath);
-      raw = await readFile7(fullPath, "utf8");
+      raw = await readFile6(fullPath, "utf8");
     } catch (err) {
       if (err instanceof Error && "code" in err && (err.code === "ENOENT" || err.code === "EACCES")) {
         process.stderr.write(
@@ -1763,10 +1578,10 @@ async function indexPagesInto(db, pagesDir) {
       }
       for (const raw of p.frontmatterFiles) {
         const isDir = looksLikeDir(raw);
-        const path5 = normalizePath(raw, isDir);
+        const path6 = normalizePath(raw, isDir);
         const originalPath = normalizePathPreservingCase(raw, isDir);
-        if (path5.length === 0) continue;
-        insertFileRef.run(p.slug, path5, originalPath, isDir ? 1 : 0);
+        if (path6.length === 0) continue;
+        insertFileRef.run(p.slug, path6, originalPath, isDir ? 1 : 0);
       }
       for (const ref of p.wikilinks) {
         switch (ref.kind) {
@@ -1822,8 +1637,8 @@ function hashContent(raw) {
   return createHash2("sha256").update(raw).digest("hex");
 }
 function topicsYamlNewerThan(almanacDir, dbPath) {
-  const path5 = join6(almanacDir, "topics.yaml");
-  if (!existsSync8(path5)) return false;
+  const path6 = join6(almanacDir, "topics.yaml");
+  if (!existsSync7(path6)) return false;
   let dbMtime;
   try {
     dbMtime = statSync2(dbPath).mtimeMs;
@@ -1831,14 +1646,14 @@ function topicsYamlNewerThan(almanacDir, dbPath) {
     return true;
   }
   try {
-    const st = statSync2(path5);
+    const st = statSync2(path6);
     return st.mtimeMs > dbMtime;
   } catch {
     return false;
   }
 }
 async function applyTopicsYaml(db, topicsYamlPath2) {
-  if (!existsSync8(topicsYamlPath2)) return;
+  if (!existsSync7(topicsYamlPath2)) return;
   let file;
   try {
     file = await loadTopicsFile(topicsYamlPath2);
@@ -1894,7 +1709,7 @@ async function applyTopicsYaml(db, topicsYamlPath2) {
 }
 
 // src/indexer/resolveWiki.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 import { join as join7 } from "path";
 async function resolveWikiRoot(params) {
   if (params.wiki !== void 0) {
@@ -1902,7 +1717,7 @@ async function resolveWikiRoot(params) {
     if (entry === null) {
       throw new Error(`no registered wiki named "${params.wiki}"`);
     }
-    if (!existsSync9(join7(entry.path, ".almanac"))) {
+    if (!existsSync8(join7(entry.path, ".almanac"))) {
       throw new Error(
         `wiki "${params.wiki}" path is unreachable (${entry.path})`
       );
@@ -1912,7 +1727,7 @@ async function resolveWikiRoot(params) {
   const nearest = findNearestAlmanacDir(params.cwd);
   if (nearest === null) {
     throw new Error(
-      "no .almanac/ found in this directory or any parent; run `almanac init` first"
+      "no .almanac/ found in this directory or any parent; run `almanac bootstrap` first"
     );
   }
   return nearest;
@@ -2068,7 +1883,7 @@ async function findDeadRefs(db, scope, repoRoot) {
   for (const r of rows) {
     if (!inPageScope(scope, r.slug)) continue;
     const abs = join8(repoRoot, r.original_path);
-    if (!existsSync10(abs)) {
+    if (!existsSync9(abs)) {
       out.push({ slug: r.slug, path: r.original_path });
     }
   }
@@ -2103,7 +1918,7 @@ async function findBrokenXwiki(db, scope) {
     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"));
+      ok = entry !== null && existsSync9(join8(entry.path, ".almanac"));
       reachableCache.set(r.target_wiki, ok);
     }
     if (!ok) {
@@ -2138,7 +1953,7 @@ async function findEmptyPages(db, scope, pagesDir) {
     if (!inPageScope(scope, r.slug)) continue;
     let raw;
     try {
-      raw = await readFile8(r.file_path, "utf8");
+      raw = await readFile7(r.file_path, "utf8");
     } catch {
       continue;
     }
@@ -2158,7 +1973,7 @@ async function findEmptyPages(db, scope, pagesDir) {
   return out;
 }
 async function findSlugCollisions(pagesDir) {
-  if (!existsSync10(pagesDir)) return [];
+  if (!existsSync9(pagesDir)) return [];
   const files = await fg2("**/*.md", {
     cwd: pagesDir,
     absolute: false,
@@ -2253,259 +2068,212 @@ function section(label, count, lines) {
 ${lines.join("\n")}`;
 }
 
-// src/commands/list.ts
+// src/commands/setup.ts
 import { existsSync as existsSync11 } from "fs";
-async function listWikis(options) {
-  if (options.drop !== void 0) {
-    return handleDrop(options.drop);
-  }
-  const entries = await readRegistry();
-  const reachable = entries.filter((e) => isReachable(e));
-  if (options.json === true) {
-    return { stdout: `${JSON.stringify(reachable, null, 2)}
-`, exitCode: 0 };
+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 };
   }
-  return { stdout: formatPretty(reachable), exitCode: 0 };
-}
-async function handleDrop(name) {
-  const removed = await dropEntry(name);
-  if (removed === null) {
-    return {
-      stdout: `no registry entry named "${name}"
+  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: `removed "${removed.name}" (${removed.path})
+    stdout: `almanac: SessionEnd hook installed
+  script: ${script.path}
+  settings: ${settingsPath}
 `,
+    stderr: "",
     exitCode: 0
   };
 }
-function isReachable(entry) {
-  if (entry.path.length === 0) return false;
-  return existsSync11(entry.path);
-}
-function formatPretty(entries) {
-  if (entries.length === 0) {
-    return "no wikis registered. run `almanac init` in a repo to create one.\n";
+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 nameWidth = Math.min(
-    30,
-    entries.reduce((w, e) => Math.max(w, e.name.length), 0)
-  );
-  const lines = [];
-  for (const entry of entries) {
-    const name = entry.name.padEnd(nameWidth);
-    const desc = entry.description.length > 0 ? entry.description : "\u2014";
-    lines.push(`${name}  ${desc}`);
-    lines.push(`${" ".repeat(nameWidth)}  ${entry.path}`);
+  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
+    };
   }
-  return `${lines.join("\n")}
-`;
-}
-
-// src/commands/reindex.ts
-async function runReindex(options) {
-  const repoRoot = await resolveWikiRoot({
-    cwd: options.cwd,
-    wiki: options.wiki
-  });
-  const result = await runIndexer({ repoRoot });
-  const skipSuffix = result.filesSkipped > 0 ? `; ${result.filesSkipped} skipped` : "";
-  const stdout = `reindexed: ${result.pagesIndexed} page${result.pagesIndexed === 1 ? "" : "s"} (${result.changed} updated, ${result.removed} removed${skipSuffix})
-`;
-  return { result, stdout, exitCode: 0 };
-}
-
-// src/commands/search.ts
-import { join as join9 } from "path";
-async function runSearch(options) {
-  const repoRoot = await resolveWikiRoot({
-    cwd: options.cwd,
-    wiki: options.wiki
-  });
-  await ensureFreshIndex({ repoRoot });
-  const dbPath = join9(repoRoot, ".almanac", "index.db");
-  const db = openIndex(dbPath);
-  try {
-    const rows = executeQuery(db, options);
-    const limited = options.limit !== void 0 && options.limit >= 0 ? rows.slice(0, options.limit) : rows;
-    const stdout = formatResults(limited, options);
-    const stderr = buildStderr(limited, options);
-    return { stdout, stderr, exitCode: 0 };
-  } finally {
-    db.close();
+  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
+  };
 }
-function executeQuery(db, options) {
-  const whereClauses = [];
-  const params = [];
-  if (options.archived === true) {
-    whereClauses.push("p.archived_at IS NOT NULL");
-  } else if (options.includeArchive !== true) {
-    whereClauses.push("p.archived_at IS NULL");
+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
+    };
   }
-  for (const rawTopic of options.topics) {
-    const topicSlug = slugForTopic(rawTopic);
-    if (topicSlug.length === 0) continue;
-    whereClauses.push(
-      "EXISTS (SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug AND pt.topic_slug = ?)"
-    );
-    params.push(topicSlug);
+  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
+    };
   }
-  if (options.mentions !== void 0 && options.mentions.length > 0) {
-    const isDir = looksLikeDir(options.mentions);
-    const norm = normalizePath(options.mentions, isDir);
-    if (isDir) {
-      const escaped = escapeGlobMeta(norm);
-      whereClauses.push(
-        `EXISTS (
-           SELECT 1 FROM file_refs r
-           WHERE r.page_slug = p.slug
-             AND (r.path = ? OR r.path GLOB ?)
-         )`
-      );
-      params.push(norm, `${escaped}*`);
-    } else {
-      const prefixes = parentFolderPrefixes(norm);
-      if (prefixes.length === 0) {
-        whereClauses.push(
-          `EXISTS (
-             SELECT 1 FROM file_refs r
-             WHERE r.page_slug = p.slug AND r.path = ?
-           )`
-        );
-        params.push(norm);
-      } else {
-        const placeholders = prefixes.map(() => "?").join(", ");
-        whereClauses.push(
-          `EXISTS (
-             SELECT 1 FROM file_refs r
-             WHERE r.page_slug = p.slug
-               AND (
-                 r.path = ?
-                 OR (r.is_dir = 1 AND r.path IN (${placeholders}))
-               )
-           )`
-        );
-        params.push(norm, ...prefixes);
-      }
+  return {
+    stdout: `SessionEnd hook: installed
+script: ${ours.command}
+settings: ${settingsPath}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+function resolveSettingsPath(options) {
+  if (options.settingsPath !== void 0) return options.settingsPath;
+  return path2.join(homedir3(), ".claude", "settings.json");
+}
+function resolveHookScriptPath(options) {
+  if (options.hookScriptPath !== void 0) {
+    return { ok: true, path: options.hookScriptPath };
+  }
+  const here = path2.dirname(fileURLToPath2(import.meta.url));
+  const candidates = [
+    // Bundled: `.../codealmanac/dist/codealmanac.js` → `../hooks/…`
+    path2.resolve(here, "..", "hooks", "almanac-capture.sh"),
+    // Source: `.../codealmanac/src/commands/hook.ts` → `../../hooks/…`
+    path2.resolve(here, "..", "..", "hooks", "almanac-capture.sh"),
+    // Defensive nested fallback.
+    path2.resolve(here, "..", "..", "..", "hooks", "almanac-capture.sh")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync10(candidate)) {
+      return { ok: true, path: candidate };
     }
   }
-  const now = Math.floor(Date.now() / 1e3);
-  if (options.since !== void 0) {
-    const seconds = parseDuration(options.since);
-    whereClauses.push("p.updated_at >= ?");
-    params.push(now - seconds);
+  return {
+    ok: false,
+    error: `could not locate hooks/almanac-capture.sh. Tried:
+` + candidates.map((c) => `  - ${c}`).join("\n")
+  };
+}
+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}`);
   }
-  if (options.stale !== void 0) {
-    const seconds = parseDuration(options.stale);
-    whereClauses.push("p.updated_at < ?");
-    params.push(now - seconds);
-  }
-  if (options.orphan === true) {
-    whereClauses.push(
-      "NOT EXISTS (SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug)"
-    );
-  }
-  let sql;
-  if (options.query !== void 0 && options.query.trim().length > 0) {
-    const ftsExpr = buildFtsQuery(options.query);
-    sql = `
-      SELECT p.slug, p.title, p.updated_at, p.archived_at, p.superseded_by
-      FROM pages p
-      JOIN fts_pages f ON f.slug = p.slug
-      WHERE fts_pages MATCH ?
-        ${whereClauses.length > 0 ? `AND ${whereClauses.join(" AND ")}` : ""}
-      ORDER BY f.rank ASC, p.updated_at DESC, p.slug ASC
-    `;
-    params.unshift(ftsExpr);
-  } else {
-    sql = buildSql(whereClauses);
-  }
-  const rows = db.prepare(sql).all(...params);
-  const topicStmt = db.prepare(
-    "SELECT topic_slug FROM page_topics WHERE page_slug = ? ORDER BY topic_slug"
-  );
-  const out = rows.map((row) => ({
-    slug: row.slug,
-    title: row.title,
-    updated_at: row.updated_at,
-    archived_at: row.archived_at,
-    superseded_by: row.superseded_by,
-    topics: topicStmt.all(row.slug).map((t) => t.topic_slug)
-  }));
-  return out;
-}
-function buildSql(whereClauses) {
-  const where = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
-  return `
-    SELECT p.slug, p.title, p.updated_at, p.archived_at, p.superseded_by
-    FROM pages p
-    ${where}
-    ORDER BY p.updated_at DESC, p.slug ASC
-  `;
-}
-function buildFtsQuery(raw) {
-  const trimmed = raw.trim();
-  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
-    const inner = trimmed.slice(1, -1).toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
-    if (inner.length === 0) return '""';
-    return `"${inner}"`;
-  }
-  const tokens = trimmed.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
-  if (tokens.length === 0) return '""';
-  return tokens.map((t) => `${t}*`).join(" AND ");
-}
-function slugForTopic(raw) {
-  return raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-}
-function parentFolderPrefixes(filePath) {
-  const out = [];
-  let cursor = 0;
-  while (true) {
-    const next = filePath.indexOf("/", cursor);
-    if (next === -1) break;
-    out.push(filePath.slice(0, next + 1));
-    cursor = next + 1;
-  }
-  return out;
-}
-function escapeGlobMeta(s) {
-  return s.replace(/[\*\?\[]/g, (ch) => `[${ch}]`);
-}
-function formatResults(rows, options) {
-  if (options.json === true) {
-    return `${JSON.stringify(rows, null, 2)}
-`;
-  }
-  if (rows.length === 0) return "";
-  return `${rows.map((r) => r.slug).join("\n")}
-`;
 }
-function buildStderr(rows, options) {
-  if (options.json === true) return "";
-  if (options.limit !== void 0) return "";
-  if (rows.length > 50) {
-    return `almanac: ${rows.length} results \u2014 consider --limit or a narrower query
+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)}
 `;
-  }
-  return "";
+  await writeFile4(tmp, body, "utf8");
+  await rename3(tmp, settingsPath);
 }
 
 // src/commands/setup.ts
-import { existsSync as existsSync12 } 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";
 var RST = "\x1B[0m";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
@@ -2563,6 +2331,12 @@ 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);
@@ -2649,147 +2423,859 @@ function reportAuth(out, auth) {
     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;
+  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;
+  }
+  stepActive(out, `Claude auth: ${DIM}not signed in${RST}`);
+  for (const line of UNAUTHENTICATED_MESSAGE.split("\n")) {
+    out.write(`  ${DIM}\u2502   ${line}${RST}
+`);
+  }
+}
+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 {
+    }
+  }
+  await copyFile(src, dest);
+  return true;
+}
+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`)
+  );
+  out.write(
+    row(
+      `  ${BLUE}2.${RST}  ${BOLD}almanac bootstrap${RST}  ${DIM}# scaffold the wiki${RST}`
+    )
+  );
+  out.write(
+    row(
+      `  ${BLUE}3.${RST}  Work normally \u2014 capture runs on session end`
+    )
+  );
+  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")
+  );
+}
+function looksLikeGuidesDir(dir) {
+  return existsSync11(path3.join(dir, "mini.md"));
+}
+
+// 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
+  });
+  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 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 {
+        status: "problem",
+        key: "install.hook",
+        message: "SessionEnd hook not installed",
+        fix: "run: almanac setup --yes"
+      };
+    }
+    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"
+      };
+    }
+    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 {
+      checks.push({
+        status: "problem",
+        key: "wiki.health",
+        message: `almanac health reports ${problems} problem${problems === 1 ? "" : "s"}`,
+        fix: "run: almanac health"
+      });
+    }
+  } 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 {
+      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"
+    };
+  }
+  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 {
+    status: "info",
+    key: "wiki.capture",
+    message: `last capture: ${formatDuration(age)} ago (${latest.name})`
+  };
+}
+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;
+  }
+}
+function detectInstallPath() {
+  try {
+    const entry = req.resolve("codealmanac");
+    return path4.dirname(path4.dirname(entry));
+  } catch {
+    return null;
+  }
+}
+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 };
+  }
+}
+async function safeCheckAuth2(spawnCli) {
+  try {
+    return await checkClaudeAuth(spawnCli);
+  } catch {
+    return { loggedIn: false };
+  }
+}
+function readPackageVersion() {
+  try {
+    const pkg = req("../../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  try {
+    const pkg = req("../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  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 existsSync13 } from "fs";
+async function listWikis(options) {
+  if (options.drop !== void 0) {
+    return handleDrop(options.drop);
+  }
+  const entries = await readRegistry();
+  const reachable = entries.filter((e) => isReachable(e));
+  if (options.json === true) {
+    return { stdout: `${JSON.stringify(reachable, null, 2)}
+`, exitCode: 0 };
+  }
+  return { stdout: formatPretty(reachable), exitCode: 0 };
+}
+async function handleDrop(name) {
+  const removed = await dropEntry(name);
+  if (removed === null) {
+    return {
+      stdout: `no registry entry named "${name}"
+`,
+      exitCode: 1
+    };
+  }
+  return {
+    stdout: `removed "${removed.name}" (${removed.path})
+`,
+    exitCode: 0
+  };
+}
+function isReachable(entry) {
+  if (entry.path.length === 0) return false;
+  return existsSync13(entry.path);
+}
+function formatPretty(entries) {
+  if (entries.length === 0) {
+    return "no wikis registered. run `almanac bootstrap` in a repo to create one.\n";
+  }
+  const nameWidth = Math.min(
+    30,
+    entries.reduce((w, e) => Math.max(w, e.name.length), 0)
+  );
+  const lines = [];
+  for (const entry of entries) {
+    const name = entry.name.padEnd(nameWidth);
+    const desc = entry.description.length > 0 ? entry.description : "\u2014";
+    lines.push(`${name}  ${desc}`);
+    lines.push(`${" ".repeat(nameWidth)}  ${entry.path}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/reindex.ts
+async function runReindex(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  const result = await runIndexer({ repoRoot });
+  const skipSuffix = result.filesSkipped > 0 ? `; ${result.filesSkipped} skipped` : "";
+  const stdout = `reindexed: ${result.pagesIndexed} page${result.pagesIndexed === 1 ? "" : "s"} (${result.changed} updated, ${result.removed} removed${skipSuffix})
+`;
+  return { result, stdout, exitCode: 0 };
+}
+
+// src/commands/search.ts
+import { join as join9 } from "path";
+async function runSearch(options) {
+  const repoRoot = await resolveWikiRoot({
+    cwd: options.cwd,
+    wiki: options.wiki
+  });
+  await ensureFreshIndex({ repoRoot });
+  const dbPath = join9(repoRoot, ".almanac", "index.db");
+  const db = openIndex(dbPath);
+  try {
+    const rows = executeQuery(db, options);
+    const limited = options.limit !== void 0 && options.limit >= 0 ? rows.slice(0, options.limit) : rows;
+    const stdout = formatResults(limited, options);
+    const stderr = buildStderr(limited, options);
+    return { stdout, stderr, exitCode: 0 };
+  } finally {
+    db.close();
+  }
+}
+function executeQuery(db, options) {
+  const whereClauses = [];
+  const params = [];
+  if (options.archived === true) {
+    whereClauses.push("p.archived_at IS NOT NULL");
+  } else if (options.includeArchive !== true) {
+    whereClauses.push("p.archived_at IS NULL");
+  }
+  for (const rawTopic of options.topics) {
+    const topicSlug = slugForTopic(rawTopic);
+    if (topicSlug.length === 0) continue;
+    whereClauses.push(
+      "EXISTS (SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug AND pt.topic_slug = ?)"
+    );
+    params.push(topicSlug);
+  }
+  if (options.mentions !== void 0 && options.mentions.length > 0) {
+    const isDir = looksLikeDir(options.mentions);
+    const norm = normalizePath(options.mentions, isDir);
+    if (isDir) {
+      const escaped = escapeGlobMeta(norm);
+      whereClauses.push(
+        `EXISTS (
+           SELECT 1 FROM file_refs r
+           WHERE r.page_slug = p.slug
+             AND (r.path = ? OR r.path GLOB ?)
+         )`
+      );
+      params.push(norm, `${escaped}*`);
+    } else {
+      const prefixes = parentFolderPrefixes(norm);
+      if (prefixes.length === 0) {
+        whereClauses.push(
+          `EXISTS (
+             SELECT 1 FROM file_refs r
+             WHERE r.page_slug = p.slug AND r.path = ?
+           )`
+        );
+        params.push(norm);
+      } else {
+        const placeholders = prefixes.map(() => "?").join(", ");
+        whereClauses.push(
+          `EXISTS (
+             SELECT 1 FROM file_refs r
+             WHERE r.page_slug = p.slug
+               AND (
+                 r.path = ?
+                 OR (r.is_dir = 1 AND r.path IN (${placeholders}))
+               )
+           )`
+        );
+        params.push(norm, ...prefixes);
+      }
+    }
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (options.since !== void 0) {
+    const seconds = parseDuration(options.since);
+    whereClauses.push("p.updated_at >= ?");
+    params.push(now - seconds);
   }
-  stepActive(out, `Claude auth: ${DIM}not signed in${RST}`);
-  for (const line of UNAUTHENTICATED_MESSAGE.split("\n")) {
-    out.write(`  ${DIM}\u2502   ${line}${RST}
-`);
+  if (options.stale !== void 0) {
+    const seconds = parseDuration(options.stale);
+    whereClauses.push("p.updated_at < ?");
+    params.push(now - seconds);
   }
-}
-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 (!existsSync12(srcMini)) {
-    throw new Error(`missing bundled guide: ${srcMini}`);
+  if (options.orphan === true) {
+    whereClauses.push(
+      "NOT EXISTS (SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug)"
+    );
   }
-  if (!existsSync12(srcRef)) {
-    throw new Error(`missing bundled guide: ${srcRef}`);
+  let sql;
+  if (options.query !== void 0 && options.query.trim().length > 0) {
+    const ftsExpr = buildFtsQuery(options.query);
+    sql = `
+      SELECT p.slug, p.title, p.updated_at, p.archived_at, p.superseded_by
+      FROM pages p
+      JOIN fts_pages f ON f.slug = p.slug
+      WHERE fts_pages MATCH ?
+        ${whereClauses.length > 0 ? `AND ${whereClauses.join(" AND ")}` : ""}
+      ORDER BY f.rank ASC, p.updated_at DESC, p.slug ASC
+    `;
+    params.unshift(ftsExpr);
+  } else {
+    sql = buildSql(whereClauses);
   }
-  const 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 };
+  const rows = db.prepare(sql).all(...params);
+  const topicStmt = db.prepare(
+    "SELECT topic_slug FROM page_topics WHERE page_slug = ? ORDER BY topic_slug"
+  );
+  const out = rows.map((row) => ({
+    slug: row.slug,
+    title: row.title,
+    updated_at: row.updated_at,
+    archived_at: row.archived_at,
+    superseded_by: row.superseded_by,
+    topics: topicStmt.all(row.slug).map((t) => t.topic_slug)
+  }));
+  return out;
 }
-async function copyIfChanged(src, dest) {
-  const srcBytes = await readFile9(src);
-  if (existsSync12(dest)) {
-    try {
-      const destBytes = await readFile9(dest);
-      if (srcBytes.equals(destBytes)) return false;
-    } catch {
-    }
-  }
-  await copyFile(src, dest);
-  return true;
+function buildSql(whereClauses) {
+  const where = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+  return `
+    SELECT p.slug, p.title, p.updated_at, p.archived_at, p.superseded_by
+    FROM pages p
+    ${where}
+    ORDER BY p.updated_at DESC, p.slug ASC
+  `;
 }
-var IMPORT_LINE = "@~/.claude/codealmanac.md";
-async function ensureImport(claudeMdPath) {
-  let existing = "";
-  if (existsSync12(claudeMdPath)) {
-    existing = await readFile9(claudeMdPath, "utf8");
+function buildFtsQuery(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    const inner = trimmed.slice(1, -1).toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    if (inner.length === 0) return '""';
+    return `"${inner}"`;
   }
-  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;
+  const tokens = trimmed.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+  if (tokens.length === 0) return '""';
+  return tokens.map((t) => `${t}*`).join(" AND ");
 }
-function hasImportLine(contents) {
-  const lines = contents.split(/\r?\n/).map((l) => l.trim());
-  return lines.includes(IMPORT_LINE);
+function slugForTopic(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-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 parentFolderPrefixes(filePath) {
+  const out = [];
+  let cursor = 0;
+  while (true) {
+    const next = filePath.indexOf("/", cursor);
+    if (next === -1) break;
+    out.push(filePath.slice(0, next + 1));
+    cursor = next + 1;
+  }
+  return out;
 }
-function 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}
+function escapeGlobMeta(s) {
+  return s.replace(/[\*\?\[]/g, (ch) => `[${ch}]`);
+}
+function formatResults(rows, options) {
+  if (options.json === true) {
+    return `${JSON.stringify(rows, null, 2)}
+`;
+  }
+  if (rows.length === 0) return "";
+  return `${rows.map((r) => r.slug).join("\n")}
 `;
-  };
-  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`)
-  );
-  out.write(
-    row(
-      `  ${BLUE}2.${RST}  ${BOLD}almanac bootstrap${RST}  ${DIM}# scaffold the wiki${RST}`
-    )
-  );
-  out.write(
-    row(
-      `  ${BLUE}3.${RST}  Work normally \u2014 capture runs on session end`
-    )
-  );
-  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;
+function buildStderr(rows, options) {
+  if (options.json === true) return "";
+  if (rows.length === 0) {
+    return "# 0 results\n";
   }
-  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 {
+  if (options.limit !== void 0) return "";
+  if (rows.length > 50) {
+    return `almanac: ${rows.length} results \u2014 consider --limit or a narrower query
+`;
   }
-  throw new Error(
-    "could not locate bundled guides/ directory. Tried:\n" + candidates.map((c) => `  - ${c}`).join("\n")
-  );
-}
-function looksLikeGuidesDir(dir) {
-  return existsSync12(path3.join(dir, "mini.md"));
+  return "";
 }
 
 // src/commands/show.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { join as join10 } from "path";
 async function runShow(options) {
   const repoRoot = await resolveWikiRoot({
@@ -2856,7 +3342,7 @@ async function fetchRecord(db, slug) {
   ).all(slug).map((r) => r.slug);
   let body = "";
   try {
-    body = stripFrontmatter(await readFile10(pageRow.file_path, "utf8"));
+    body = stripFrontmatter(await readFile11(pageRow.file_path, "utf8"));
   } catch {
   }
   return {
@@ -2907,7 +3393,9 @@ function selectedFields(options) {
 }
 function formatRecord(rec, options) {
   if (options.raw === true) {
-    return rec.body;
+    if (rec.body.length === 0) return "";
+    return rec.body.endsWith("\n") ? rec.body : `${rec.body}
+`;
   }
   const fields = selectedFields(options);
   if (fields.length > 0) {
@@ -2975,7 +3463,7 @@ function labeledFields(rec, fields) {
   for (const f of fields) {
     parts.push(labeledSection(rec, f));
   }
-  return parts.join("\n") + (parts.length > 0 ? "" : "");
+  return parts.join("\n");
 }
 function labeledSection(rec, field) {
   switch (field) {
@@ -3075,10 +3563,10 @@ function metadataHeader(rec) {
 }
 function stripFrontmatter(src) {
   if (!src.startsWith("---\n") && !src.startsWith("---\r\n")) return src;
-  const rest = src.slice(src.indexOf("\n") + 1);
-  const endMatch = rest.match(/^---[ \t]*\r?\n/m);
+  const afterOpen = src.replace(/^---\r?\n/, "");
+  const endMatch = afterOpen.match(/^---[ \t]*\r?\n/m);
   if (endMatch === null || endMatch.index === void 0) return src;
-  return rest.slice(endMatch.index + endMatch[0].length);
+  return afterOpen.slice(endMatch.index + endMatch[0].length);
 }
 function firstParagraph(body) {
   let src = body.trimStart();
@@ -3101,10 +3589,10 @@ function collectSlugs(options) {
 }
 
 // src/topics/frontmatterRewrite.ts
-import { readFile as readFile11, rename as rename4, writeFile as writeFile6 } 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 readFile11(filePath, "utf8");
+  const raw = await readFile12(filePath, "utf8");
   const { before, after, output, changed } = applyTopicsTransform(
     raw,
     transform
@@ -3482,7 +3970,7 @@ async function runUntag(options) {
 }
 
 // src/commands/topics.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 import { join as join12 } from "path";
 import fg3 from "fast-glob";
 async function runTopicsList(options) {
@@ -3963,7 +4451,7 @@ async function rewriteTopicOnPages(repoRoot, transform) {
   });
   let changed = 0;
   for (const filePath of files) {
-    const raw = await readFile12(filePath, "utf8");
+    const raw = await readFile13(filePath, "utf8");
     const applied = applyTopicsTransform(raw, transform);
     if (!applied.changed) continue;
     await rewritePageTopics(filePath, transform);
@@ -3973,18 +4461,18 @@ async function rewriteTopicOnPages(repoRoot, transform) {
 }
 
 // src/commands/uninstall.ts
-import { existsSync as existsSync13 } from "fs";
-import { readFile as readFile13, rm, writeFile as writeFile7 } from "fs/promises";
-import { homedir as homedir5 } from "os";
-import path4 from "path";
-var BLUE2 = "\x1B[38;5;75m";
-var DIM2 = "\x1B[2m";
-var RST2 = "\x1B[0m";
+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 ?? path4.join(homedir5(), ".claude");
+  const claudeDir = options.claudeDir ?? path5.join(homedir6(), ".claude");
   out.write("\n");
   let removeHook = true;
   if (options.keepHook === true) {
@@ -4004,10 +4492,10 @@ async function runUninstall(options = {}) {
     if (res.exitCode !== 0) {
       return { stdout: "", stderr: res.stderr, exitCode: res.exitCode };
     }
-    out.write(`  ${BLUE2}\u25C7${RST2}  ${res.stdout.trim()}
+    out.write(`  ${BLUE3}\u25C7${RST3}  ${res.stdout.trim()}
 `);
   } else {
-    out.write(`  ${DIM2}\u25CB  Hook kept${RST2}
+    out.write(`  ${DIM3}\u25CB  Hook kept${RST3}
 `);
   }
   let removeGuides = true;
@@ -4024,38 +4512,38 @@ async function runUninstall(options = {}) {
     const summary = await removeGuideFiles(claudeDir);
     if (summary.anyChanges) {
       out.write(
-        `  ${BLUE2}\u25C7${RST2}  Guides removed (${summary.filesTouched.join(", ")})
+        `  ${BLUE3}\u25C7${RST3}  Guides removed (${summary.filesTouched.join(", ")})
 `
       );
     } else {
-      out.write(`  ${DIM2}\u25CB  Guides not installed${RST2}
+      out.write(`  ${DIM3}\u25CB  Guides not installed${RST3}
 `);
     }
   } else {
-    out.write(`  ${DIM2}\u25CB  Guides kept${RST2}
+    out.write(`  ${DIM3}\u25CB  Guides kept${RST3}
 `);
   }
   out.write(`
-  ${BLUE2}\u25C7${RST2}  ${BLUE2}Uninstall complete${RST2}
+  ${BLUE3}\u25C7${RST3}  ${BLUE3}Uninstall complete${RST3}
 
 `);
   return { stdout: "", stderr: "", exitCode: 0 };
 }
 async function removeGuideFiles(claudeDir) {
   const touched = [];
-  const mini = path4.join(claudeDir, "codealmanac.md");
-  const ref = path4.join(claudeDir, "codealmanac-reference.md");
-  const claudeMd = path4.join(claudeDir, "CLAUDE.md");
-  if (existsSync13(mini)) {
+  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 (existsSync13(ref)) {
+  if (existsSync14(ref)) {
     await rm(ref, { force: true });
     touched.push("codealmanac-reference.md");
   }
-  if (existsSync13(claudeMd)) {
-    const existing = await readFile13(claudeMd, "utf8");
+  if (existsSync14(claudeMd)) {
+    const existing = await readFile14(claudeMd, "utf8");
     const { changed, body } = removeImportLine(existing);
     if (changed) {
       if (body.trim().length === 0) {
@@ -4087,7 +4575,7 @@ function removeImportLine(contents) {
 function confirm2(out, question, defaultYes) {
   return new Promise((resolve2) => {
     const hint = defaultYes ? "[Y/n]" : "[y/N]";
-    out.write(`  ${BLUE2}\u25C6${RST2}  ${question} ${DIM2}${hint}${RST2} `);
+    out.write(`  ${BLUE3}\u25C6${RST3}  ${question} ${DIM3}${hint}${RST3} `);
     let buf = "";
     const onData = (chunk) => {
       buf += chunk.toString("utf8");
@@ -4105,13 +4593,13 @@ function confirm2(out, question, defaultYes) {
 }
 
 // src/registry/autoregister.ts
-import { existsSync as existsSync14 } 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 (!existsSync14(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;
@@ -4161,13 +4649,16 @@ async function run(argv) {
   const program = new Command();
   program.name(programName).description(
     "codealmanac \u2014 a living wiki for codebases, maintained by AI agents"
-  ).version(readPackageVersion(), "-v, --version", "print version");
-  if (programName === "codealmanac" && argv.length === 2) {
-    const result = await runSetup({});
-    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;
+  ).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("find pages by text, topic, file mentions, freshness").option(
     "--topic <name...>",
@@ -4176,7 +4667,7 @@ async function run(argv) {
     []
   ).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)"
@@ -4452,7 +4943,24 @@ async function run(argv) {
       emit(result);
     }
   );
-  program.command("uninstall").description("remove the hook + guides + import line").option("-y, --yes", "skip confirmations; remove everything").option("--keep-hook", "leave the hook alone").option("--keep-guides", "leave the guides + CLAUDE.md import alone").action(
+  program.command("doctor").description("report on the codealmanac install + current wiki health").option("--json", "emit structured JSON").option("--install-only", "report only on the install (skip wiki checks)").option("--wiki-only", "report only on the current wiki (skip install checks)").action(
+    async (opts) => {
+      const result = await runDoctor({
+        cwd: process.cwd(),
+        json: opts.json,
+        installOnly: opts.installOnly,
+        wikiOnly: opts.wikiOnly
+      });
+      emit(result);
+    }
+  );
+  program.command("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,
@@ -4480,7 +4988,7 @@ var HELP_GROUPS = [
   },
   {
     title: "Setup",
-    commands: ["setup", "uninstall"]
+    commands: ["setup", "uninstall", "doctor"]
   }
 ];
 function configureGroupedHelp(program) {
@@ -4581,9 +5089,9 @@ function renderDefault(cmd, helper) {
   }
   return lines.join("\n");
 }
-function readPackageVersion() {
+function readPackageVersion2() {
   try {
-    const require2 = createRequire3(import.meta.url);
+    const require2 = createRequire4(import.meta.url);
     const pkg = require2("../package.json");
     if (typeof pkg.version === "string" && pkg.version.length > 0) {
       return pkg.version;
@@ -4615,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) => {