codealmanac 0.1.1 → 0.1.2

package/dist/codealmanac.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { createRequire as createRequire3 } 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 path5 = getRegistryPath();
   let raw;
   try {
-    raw = await readFile2(path3, "utf8");
+    raw = await readFile2(path5, "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 ${path5} 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 ${path5} 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 path6 = 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 (path6.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: path6,
       registered_at: typeof e.registered_at === "string" ? e.registered_at : ""
     };
   });
 }
 async function writeRegistry(entries) {
-  const path3 = getRegistryPath();
-  await mkdir(dirname3(path3), { recursive: true });
+  const path5 = getRegistryPath();
+  await mkdir(dirname3(path5), { recursive: true });
   const body = `${JSON.stringify(entries, null, 2)}
 `;
-  const tmpPath = `${path3}.tmp`;
+  const tmpPath = `${path5}.tmp`;
   await writeFile(tmpPath, body, "utf8");
-  await rename(tmpPath, path3);
+  await rename(tmpPath, path5);
 }
 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 path5 = 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(path5)) {
+    existing = await readFile3(path5, "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(path5, `${existing}${sep}${block}`, "utf8");
 }
 function starterReadme() {
   return `# Wiki
@@ -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(path5, bytes) {
+  const content = await readFile4(path5, "utf8");
   return content.length > bytes ? content.slice(0, bytes) : content;
 }
 async function snapshotPages(pagesDir) {
@@ -1294,13 +1295,13 @@ import { existsSync as existsSync7 } from "fs";
 import { mkdir as mkdir4, readFile as readFile6, rename as rename3, writeFile as writeFile4 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 import yaml2 from "js-yaml";
-async function loadTopicsFile(path3) {
-  if (!existsSync7(path3)) {
+async function loadTopicsFile(path5) {
+  if (!existsSync7(path5)) {
     return { topics: [] };
   }
   let raw;
   try {
-    raw = await readFile6(path3, "utf8");
+    raw = await readFile6(path5, "utf8");
   } catch (err) {
     if (isNodeError2(err) && err.code === "ENOENT") {
       return { topics: [] };
@@ -1316,13 +1317,13 @@ async function loadTopicsFile(path3) {
     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}`);
+    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 ${path3} must be a mapping`);
+    throw new Error(`topics.yaml at ${path5} must be a mapping`);
   }
   const obj = parsed;
   const rawTopics = obj.topics;
@@ -1330,7 +1331,7 @@ async function loadTopicsFile(path3) {
     return { topics: [] };
   }
   if (!Array.isArray(rawTopics)) {
-    throw new Error(`topics.yaml at ${path3} \u2014 "topics" must be a list`);
+    throw new Error(`topics.yaml at ${path5} \u2014 "topics" must be a list`);
   }
   const topics = [];
   for (const item of rawTopics) {
@@ -1359,7 +1360,7 @@ async function loadTopicsFile(path3) {
   }
   return { topics };
 }
-async function writeTopicsFile(path3, file) {
+async function writeTopicsFile(path5, file) {
   const sorted = [...file.topics].sort((a, b) => a.slug.localeCompare(b.slug));
   const doc = {
     topics: sorted.map((t) => {
@@ -1384,13 +1385,13 @@ async function writeTopicsFile(path3, file) {
     sortKeys: false
   });
   const content = `${header}${body}`;
-  const tmpPath = `${path3}.tmp`;
-  const parent = dirname4(path3);
+  const tmpPath = `${path5}.tmp`;
+  const parent = dirname4(path5);
   if (!existsSync7(parent)) {
     await mkdir4(parent, { recursive: true });
   }
   await writeFile4(tmpPath, content, "utf8");
-  await rename3(tmpPath, path3);
+  await rename3(tmpPath, path5);
 }
 function findTopic(file, slug) {
   for (const t of file.topics) {
@@ -1539,10 +1540,10 @@ function classifyWikilink(raw) {
   }
   if (firstSlash !== -1) {
     const isDir = looksLikeDir(body);
-    const path3 = normalizePath(body, isDir);
+    const path5 = 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 };
+    if (path5.length === 0) return null;
+    return isDir ? { kind: "folder", path: path5, originalPath } : { kind: "file", path: path5, originalPath };
   }
   const target = toKebabCase(body);
   if (target.length === 0) return null;
@@ -1762,10 +1763,10 @@ async function indexPagesInto(db, pagesDir) {
       }
       for (const raw of p.frontmatterFiles) {
         const isDir = looksLikeDir(raw);
-        const path3 = normalizePath(raw, isDir);
+        const path5 = normalizePath(raw, isDir);
         const originalPath = normalizePathPreservingCase(raw, isDir);
-        if (path3.length === 0) continue;
-        insertFileRef.run(p.slug, path3, originalPath, isDir ? 1 : 0);
+        if (path5.length === 0) continue;
+        insertFileRef.run(p.slug, path5, originalPath, isDir ? 1 : 0);
       }
       for (const ref of p.wikilinks) {
         switch (ref.kind) {
@@ -1821,8 +1822,8 @@ 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;
+  const path5 = join6(almanacDir, "topics.yaml");
+  if (!existsSync8(path5)) return false;
   let dbMtime;
   try {
     dbMtime = statSync2(dbPath).mtimeMs;
@@ -1830,7 +1831,7 @@ function topicsYamlNewerThan(almanacDir, dbPath) {
     return true;
   }
   try {
-    const st = statSync2(path3);
+    const st = statSync2(path5);
     return st.mtimeMs > dbMtime;
   } catch {
     return false;
@@ -2252,153 +2253,6 @@ function section(label, count, lines) {
 ${lines.join("\n")}`;
 }
 
-// src/commands/info.ts
-import { join as join9 } from "path";
-async function runInfo(options) {
-  const repoRoot = await resolveWikiRoot({
-    cwd: options.cwd,
-    wiki: options.wiki
-  });
-  await ensureFreshIndex({ repoRoot });
-  const dbPath = join9(repoRoot, ".almanac", "index.db");
-  const db = openIndex(dbPath);
-  try {
-    const slugs = collectSlugs(options);
-    if (slugs.length === 0) {
-      return {
-        stdout: "",
-        stderr: "almanac: info requires a slug (or --stdin)\n",
-        exitCode: 1
-      };
-    }
-    const records = [];
-    const missing = [];
-    for (const slug of slugs) {
-      const rec = fetchInfo(db, slug);
-      if (rec === null) {
-        missing.push(slug);
-        continue;
-      }
-      records.push(rec);
-    }
-    const bulk = options.stdin === true;
-    const jsonOut = options.json === true || bulk;
-    let stdout;
-    if (jsonOut) {
-      if (bulk) {
-        stdout = `${JSON.stringify(records, null, 2)}
-`;
-      } else {
-        const only = records[0] ?? null;
-        stdout = `${JSON.stringify(only, null, 2)}
-`;
-      }
-    } else {
-      stdout = records.map(formatHumanReadable).join("\n");
-    }
-    const stderr = missing.map((s) => `almanac: no such page "${s}"
-`).join("");
-    return {
-      stdout,
-      stderr,
-      exitCode: missing.length > 0 ? 1 : 0
-    };
-  } finally {
-    db.close();
-  }
-}
-function fetchInfo(db, slug) {
-  const pageRow = db.prepare(
-    "SELECT slug, title, file_path, updated_at, archived_at, superseded_by FROM pages WHERE slug = ?"
-  ).get(slug);
-  if (pageRow === void 0) return null;
-  const topics = db.prepare(
-    "SELECT topic_slug FROM page_topics WHERE page_slug = ? ORDER BY topic_slug"
-  ).all(slug).map((r) => r.topic_slug);
-  const refs = db.prepare(
-    // Display the author's casing (`original_path`), not the
-    // lowercased lookup form. The lowercased `path` column is the
-    // query key for `--mentions`; it's not a user-facing string.
-    "SELECT original_path, is_dir FROM file_refs WHERE page_slug = ? ORDER BY original_path"
-  ).all(slug).map((r) => ({ path: r.original_path, is_dir: r.is_dir === 1 }));
-  const linksOut = db.prepare(
-    "SELECT target_slug FROM wikilinks WHERE source_slug = ? ORDER BY target_slug"
-  ).all(slug).map((r) => r.target_slug);
-  const linksIn = db.prepare(
-    "SELECT source_slug FROM wikilinks WHERE target_slug = ? ORDER BY source_slug"
-  ).all(slug).map((r) => r.source_slug);
-  const xwiki = db.prepare(
-    "SELECT target_wiki, target_slug FROM cross_wiki_links WHERE source_slug = ? ORDER BY target_wiki, target_slug"
-  ).all(slug).map((r) => ({ wiki: r.target_wiki, target: r.target_slug }));
-  const supersedesRows = db.prepare(
-    "SELECT slug FROM pages WHERE superseded_by = ? ORDER BY slug"
-  ).all(slug).map((r) => r.slug);
-  return {
-    slug: pageRow.slug,
-    title: pageRow.title,
-    file_path: pageRow.file_path,
-    updated_at: pageRow.updated_at,
-    archived_at: pageRow.archived_at,
-    superseded_by: pageRow.superseded_by,
-    supersedes: supersedesRows,
-    topics,
-    file_refs: refs,
-    wikilinks_out: linksOut,
-    wikilinks_in: linksIn,
-    cross_wiki_links: xwiki
-  };
-}
-function collectSlugs(options) {
-  if (options.stdin === true && options.stdinInput !== void 0) {
-    return options.stdinInput.split(/\r?\n/).map((s) => s.trim()).filter((s) => s.length > 0);
-  }
-  if (options.slug !== void 0 && options.slug.length > 0) {
-    return [options.slug];
-  }
-  return [];
-}
-function formatHumanReadable(rec) {
-  const lines = [];
-  lines.push(`slug:          ${rec.slug}`);
-  lines.push(`title:         ${rec.title ?? "\u2014"}`);
-  lines.push(`file:          ${rec.file_path}`);
-  lines.push(`updated_at:    ${new Date(rec.updated_at * 1e3).toISOString()}`);
-  if (rec.archived_at !== null) {
-    lines.push(
-      `archived_at:   ${new Date(rec.archived_at * 1e3).toISOString()}`
-    );
-  }
-  if (rec.superseded_by !== null) {
-    lines.push(`superseded_by: ${rec.superseded_by}`);
-  }
-  if (rec.supersedes.length > 0) {
-    lines.push(`supersedes:    ${rec.supersedes.join(", ")}`);
-  }
-  lines.push(`topics:        ${rec.topics.length > 0 ? rec.topics.join(", ") : "\u2014"}`);
-  lines.push("file_refs:");
-  if (rec.file_refs.length === 0) {
-    lines.push("  \u2014");
-  } else {
-    for (const r of rec.file_refs) {
-      lines.push(`  ${r.path}${r.is_dir ? "  (dir)" : ""}`);
-    }
-  }
-  lines.push("wikilinks_out:");
-  if (rec.wikilinks_out.length === 0) lines.push("  \u2014");
-  else for (const t of rec.wikilinks_out) lines.push(`  ${t}`);
-  lines.push("wikilinks_in:");
-  if (rec.wikilinks_in.length === 0) lines.push("  \u2014");
-  else for (const s of rec.wikilinks_in) lines.push(`  ${s}`);
-  if (rec.cross_wiki_links.length > 0) {
-    lines.push("cross_wiki_links:");
-    for (const x of rec.cross_wiki_links) {
-      lines.push(`  ${x.wiki}:${x.target}`);
-    }
-  }
-  return `${lines.join("\n")}
-`;
-}
-
 // src/commands/list.ts
 import { existsSync as existsSync11 } from "fs";
 async function listWikis(options) {
@@ -2451,61 +2305,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 +2319,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);
@@ -2695,19 +2494,313 @@ function buildStderr(rows, options) {
   return "";
 }
 
+// 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";
+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}
+`);
+  }
+  out.write(`
+${WHITE_BOLD}  Install the hook + agent guides${RST}
+`);
+}
+function printBadge(out) {
+  out.write(`
+   ${ACCENT_BG} codealmanac ${RST}
+
+`);
+}
+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;
+  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
+      };
+    }
+    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}`);
+  }
+  out.write(BAR + "\n");
+  stepDone(out, `${BLUE}Setup complete${RST}`);
+  out.write("\n");
+  printNextSteps(out);
+  return { stdout: "", stderr: "", exitCode: 0 };
+}
+async function safeCheckAuth(spawnCli) {
+  try {
+    return await checkClaudeAuth(spawnCli);
+  } catch {
+    return { loggedIn: false };
+  }
+}
+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;
+  }
+  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 (!existsSync12(srcMini)) {
+    throw new Error(`missing bundled guide: ${srcMini}`);
+  }
+  if (!existsSync12(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 (existsSync12(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 (existsSync12(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.includes(IMPORT_LINE);
+}
+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 existsSync12(path3.join(dir, "mini.md"));
+}
+
 // src/commands/show.ts
-import { readFile as readFile9 } from "fs/promises";
-import { join as join12 } from "path";
+import { readFile as readFile10 } 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 +2808,289 @@ 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 row = stmt.get(slug);
-      if (row === void 0) {
+      const rec = await fetchRecord(db, slug);
+      if (rec === null) {
         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})`);
+      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 readFile10(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) {
+    return 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") + (parts.length > 0 ? "" : "");
+}
+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";
     }
-    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();
+    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(", ")}`
+    );
+  }
+  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 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);
+  if (endMatch === null || endMatch.index === void 0) return src;
+  return rest.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 collectSlugs3(options) {
+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 +3101,17 @@ function collectSlugs3(options) {
 }
 
 // src/topics/frontmatterRewrite.ts
-import { readFile as readFile10, rename as rename4, writeFile as writeFile5 } from "fs/promises";
+import { readFile as readFile11, 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 readFile11(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 +3318,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 +3482,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 readFile12 } 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 +3955,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 +3963,7 @@ async function rewriteTopicOnPages(repoRoot, transform) {
   });
   let changed = 0;
   for (const filePath of files) {
-    const raw = await readFile11(filePath, "utf8");
+    const raw = await readFile12(filePath, "utf8");
     const applied = applyTopicsTransform(raw, transform);
     if (!applied.changed) continue;
     await rewritePageTopics(filePath, transform);
@@ -3634,14 +3972,146 @@ async function rewriteTopicOnPages(repoRoot, transform) {
   return changed;
 }
 
+// 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";
+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");
+  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(`  ${BLUE2}\u25C7${RST2}  ${res.stdout.trim()}
+`);
+  } else {
+    out.write(`  ${DIM2}\u25CB  Hook kept${RST2}
+`);
+  }
+  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(
+        `  ${BLUE2}\u25C7${RST2}  Guides removed (${summary.filesTouched.join(", ")})
+`
+      );
+    } else {
+      out.write(`  ${DIM2}\u25CB  Guides not installed${RST2}
+`);
+    }
+  } else {
+    out.write(`  ${DIM2}\u25CB  Guides kept${RST2}
+`);
+  }
+  out.write(`
+  ${BLUE2}\u25C7${RST2}  ${BLUE2}Uninstall complete${RST2}
+
+`);
+  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)) {
+    await rm(mini, { force: true });
+    touched.push("codealmanac.md");
+  }
+  if (existsSync13(ref)) {
+    await rm(ref, { force: true });
+    touched.push("codealmanac-reference.md");
+  }
+  if (existsSync13(claudeMd)) {
+    const existing = await readFile13(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(`  ${BLUE2}\u25C6${RST2}  ${question} ${DIM2}${hint}${RST2} `);
+    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 existsSync14 } 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 (!existsSync14(repoRoot)) return null;
     const entries = await readRegistry();
     const existing = entries.find((e) => samePath(e.path, repoRoot));
     if (existing !== void 0) return existing;
@@ -3686,38 +4156,20 @@ 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;
-    }
-  });
-  program.command("search [query]").description("query pages by text, topic, file mentions, or freshness").option(
+  ).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;
+  }
+  program.command("search [query]").description("find pages by text, topic, file mentions, freshness").option(
     "--topic <name...>",
     "filter by topic (repeat for intersection)",
     collectOption,
@@ -3748,12 +4200,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 +4211,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 +4386,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 +4403,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 +4420,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 +4433,165 @@ 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({
-        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
+      const result = await runSetup({
+        yes: opts.yes,
+        skipHook: opts.skipHook,
+        skipGuides: opts.skipGuides
       });
       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(
+    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"]
+  }
+];
+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 readPackageVersion() {
+  try {
+    const require2 = createRequire3(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);