codealmanac 0.1.3 → 0.1.5

package/dist/codealmanac.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { createRequire as createRequire4 } from "module";
+import { createRequire as createRequire7 } from "module";
 import { basename as basename6 } from "path";
 import { Command } from "commander";
 
@@ -840,7 +840,8 @@ async function runCapture(options) {
     }
   };
   const now = options.now?.() ?? /* @__PURE__ */ new Date();
-  const logName = `.capture-${formatTimestamp2(now)}.log`;
+  const logStem = options.sessionId !== void 0 && options.sessionId.length > 0 ? options.sessionId : formatTimestamp2(now);
+  const logName = `.capture-${logStem}.jsonl`;
   const logPath = join5(almanacDir, logName);
   const logStream = createWriteStream2(logPath, { flags: "w" });
   const out = process.stdout;
@@ -1061,123 +1062,12 @@ function closeStream2(stream) {
 }
 
 // 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 { existsSync as existsSync12, readFileSync as readFileSync2, readdirSync, statSync as statSync3 } from "fs";
+import { readFile as readFile12 } from "fs/promises";
+import { createRequire as createRequire4 } 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 ?? ""}"`);
-  }
-}
+import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/indexer/index.ts
 import { createHash as createHash2 } from "crypto";
@@ -1339,6 +1229,87 @@ 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("|");
@@ -1708,16 +1679,330 @@ async function applyTopicsYaml(db, topicsYamlPath2) {
   apply();
 }
 
+// src/update/config.ts
+import { mkdir as mkdir4, readFile as readFile7, rename as rename3, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname5, join as join7 } from "path";
+function defaultConfig() {
+  return { update_notifier: true };
+}
+function getConfigPath() {
+  return join7(getGlobalAlmanacDir(), "config.json");
+}
+async function readConfig(path6) {
+  const file = path6 ?? getConfigPath();
+  let raw;
+  try {
+    raw = await readFile7(file, "utf8");
+  } catch {
+    return defaultConfig();
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return defaultConfig();
+  try {
+    const parsed = JSON.parse(trimmed);
+    return {
+      update_notifier: typeof parsed.update_notifier === "boolean" ? parsed.update_notifier : true
+    };
+  } catch {
+    return defaultConfig();
+  }
+}
+async function writeConfig(config, path6) {
+  const file = path6 ?? getConfigPath();
+  await mkdir4(dirname5(file), { recursive: true });
+  const body = `${JSON.stringify(config, null, 2)}
+`;
+  const tmp = `${file}.tmp`;
+  await writeFile4(tmp, body, "utf8");
+  await rename3(tmp, file);
+}
+
+// src/update/schedule.ts
+import { spawn as spawn2 } from "child_process";
+import { readFileSync } from "fs";
+
+// src/update/check.ts
+import { createRequire as createRequire2 } from "module";
+
+// src/update/state.ts
+import { mkdir as mkdir5, readFile as readFile8, rename as rename4, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname6, join as join8 } from "path";
+function emptyState() {
+  return {
+    last_check_at: 0,
+    installed_version: "",
+    latest_version: "",
+    dismissed_versions: []
+  };
+}
+function getStatePath() {
+  return join8(getGlobalAlmanacDir(), "update-state.json");
+}
+async function readState(path6) {
+  const file = path6 ?? getStatePath();
+  let raw;
+  try {
+    raw = await readFile8(file, "utf8");
+  } catch {
+    return emptyState();
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return emptyState();
+  try {
+    const parsed = JSON.parse(trimmed);
+    return {
+      last_check_at: typeof parsed.last_check_at === "number" ? parsed.last_check_at : 0,
+      installed_version: typeof parsed.installed_version === "string" ? parsed.installed_version : "",
+      latest_version: typeof parsed.latest_version === "string" ? parsed.latest_version : "",
+      dismissed_versions: Array.isArray(parsed.dismissed_versions) ? parsed.dismissed_versions.filter(
+        (v) => typeof v === "string" && v.length > 0
+      ) : [],
+      last_fetch_failed_at: typeof parsed.last_fetch_failed_at === "number" ? parsed.last_fetch_failed_at : void 0
+    };
+  } catch {
+    return emptyState();
+  }
+}
+async function writeState(state, path6) {
+  const file = path6 ?? getStatePath();
+  await mkdir5(dirname6(file), { recursive: true });
+  const body = `${JSON.stringify(state, null, 2)}
+`;
+  const tmp = `${file}.tmp`;
+  await writeFile5(tmp, body, "utf8");
+  await rename4(tmp, file);
+}
+
+// src/update/check.ts
+var DEFAULT_CACHE_SECONDS = 24 * 60 * 60;
+var DEFAULT_TIMEOUT_MS = 3e3;
+var REGISTRY_URL = "https://registry.npmjs.org/codealmanac";
+async function checkForUpdate(opts = {}) {
+  const now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
+  const cacheSeconds = opts.cacheSeconds ?? DEFAULT_CACHE_SECONDS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchFn = opts.fetchFn ?? globalThis.fetch;
+  const installed = opts.installedVersion ?? readInstalledVersion();
+  const state = await readState(opts.statePath);
+  if (!opts.force && state.last_check_at > 0 && now() - state.last_check_at < cacheSeconds) {
+    return { state, fetched: false, fetchFailed: false };
+  }
+  let latest = null;
+  let failed = false;
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+      const res = await fetchFn(REGISTRY_URL, {
+        signal: ac.signal,
+        headers: { accept: "application/json" }
+      });
+      if (!res.ok) {
+        failed = true;
+      } else {
+        const body = await res.json();
+        const tag = body["dist-tags"]?.latest;
+        if (typeof tag === "string" && tag.length > 0) {
+          latest = tag;
+        } else {
+          failed = true;
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    failed = true;
+  }
+  if (failed || latest === null) {
+    const next2 = {
+      ...state,
+      // We still bump last_check_at on a failed attempt; without this,
+      // every subsequent command would re-try the registry. A one-shot
+      // retry on the next invocation is enough; sustained failure gets
+      // retried on the 24h cadence like a success.
+      last_check_at: now(),
+      installed_version: installed,
+      last_fetch_failed_at: now()
+    };
+    try {
+      await writeState(next2, opts.statePath);
+    } catch {
+    }
+    return { state: next2, fetched: true, fetchFailed: true };
+  }
+  const next = {
+    last_check_at: now(),
+    installed_version: installed,
+    latest_version: latest,
+    dismissed_versions: state.dismissed_versions,
+    // Clear the failure marker on success.
+    last_fetch_failed_at: void 0
+  };
+  try {
+    await writeState(next, opts.statePath);
+  } catch {
+  }
+  return { state: next, fetched: true, fetchFailed: false };
+}
+function readInstalledVersion() {
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const pkg = require2("../../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const pkg = require2("../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return "unknown";
+}
+
+// src/update/schedule.ts
+function scheduleBackgroundUpdateCheck(argv) {
+  if (!shouldSchedule(argv)) return;
+  const scriptPath = argv[1];
+  const nodeBin = process.execPath;
+  if (scriptPath === void 0 || scriptPath.length === 0) return;
+  try {
+    const child = spawn2(
+      nodeBin,
+      [scriptPath, "--internal-check-updates"],
+      {
+        detached: true,
+        stdio: "ignore"
+        // Windows: with `detached: true` and no `stdio`, Node opens a
+        // console window — `"ignore"` prevents that.
+      }
+    );
+    child.unref();
+    child.on("error", () => {
+    });
+  } catch {
+  }
+}
+function shouldSchedule(argv) {
+  if (process.env.CODEALMANAC_SKIP_UPDATE_CHECK === "1") return false;
+  if (process.env.NODE_ENV === "test") return false;
+  if (process.env.VITEST !== void 0) return false;
+  if (argv.slice(2).includes("--internal-check-updates")) return false;
+  if (!notifierEnabled()) return false;
+  return true;
+}
+function notifierEnabled() {
+  try {
+    const raw = readFileSync(getConfigPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.update_notifier === false) return false;
+    return true;
+  } catch {
+    return true;
+  }
+}
+async function runInternalUpdateCheck() {
+  try {
+    await checkForUpdate({});
+  } catch {
+  }
+}
+function readStateForDoctor(path6) {
+  const file = path6 ?? getStatePath();
+  try {
+    const raw = readFileSync(file, "utf8");
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) return null;
+    const parsed = JSON.parse(trimmed);
+    return {
+      last_check_at: typeof parsed.last_check_at === "number" ? parsed.last_check_at : 0,
+      installed_version: typeof parsed.installed_version === "string" ? parsed.installed_version : "",
+      latest_version: typeof parsed.latest_version === "string" ? parsed.latest_version : "",
+      dismissed_versions: Array.isArray(parsed.dismissed_versions) ? parsed.dismissed_versions.filter((v) => typeof v === "string") : [],
+      last_fetch_failed_at: typeof parsed.last_fetch_failed_at === "number" ? parsed.last_fetch_failed_at : void 0
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/update/semver.ts
+function parse(v) {
+  const trimmed = v.trim().replace(/^v/i, "");
+  const noBuild = trimmed.split("+")[0] ?? "";
+  const dashAt = noBuild.indexOf("-");
+  const core = dashAt === -1 ? noBuild : noBuild.slice(0, dashAt);
+  const pre = dashAt === -1 ? "" : noBuild.slice(dashAt + 1);
+  const parts = core.split(".").map((p) => Number.parseInt(p, 10));
+  if (parts.length === 0 || parts.some((n) => !Number.isFinite(n) || n < 0)) {
+    return null;
+  }
+  return {
+    major: parts[0] ?? 0,
+    minor: parts[1] ?? 0,
+    patch: parts[2] ?? 0,
+    pre
+  };
+}
+function isNewer(latest, installed) {
+  const a = parse(latest);
+  const b = parse(installed);
+  if (a === null || b === null) return false;
+  if (a.major !== b.major) return a.major > b.major;
+  if (a.minor !== b.minor) return a.minor > b.minor;
+  if (a.patch !== b.patch) return a.patch > b.patch;
+  if (a.pre === b.pre) return false;
+  if (a.pre === "" && b.pre !== "") return true;
+  if (a.pre !== "" && b.pre === "") return false;
+  return a.pre > b.pre;
+}
+
+// src/commands/health.ts
+import { existsSync as existsSync9 } from "fs";
+import { readFile as readFile9 } from "fs/promises";
+import { basename as basename4, join as join10 } 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/resolveWiki.ts
 import { existsSync as existsSync8 } from "fs";
-import { join as join7 } from "path";
+import { join as join9 } from "path";
 async function resolveWikiRoot(params) {
   if (params.wiki !== void 0) {
     const entry = await findEntry({ name: params.wiki });
     if (entry === null) {
       throw new Error(`no registered wiki named "${params.wiki}"`);
     }
-    if (!existsSync8(join7(entry.path, ".almanac"))) {
+    if (!existsSync8(join9(entry.path, ".almanac"))) {
       throw new Error(
         `wiki "${params.wiki}" path is unreachable (${entry.path})`
       );
@@ -1779,9 +2064,9 @@ var DEFAULT_STALE_SECONDS = 90 * 24 * 60 * 60;
 async function runHealth(options) {
   const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
   await ensureFreshIndex({ repoRoot });
-  const almanacDir = join8(repoRoot, ".almanac");
-  const pagesDir = join8(almanacDir, "pages");
-  const db = openIndex(join8(almanacDir, "index.db"));
+  const almanacDir = join10(repoRoot, ".almanac");
+  const pagesDir = join10(almanacDir, "pages");
+  const db = openIndex(join10(almanacDir, "index.db"));
   try {
     const staleSeconds = options.stale !== void 0 ? parseDuration(options.stale) : DEFAULT_STALE_SECONDS;
     const scope = resolveScope(db, options);
@@ -1882,7 +2167,7 @@ async function findDeadRefs(db, scope, repoRoot) {
   const out = [];
   for (const r of rows) {
     if (!inPageScope(scope, r.slug)) continue;
-    const abs = join8(repoRoot, r.original_path);
+    const abs = join10(repoRoot, r.original_path);
     if (!existsSync9(abs)) {
       out.push({ slug: r.slug, path: r.original_path });
     }
@@ -1918,7 +2203,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 && existsSync9(join8(entry.path, ".almanac"));
+      ok = entry !== null && existsSync9(join10(entry.path, ".almanac"));
       reachableCache.set(r.target_wiki, ok);
     }
     if (!ok) {
@@ -1953,7 +2238,7 @@ async function findEmptyPages(db, scope, pagesDir) {
     if (!inPageScope(scope, r.slug)) continue;
     let raw;
     try {
-      raw = await readFile7(r.file_path, "utf8");
+      raw = await readFile9(r.file_path, "utf8");
     } catch {
       continue;
     }
@@ -2072,22 +2357,61 @@ ${lines.join("\n")}`;
 import { existsSync as existsSync11 } from "fs";
 import {
   copyFile,
-  mkdir as mkdir5,
-  readFile as readFile9,
-  writeFile as writeFile5
+  mkdir as mkdir7,
+  readFile as readFile11,
+  writeFile as writeFile7
 } from "fs/promises";
-import { createRequire as createRequire2 } from "module";
+import { createRequire as createRequire3 } 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 { mkdir as mkdir6, readFile as readFile10, rename as rename5, writeFile as writeFile6 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import path2 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var HOOK_TIMEOUT_SECONDS = 10;
+function isOurCommandPath(command) {
+  return command.endsWith("almanac-capture.sh");
+}
+function classifyEntry(raw) {
+  if (raw === null || typeof raw !== "object") {
+    return { kind: "unknown", entry: raw };
+  }
+  const obj = raw;
+  if (Array.isArray(obj.hooks)) {
+    const matcher = typeof obj.matcher === "string" ? obj.matcher : "";
+    const hooks = [];
+    for (const h of obj.hooks) {
+      if (h !== null && typeof h === "object") {
+        const ho = h;
+        if (ho.type === "command" && typeof ho.command === "string") {
+          const cmd = {
+            type: "command",
+            command: ho.command
+          };
+          if (typeof ho.timeout === "number") cmd.timeout = ho.timeout;
+          hooks.push(cmd);
+        }
+      }
+    }
+    return { kind: "wrapped", entry: { matcher, hooks } };
+  }
+  if (obj.type === "command" && typeof obj.command === "string") {
+    const cmd = {
+      type: "command",
+      command: obj.command
+    };
+    if (typeof obj.timeout === "number") cmd.timeout = obj.timeout;
+    return { kind: "legacy", entry: cmd };
+  }
+  return { kind: "unknown", entry: raw };
+}
+function isOurWrapped(entry) {
+  return entry.hooks.some((h) => isOurCommandPath(h.command));
+}
 async function runHookInstall(options = {}) {
   const script = resolveHookScriptPath(options);
   if (!script.ok) {
@@ -2097,26 +2421,54 @@ async function runHookInstall(options = {}) {
   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");
+  const preserved = [];
+  let oursAlready = null;
+  const staleCount = { n: 0 };
+  for (const raw of existing) {
+    const c = classifyEntry(raw);
+    if (c.kind === "wrapped") {
+      if (!isOurWrapped(c.entry)) {
+        preserved.push(raw);
+        continue;
+      }
+      const exactMatch = c.entry.hooks.some(
+        (h) => h.command === script.path
+      );
+      if (exactMatch && oursAlready === null) {
+        oursAlready = c.entry;
+      } else {
+        staleCount.n += 1;
+      }
+    } else if (c.kind === "legacy") {
+      if (isOurCommandPath(c.entry.command)) {
+        staleCount.n += 1;
+      } else {
+        preserved.push(raw);
+      }
+    } else {
+      preserved.push(raw);
+    }
+  }
+  const foreignLegacy = preserved.filter((raw) => {
+    const c = classifyEntry(raw);
+    return c.kind === "legacy";
+  });
+  if (foreignLegacy.length > 0) {
+    const lines = foreignLegacy.map((raw) => {
+      const c = classifyEntry(raw);
+      if (c.kind === "legacy") return `  - ${c.entry.command}`;
+      return "  - <unrecognized>";
+    }).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.
+      stderr: `almanac: SessionEnd has a foreign legacy entry:
+${lines}
+Remove or rewrap it manually in ${settingsPath} before installing.
 `,
       exitCode: 1
     };
   }
-  if (ourEntries.length > 0 && stale.length === 0) {
+  if (oursAlready !== null && staleCount.n === 0) {
     return {
       stdout: `almanac: SessionEnd hook already installed at ${script.path}
 `,
@@ -2124,13 +2476,17 @@ Remove it manually from ${settingsPath} if you want almanac to manage the hook.
       exitCode: 0
     };
   }
-  const newEntries = [
-    {
-      type: "command",
-      command: script.path,
-      timeout: HOOK_TIMEOUT_SECONDS
-    }
-  ];
+  const fresh = {
+    matcher: "",
+    hooks: [
+      {
+        type: "command",
+        command: script.path,
+        timeout: HOOK_TIMEOUT_SECONDS
+      }
+    ]
+  };
+  const newEntries = [...preserved, fresh];
   settings.hooks = { ...settings.hooks ?? {}, SessionEnd: newEntries };
   await writeSettings(settingsPath, settings);
   return {
@@ -2154,8 +2510,33 @@ async function runHookUninstall(options = {}) {
   }
   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;
+  const kept = [];
+  let removed = 0;
+  for (const raw of existing) {
+    const c = classifyEntry(raw);
+    if (c.kind === "wrapped") {
+      const innerKept = c.entry.hooks.filter(
+        (h) => !isOurCommandPath(h.command)
+      );
+      const innerRemoved = c.entry.hooks.length - innerKept.length;
+      removed += innerRemoved;
+      if (innerKept.length === 0) {
+        if (innerRemoved === 0) kept.push(raw);
+      } else if (innerRemoved === 0) {
+        kept.push(raw);
+      } else {
+        kept.push({ matcher: c.entry.matcher, hooks: innerKept });
+      }
+    } else if (c.kind === "legacy") {
+      if (isOurCommandPath(c.entry.command)) {
+        removed += 1;
+      } else {
+        kept.push(raw);
+      }
+    } else {
+      kept.push(raw);
+    }
+  }
   if (removed === 0) {
     return {
       stdout: `almanac: SessionEnd hook not installed
@@ -2199,14 +2580,33 @@ settings: ${settingsPath} (does not exist)
   }
   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");
+  let ourCommand = null;
+  const foreignSummary = [];
+  for (const raw of existing) {
+    const c = classifyEntry(raw);
+    if (c.kind === "wrapped") {
+      for (const h of c.entry.hooks) {
+        if (isOurCommandPath(h.command)) {
+          ourCommand ??= h.command;
+        } else {
+          foreignSummary.push(h.command);
+        }
+      }
+    } else if (c.kind === "legacy") {
+      if (isOurCommandPath(c.entry.command)) {
+        ourCommand ??= c.entry.command;
+      } else {
+        foreignSummary.push(c.entry.command);
+      }
+    }
+  }
+  if (ourCommand === null) {
+    const foreignLines = foreignSummary.map((c) => `  - ${c}`).join("\n");
     return {
       stdout: `SessionEnd hook: not installed
 settings: ${settingsPath}
-` + (existing.length > 0 ? `(${existing.length} foreign entr${existing.length === 1 ? "y" : "ies"} present:
-${foreign})
+` + (foreignSummary.length > 0 ? `(${foreignSummary.length} foreign entr${foreignSummary.length === 1 ? "y" : "ies"} present:
+${foreignLines})
 ` : "") + (script.ok ? `script would be: ${script.path}
 ` : ""),
       stderr: "",
@@ -2215,7 +2615,7 @@ ${foreign})
   }
   return {
     stdout: `SessionEnd hook: installed
-script: ${ours.command}
+script: ${ourCommand}
 settings: ${settingsPath}
 `,
     stderr: "",
@@ -2253,7 +2653,7 @@ function resolveHookScriptPath(options) {
 async function readSettings(settingsPath) {
   if (!existsSync10(settingsPath)) return {};
   try {
-    const raw = await readFile8(settingsPath, "utf8");
+    const raw = await readFile10(settingsPath, "utf8");
     if (raw.trim().length === 0) return {};
     const parsed = JSON.parse(raw);
     if (parsed === null || typeof parsed !== "object") return {};
@@ -2265,12 +2665,12 @@ async function readSettings(settingsPath) {
 }
 async function writeSettings(settingsPath, settings) {
   const dir = path2.dirname(settingsPath);
-  await mkdir4(dir, { recursive: true });
+  await mkdir6(dir, { recursive: true });
   const tmp = `${settingsPath}.almanac-tmp-${process.pid}`;
   const body = `${JSON.stringify(settings, null, 2)}
 `;
-  await writeFile4(tmp, body, "utf8");
-  await rename3(tmp, settingsPath);
+  await writeFile6(tmp, body, "utf8");
+  await rename5(tmp, settingsPath);
 }
 
 // src/commands/setup.ts
@@ -2434,7 +2834,7 @@ function reportAuth(out, auth) {
   }
 }
 async function installGuides(options) {
-  await mkdir5(options.claudeDir, { recursive: true });
+  await mkdir7(options.claudeDir, { recursive: true });
   const srcMini = path3.join(options.guidesDir, "mini.md");
   const srcRef = path3.join(options.guidesDir, "reference.md");
   if (!existsSync11(srcMini)) {
@@ -2456,10 +2856,10 @@ async function installGuides(options) {
   return { anyChanges: filesWritten.length > 0, filesWritten };
 }
 async function copyIfChanged(src, dest) {
-  const srcBytes = await readFile9(src);
+  const srcBytes = await readFile11(src);
   if (existsSync11(dest)) {
     try {
-      const destBytes = await readFile9(dest);
+      const destBytes = await readFile11(dest);
       if (srcBytes.equals(destBytes)) return false;
     } catch {
     }
@@ -2471,13 +2871,13 @@ var IMPORT_LINE = "@~/.claude/codealmanac.md";
 async function ensureImport(claudeMdPath) {
   let existing = "";
   if (existsSync11(claudeMdPath)) {
-    existing = await readFile9(claudeMdPath, "utf8");
+    existing = await readFile11(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");
+  await writeFile7(claudeMdPath, body, "utf8");
   return true;
 }
 function hasImportLine(contents) {
@@ -2553,7 +2953,7 @@ function resolveGuidesDir() {
     if (looksLikeGuidesDir(dir)) return dir;
   }
   try {
-    const require2 = createRequire2(import.meta.url);
+    const require2 = createRequire3(import.meta.url);
     const pkgJson = require2.resolve("codealmanac/package.json");
     const guides = path3.join(path3.dirname(pkgJson), "guides");
     if (looksLikeGuidesDir(guides)) return guides;
@@ -2577,8 +2977,9 @@ 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 updates = options.wikiOnly === true ? [] : await gatherUpdateChecks(options, version);
   const wiki = options.installOnly === true ? [] : await gatherWikiChecks(options);
-  const report = { version, install, wiki };
+  const report = { version, install, updates, wiki };
   if (options.json === true) {
     return {
       stdout: `${JSON.stringify(report, null, 2)}
@@ -2660,13 +3061,21 @@ async function describeHook(settingsPath) {
     };
   }
   try {
-    const raw = await readFile10(settingsPath, "utf8");
+    const raw = await readFile12(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) {
+    const found = entries.some((e) => {
+      if (typeof e?.command === "string" && e.command.endsWith("almanac-capture.sh")) {
+        return true;
+      }
+      if (Array.isArray(e?.hooks)) {
+        return e.hooks.some(
+          (h) => typeof h?.command === "string" && h.command.endsWith("almanac-capture.sh")
+        );
+      }
+      return false;
+    });
+    if (!found) {
       return {
         status: "problem",
         key: "install.hook",
@@ -2723,7 +3132,7 @@ async function describeImportLine(claudeDir) {
     };
   }
   try {
-    const contents = await readFile10(claudeMd, "utf8");
+    const contents = await readFile12(claudeMd, "utf8");
     const lines = contents.split(/\r?\n/).map((l) => l.trim());
     const present = lines.some((line) => {
       if (line === IMPORT_LINE) return true;
@@ -2753,6 +3162,63 @@ async function describeImportLine(claudeDir) {
     };
   }
 }
+async function gatherUpdateChecks(options, installedVersion) {
+  const checks = [];
+  const state = readStateForDoctor(options.updateStatePath);
+  const config = await readConfig(options.updateConfigPath);
+  if (state === null || state.latest_version.length === 0) {
+    checks.push({
+      status: "info",
+      key: "update.status",
+      message: `on ${installedVersion}; no update check has run yet`,
+      fix: "run: almanac update --check"
+    });
+  } else if (isNewer(state.latest_version, installedVersion)) {
+    const dismissed = state.dismissed_versions.includes(state.latest_version) ? " (dismissed \u2014 run `almanac update` to install anyway)" : "";
+    checks.push({
+      status: "problem",
+      key: "update.status",
+      message: `${state.latest_version} available (you're on ${installedVersion})${dismissed}`,
+      fix: "run: almanac update"
+    });
+  } else {
+    checks.push({
+      status: "ok",
+      key: "update.status",
+      message: `on latest (${installedVersion})`
+    });
+  }
+  if (state !== null && state.last_check_at > 0) {
+    const now = (options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+    const ageMs = now - state.last_check_at * 1e3;
+    const failedSuffix = state.last_fetch_failed_at !== void 0 && state.last_fetch_failed_at === state.last_check_at ? " (last attempt failed \u2014 will retry next invocation)" : "";
+    checks.push({
+      status: "info",
+      key: "update.last_check",
+      message: `last checked: ${formatDuration(ageMs)} ago${failedSuffix}`
+    });
+  } else {
+    checks.push({
+      status: "info",
+      key: "update.last_check",
+      message: "last checked: never"
+    });
+  }
+  checks.push({
+    status: "info",
+    key: "update.notifier",
+    message: `update notifier: ${config.update_notifier ? "enabled" : "disabled"}`,
+    fix: config.update_notifier ? void 0 : "run: almanac update --enable-notifier"
+  });
+  if (state !== null && state.dismissed_versions.length > 0) {
+    checks.push({
+      status: "info",
+      key: "update.dismissed",
+      message: `dismissed versions: ${state.dismissed_versions.join(", ")}`
+    });
+  }
+  return checks;
+}
 async function gatherWikiChecks(options) {
   const checks = [];
   const repoRoot = findNearestAlmanacDir(options.cwd);
@@ -2770,14 +3236,30 @@ async function gatherWikiChecks(options) {
     key: "wiki.repo",
     message: `repo: ${repoRoot}`
   });
-  const entry = await findEntry({ path: repoRoot });
+  try {
+    await ensureFreshIndex({ repoRoot });
+  } catch {
+  }
+  let entry;
+  try {
+    entry = await findEntry({ path: repoRoot });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    checks.push({
+      status: "problem",
+      key: "wiki.registered",
+      message: `could not read registry: ${msg}`,
+      fix: "inspect ~/.almanac/registry.json; remove or fix the malformed entry"
+    });
+    entry = null;
+  }
   if (entry !== null) {
     checks.push({
       status: "ok",
       key: "wiki.registered",
       message: `registered as '${entry.name}'`
     });
-  } else {
+  } else if (checks[checks.length - 1]?.key !== "wiki.registered") {
     checks.push({
       status: "info",
       key: "wiki.registered",
@@ -2894,7 +3376,9 @@ function describeLastCapture(almanacDir, nowFn) {
       message: "last capture: unknown"
     };
   }
-  const captures = entries.filter((e) => e.startsWith(".capture-") && e.endsWith(".log")).map((e) => {
+  const captures = entries.filter(
+    (e) => e.startsWith(".capture-") && (e.endsWith(".log") || e.endsWith(".jsonl"))
+  ).map((e) => {
     try {
       return {
         name: e,
@@ -2921,12 +3405,23 @@ function describeLastCapture(almanacDir, nowFn) {
     message: `last capture: ${formatDuration(age)} ago (${latest.name})`
   };
 }
-var req = createRequire3(import.meta.url);
+var req = createRequire4(import.meta.url);
+var HEALTH_PROBLEM_KEYS = [
+  "orphans",
+  "stale",
+  "dead_refs",
+  "broken_links",
+  "broken_xwiki",
+  "empty_topics",
+  "empty_pages",
+  "slug_collisions"
+];
 function countHealthProblems(jsonStdout) {
   try {
     const report = JSON.parse(jsonStdout);
     let total = 0;
-    for (const arr of Object.values(report)) {
+    for (const key of HEALTH_PROBLEM_KEYS) {
+      const arr = report[key];
       if (Array.isArray(arr)) total += arr.length;
     }
     return total;
@@ -2936,8 +3431,23 @@ function countHealthProblems(jsonStdout) {
 }
 function detectInstallPath() {
   try {
-    const entry = req.resolve("codealmanac");
-    return path4.dirname(path4.dirname(entry));
+    const here = fileURLToPath4(import.meta.url);
+    let dir = path4.dirname(here);
+    for (let i = 0; i < 5; i++) {
+      const pkgPath = path4.join(dir, "package.json");
+      if (existsSync12(pkgPath)) {
+        try {
+          const raw = readFileSync2(pkgPath, "utf-8");
+          const pkg = JSON.parse(raw);
+          if (pkg.name === "codealmanac") return dir;
+        } catch {
+        }
+      }
+      const parent = path4.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return null;
   } catch {
     return null;
   }
@@ -2990,6 +3500,13 @@ function formatReport2(report, options) {
     }
     lines.push("");
   }
+  if (report.updates.length > 0) {
+    lines.push(color ? `${BOLD2}## Updates${RST2}` : "## Updates");
+    for (const c of report.updates) {
+      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) {
@@ -3096,14 +3613,14 @@ async function runReindex(options) {
 }
 
 // src/commands/search.ts
-import { join as join9 } from "path";
+import { join as join11 } from "path";
 async function runSearch(options) {
   const repoRoot = await resolveWikiRoot({
     cwd: options.cwd,
     wiki: options.wiki
   });
   await ensureFreshIndex({ repoRoot });
-  const dbPath = join9(repoRoot, ".almanac", "index.db");
+  const dbPath = join11(repoRoot, ".almanac", "index.db");
   const db = openIndex(dbPath);
   try {
     const rows = executeQuery(db, options);
@@ -3275,15 +3792,15 @@ function buildStderr(rows, options) {
 }
 
 // src/commands/show.ts
-import { readFile as readFile11 } from "fs/promises";
-import { join as join10 } from "path";
+import { readFile as readFile13 } from "fs/promises";
+import { join as join12 } from "path";
 async function runShow(options) {
   const repoRoot = await resolveWikiRoot({
     cwd: options.cwd,
     wiki: options.wiki
   });
   await ensureFreshIndex({ repoRoot });
-  const dbPath = join10(repoRoot, ".almanac", "index.db");
+  const dbPath = join12(repoRoot, ".almanac", "index.db");
   const db = openIndex(dbPath);
   try {
     const slugs = collectSlugs(options);
@@ -3342,7 +3859,7 @@ async function fetchRecord(db, slug) {
   ).all(slug).map((r) => r.slug);
   let body = "";
   try {
-    body = stripFrontmatter(await readFile11(pageRow.file_path, "utf8"));
+    body = stripFrontmatter(await readFile13(pageRow.file_path, "utf8"));
   } catch {
   }
   return {
@@ -3589,18 +4106,18 @@ function collectSlugs(options) {
 }
 
 // src/topics/frontmatterRewrite.ts
-import { readFile as readFile12, rename as rename4, writeFile as writeFile6 } from "fs/promises";
+import { readFile as readFile14, rename as rename6, writeFile as writeFile8 } from "fs/promises";
 import yaml3 from "js-yaml";
 async function rewritePageTopics(filePath, transform) {
-  const raw = await readFile12(filePath, "utf8");
+  const raw = await readFile14(filePath, "utf8");
   const { before, after, output, changed } = applyTopicsTransform(
     raw,
     transform
   );
   if (changed) {
     const tmp = `${filePath}.tmp`;
-    await writeFile6(tmp, output, "utf8");
-    await rename4(tmp, filePath);
+    await writeFile8(tmp, output, "utf8");
+    await rename6(tmp, filePath);
   }
   return { before, after, changed };
 }
@@ -3806,12 +4323,12 @@ function arraysEqual(a, b) {
 }
 
 // src/topics/paths.ts
-import { join as join11 } from "path";
+import { join as join13 } from "path";
 function topicsYamlPath(repoRoot) {
-  return join11(repoRoot, ".almanac", "topics.yaml");
+  return join13(repoRoot, ".almanac", "topics.yaml");
 }
 function indexDbPath(repoRoot) {
-  return join11(repoRoot, ".almanac", "index.db");
+  return join13(repoRoot, ".almanac", "index.db");
 }
 
 // src/commands/tag.ts
@@ -3970,8 +4487,8 @@ async function runUntag(options) {
 }
 
 // src/commands/topics.ts
-import { readFile as readFile13 } from "fs/promises";
-import { join as join12 } from "path";
+import { readFile as readFile15 } from "fs/promises";
+import { join as join14 } from "path";
 import fg3 from "fast-glob";
 async function runTopicsList(options) {
   const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
@@ -4443,7 +4960,7 @@ async function runTopicsDescribe(options) {
   };
 }
 async function rewriteTopicOnPages(repoRoot, transform) {
-  const pagesDir = join12(repoRoot, ".almanac", "pages");
+  const pagesDir = join14(repoRoot, ".almanac", "pages");
   const files = await fg3("**/*.md", {
     cwd: pagesDir,
     absolute: true,
@@ -4451,7 +4968,7 @@ async function rewriteTopicOnPages(repoRoot, transform) {
   });
   let changed = 0;
   for (const filePath of files) {
-    const raw = await readFile13(filePath, "utf8");
+    const raw = await readFile15(filePath, "utf8");
     const applied = applyTopicsTransform(raw, transform);
     if (!applied.changed) continue;
     await rewritePageTopics(filePath, transform);
@@ -4462,7 +4979,7 @@ async function rewriteTopicOnPages(repoRoot, transform) {
 
 // src/commands/uninstall.ts
 import { existsSync as existsSync14 } from "fs";
-import { readFile as readFile14, rm, writeFile as writeFile7 } from "fs/promises";
+import { readFile as readFile16, rm, writeFile as writeFile9 } from "fs/promises";
 import { homedir as homedir6 } from "os";
 import path5 from "path";
 var BLUE3 = "\x1B[38;5;75m";
@@ -4543,14 +5060,14 @@ async function removeGuideFiles(claudeDir) {
     touched.push("codealmanac-reference.md");
   }
   if (existsSync14(claudeMd)) {
-    const existing = await readFile14(claudeMd, "utf8");
+    const existing = await readFile16(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");
+        await writeFile9(claudeMd, body, "utf8");
         touched.push("CLAUDE.md");
       }
     }
@@ -4592,6 +5109,195 @@ function confirm2(out, question, defaultYes) {
   });
 }
 
+// src/commands/update.ts
+import { spawn as spawn3 } from "child_process";
+import { createRequire as createRequire5 } from "module";
+async function runUpdate(opts = {}) {
+  if (opts.enableNotifier === true) {
+    return await toggleNotifier(true, opts);
+  }
+  if (opts.disableNotifier === true) {
+    return await toggleNotifier(false, opts);
+  }
+  if (opts.dismiss === true) {
+    return await dismissLatest(opts);
+  }
+  if (opts.check === true) {
+    return await forceCheck(opts);
+  }
+  return await installLatest(opts);
+}
+async function dismissLatest(opts) {
+  const state = await readState(opts.statePath);
+  if (state.latest_version.length === 0) {
+    return {
+      stdout: "codealmanac: no pending update to dismiss. Run `almanac update --check` to query the registry.\n",
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const installed = opts.installedVersion ?? readInstalledVersion2();
+  if (!isNewer(state.latest_version, installed)) {
+    return {
+      stdout: `codealmanac: already on latest (${installed}); nothing to dismiss.
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  if (state.dismissed_versions.includes(state.latest_version)) {
+    return {
+      stdout: `codealmanac: ${state.latest_version} already dismissed.
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const next = {
+    ...state,
+    dismissed_versions: [...state.dismissed_versions, state.latest_version]
+  };
+  await writeState(next, opts.statePath);
+  return {
+    stdout: `codealmanac: dismissed ${state.latest_version}. The nag banner will not show for this version.
+Run \`almanac update\` to upgrade, or \`almanac update --enable-notifier\` to re-enable nags.
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function forceCheck(opts) {
+  const installed = opts.installedVersion ?? readInstalledVersion2();
+  const checkFn = opts.checkFn ?? checkForUpdate;
+  const result = await checkFn({
+    installedVersion: installed,
+    force: true,
+    statePath: opts.statePath,
+    now: opts.now
+  });
+  if (result.fetchFailed) {
+    return {
+      stdout: "",
+      stderr: `codealmanac: could not reach registry.npmjs.org (timeout or network error).
+Installed: ${installed}. No cached latest available.
+`,
+      exitCode: 1
+    };
+  }
+  const latest = result.state.latest_version;
+  if (latest.length === 0) {
+    return {
+      stdout: `codealmanac: installed ${installed}; registry did not report a latest tag.
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  if (isNewer(latest, installed)) {
+    const dismissed = result.state.dismissed_versions.includes(latest) ? " (dismissed \u2014 banner suppressed; `almanac update` still installs)" : "";
+    return {
+      stdout: `codealmanac ${latest} available (you're on ${installed})${dismissed}.
+Run: almanac update
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    stdout: `codealmanac: up to date (${installed}).
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function toggleNotifier(enable, opts) {
+  const config = await readConfig(opts.configPath);
+  const next = { ...config, update_notifier: enable };
+  await writeConfig(next, opts.configPath);
+  return {
+    stdout: enable ? "codealmanac: update notifier enabled. The pre-command banner will show when a new version is available.\n" : "codealmanac: update notifier disabled. No more pre-command banners. Run `almanac update --check` to see status.\n",
+    stderr: "",
+    exitCode: 0
+  };
+}
+async function installLatest(opts) {
+  const spawnFn = opts.spawnFn ?? spawn3;
+  const installed = opts.installedVersion ?? readInstalledVersion2();
+  const spawnOpts = { stdio: "inherit" };
+  return await new Promise((resolve2) => {
+    const child = spawnFn(
+      "npm",
+      ["i", "-g", "codealmanac@latest"],
+      spawnOpts
+    );
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        resolve2({
+          stdout: "",
+          stderr: "codealmanac: `npm` not found on PATH. Install Node.js + npm, or install codealmanac via your package manager.\n",
+          exitCode: 1
+        });
+        return;
+      }
+      resolve2({
+        stdout: "",
+        stderr: `codealmanac: failed to run npm: ${err.message}
+`,
+        exitCode: 1
+      });
+    });
+    child.on("exit", async (code, _signal) => {
+      const exitCode = code ?? 1;
+      if (exitCode !== 0) {
+        const hint = `codealmanac: npm install failed (exit ${exitCode}).
+If you see "EACCES" above, try: sudo npm i -g codealmanac@latest
+Or install with a version manager (nvm, volta, fnm) to avoid sudo.
+`;
+        resolve2({ stdout: "", stderr: hint, exitCode });
+        return;
+      }
+      try {
+        const state = await readState(opts.statePath);
+        const now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
+        await writeState(
+          {
+            last_check_at: now(),
+            installed_version: state.latest_version || installed,
+            latest_version: state.latest_version || installed,
+            dismissed_versions: state.dismissed_versions
+          },
+          opts.statePath
+        );
+      } catch {
+      }
+      resolve2({
+        stdout: "codealmanac: updated.\n",
+        stderr: "",
+        exitCode: 0
+      });
+    });
+  });
+}
+function readInstalledVersion2() {
+  try {
+    const require2 = createRequire5(import.meta.url);
+    const pkg = require2("../../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  try {
+    const require2 = createRequire5(import.meta.url);
+    const pkg = require2("../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return "unknown";
+}
+
 // src/registry/autoregister.ts
 import { existsSync as existsSync15 } from "fs";
 import { basename as basename5 } from "path";
@@ -4642,10 +5348,104 @@ function samePath(a, b) {
   return a === b;
 }
 
+// src/update/announce.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { createRequire as createRequire6 } from "module";
+var RST4 = "\x1B[0m";
+var BOLD3 = "\x1B[1m";
+var YELLOW = "\x1B[33m";
+function announceUpdateIfAvailable(stderr, opts = {}) {
+  const statePath = opts.statePath ?? getStatePath();
+  const configPath = opts.configPath ?? getConfigPath();
+  const installed = opts.installedVersion ?? readInstalledVersion3();
+  if (!shouldNotify(configPath)) return;
+  const state = readStateSync(statePath);
+  if (state === null) return;
+  if (state.latest_version.length === 0) return;
+  if (!isNewer(state.latest_version, installed)) return;
+  if (state.dismissed_versions.includes(state.latest_version)) return;
+  const useColor = opts.color ?? (process.stderr.isTTY === true && !("NO_COLOR" in process.env));
+  const warn = useColor ? `${YELLOW}${BOLD3}\u26A0${RST4}` : "!";
+  const cmd = useColor ? `${BOLD3}almanac update${RST4}` : "almanac update";
+  stderr.write(
+    `${warn} codealmanac ${state.latest_version} available (you're on ${installed}) \u2014 run: ${cmd}
+`
+  );
+}
+function readStateSync(path6) {
+  let raw;
+  try {
+    raw = readFileSync3(path6, "utf8");
+  } catch {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return {
+      last_check_at: typeof parsed.last_check_at === "number" ? parsed.last_check_at : 0,
+      installed_version: typeof parsed.installed_version === "string" ? parsed.installed_version : "",
+      latest_version: typeof parsed.latest_version === "string" ? parsed.latest_version : "",
+      dismissed_versions: Array.isArray(parsed.dismissed_versions) ? parsed.dismissed_versions.filter(
+        (v) => typeof v === "string"
+      ) : []
+    };
+  } catch {
+    return null;
+  }
+}
+function shouldNotify(configPath) {
+  let raw;
+  try {
+    raw = readFileSync3(configPath, "utf8");
+  } catch {
+    return true;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return true;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed.update_notifier === false) return false;
+    return true;
+  } catch {
+    return true;
+  }
+}
+function readInstalledVersion3() {
+  try {
+    const require2 = createRequire6(import.meta.url);
+    const pkg = require2("../../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  try {
+    const require2 = createRequire6(import.meta.url);
+    const pkg = require2("../package.json");
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return "unknown";
+}
+
 // src/cli.ts
-async function run(argv) {
+async function run(argv, deps = {}) {
+  const runSetupFn = deps.runSetup ?? runSetup;
+  const announceUpdateFn = deps.announceUpdate ?? announceUpdateIfAvailable;
+  const scheduleUpdateCheckFn = deps.scheduleUpdateCheck ?? scheduleBackgroundUpdateCheck;
+  const runInternalUpdateCheckFn = deps.runInternalUpdateCheck ?? runInternalUpdateCheck;
+  if (argv.slice(2).includes("--internal-check-updates")) {
+    await runInternalUpdateCheckFn();
+    return;
+  }
   const invoked = argv[1] !== void 0 ? basename6(argv[1]) : "almanac";
   const programName = invoked === "codealmanac" ? "codealmanac" : "almanac";
+  announceUpdateFn(process.stderr);
+  scheduleUpdateCheckFn(argv);
   const program = new Command();
   program.name(programName).description(
     "codealmanac \u2014 a living wiki for codebases, maintained by AI agents"
@@ -4653,7 +5453,7 @@ async function run(argv) {
   if (programName === "codealmanac") {
     const setupInvocation = tryParseSetupShortcut(argv.slice(2));
     if (setupInvocation !== null) {
-      const result = await runSetup(setupInvocation);
+      const result = await runSetupFn(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;
@@ -4954,6 +5754,31 @@ async function run(argv) {
       emit(result);
     }
   );
+  program.command("update").description(
+    "install the latest codealmanac (synchronous foreground `npm i -g`)"
+  ).option(
+    "--dismiss",
+    "silence the update banner for the current `latest_version` without installing"
+  ).option(
+    "--check",
+    "force a registry check now (bypasses the 24h cache); no install"
+  ).option(
+    "--enable-notifier",
+    "re-enable the pre-command update banner (writes ~/.almanac/config.json)"
+  ).option(
+    "--disable-notifier",
+    "silence the pre-command update banner (writes ~/.almanac/config.json)"
+  ).action(
+    async (opts) => {
+      const result = await runUpdate({
+        dismiss: opts.dismiss,
+        check: opts.check,
+        enableNotifier: opts.enableNotifier,
+        disableNotifier: opts.disableNotifier
+      });
+      emit(result);
+    }
+  );
   program.command("uninstall").description("remove the hook + guides + import line").option("-y, --yes", "skip confirmations; remove everything").option(
     "--keep-hook",
     "don't remove the SessionEnd hook (guides still prompted unless --yes)"
@@ -4988,7 +5813,7 @@ var HELP_GROUPS = [
   },
   {
     title: "Setup",
-    commands: ["setup", "uninstall", "doctor"]
+    commands: ["setup", "uninstall", "doctor", "update"]
   }
 ];
 function configureGroupedHelp(program) {
@@ -5036,6 +5861,7 @@ function configureGroupedHelp(program) {
         }
         out.push("");
       }
+      byName.delete("help");
       if (byName.size > 0) {
         out.push("Other:");
         for (const c of byName.values()) {
@@ -5091,7 +5917,7 @@ function renderDefault(cmd, helper) {
 }
 function readPackageVersion2() {
   try {
-    const require2 = createRequire4(import.meta.url);
+    const require2 = createRequire7(import.meta.url);
     const pkg = require2("../package.json");
     if (typeof pkg.version === "string" && pkg.version.length > 0) {
       return pkg.version;