librian 0.1.1 → 0.2.0

package/dist/cli.js

@@ -7263,7 +7263,7 @@ import { resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "librian",
-  version: "0.1.1",
+  version: "0.2.0",
   description: "Find and read sections of a markdown docs folder over MCP, with outlines and line ranges that stay current as the docs change",
   repository: {
     type: "git",
@@ -7318,11 +7318,6 @@ var package_default = {
   }
 };
 
-// src/modules/catalog/catalog.ts
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
 // src/_defs/limits.ts
 var DEFAULT_MAX_BYTES = 16e3;
 var MIN_MAX_BYTES = 4e3;
@@ -7333,8 +7328,12 @@ var SEARCH_LIMIT_DEFAULT = 20;
 var SEARCH_LIMIT_MAX = 50;
 var COUNT_MAX_FILES = 5e3;
 var COUNT_MAX_MS = 2e3;
+var HISTORY_REFRESH_MS = 5 * 60 * 1e3;
 
 // src/modules/catalog/catalog.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 var CATALOG_FILE_NAME = "catalog.json";
 var ENTRY_NAME_PATTERN = /^[a-z][a-z0-9_]{0,23}$/;
 var ENTRY_NAME_MAX_CHARS = 24;
@@ -7461,7 +7460,7 @@ function defaultEntryName(root, taken) {
 // src/modules/cli/folder-check.ts
 import { statSync as statSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join3, parse, resolve as resolve2 } from "node:path";
+import { join as join4, parse, resolve as resolve2 } from "node:path";
 
 // src/_libs/compare-text.ts
 function compareText(left, right) {
@@ -7496,7 +7495,7 @@ function compareText(left, right) {
 
 // src/modules/docs/library.ts
 import { readFileSync as readFileSync2, readdirSync, realpathSync, statSync } from "node:fs";
-import { basename, join as join2, resolve } from "node:path";
+import { basename, join as join3, resolve } from "node:path";
 
 // src/_libs/is-inside.ts
 import { isAbsolute, relative, sep } from "node:path";
@@ -7511,6 +7510,114 @@ function isInside(root, target) {
   return true;
 }
 
+// src/modules/docs/blocks.ts
+import { createHash } from "node:crypto";
+
+// src/modules/tools/format.ts
+function textResult(text2) {
+  return { content: [{ type: "text", text: text2 }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function byteLength(text2) {
+  return Buffer.byteLength(text2, "utf8");
+}
+function formatSize(bytes) {
+  if (bytes < 1e3) {
+    return bytes + "B";
+  }
+  if (bytes < 99950) {
+    return (bytes / 1e3).toFixed(1) + "K";
+  }
+  if (bytes < 999500) {
+    return Math.round(bytes / 1e3) + "K";
+  }
+  return (bytes / 1e6).toFixed(2) + "M";
+}
+function pluralize(count, noun) {
+  if (count == 1) {
+    return count + " " + noun;
+  }
+  return count + " " + noun + "s";
+}
+function truncateChars(text2, maxChars) {
+  const characters = Array.from(text2);
+  if (characters.length <= maxChars) {
+    return text2;
+  }
+  return characters.slice(0, maxChars - 1).join("") + "\u2026";
+}
+function takeBytes(text2, maxBytes) {
+  let result = "";
+  let used = 0;
+  for (const character of text2) {
+    const characterBytes = byteLength(character);
+    if (used + characterBytes > maxBytes) {
+      break;
+    }
+    result += character;
+    used += characterBytes;
+  }
+  return result;
+}
+function headingLabel(document, headingIndex) {
+  const heading = document.headings[headingIndex];
+  return "#".repeat(heading.level) + " " + truncateChars(heading.title, TITLE_MAX_CHARS);
+}
+function headingChain(document, headingIndex) {
+  const labels = [headingLabel(document, headingIndex)];
+  let ancestor = document.headings[headingIndex].parent;
+  while (ancestor != null) {
+    if (ancestor != document.titleIndex) {
+      labels.unshift(headingLabel(document, ancestor));
+    }
+    ancestor = document.headings[ancestor].parent;
+  }
+  return labels.join(" \u203A ");
+}
+function rangeHeader(document, start, end, headingIndex) {
+  let header = document.path + ":" + start + "-" + end + " \xB7 " + formatSize(document.bytesOf(start, end));
+  if (headingIndex != null) {
+    header += " \xB7 " + headingChain(document, headingIndex);
+  }
+  return header;
+}
+function cutPage(document, start, end, budgetBytes) {
+  const joinLines2 = (lastLine2) => document.lines.slice(start - 1, lastLine2).join("\n");
+  if (document.bytesOf(start, end) - 1 <= budgetBytes) {
+    return { text: joinLines2(end), lastLine: end };
+  }
+  let fitting = start - 1;
+  let overflowing = end;
+  while (overflowing - fitting > 1) {
+    const middle = fitting + overflowing >> 1;
+    if (document.bytesOf(start, middle) - 1 <= budgetBytes) {
+      fitting = middle;
+    } else {
+      overflowing = middle;
+    }
+  }
+  if (fitting < start) {
+    const line = document.lines[start - 1];
+    const marker = "[line " + start + " cut: " + byteLength(line) + "B]";
+    const allowed = budgetBytes - byteLength(marker) - 1;
+    if (allowed <= 0) {
+      return { text: marker, lastLine: start };
+    }
+    return { text: takeBytes(line, allowed) + " " + marker, lastLine: start };
+  }
+  let lastLine = fitting;
+  const halfway = start + Math.floor((fitting - start) / 2);
+  for (let line = fitting; line > halfway; line--) {
+    if (document.lines[line - 1].trim() == "") {
+      lastLine = line;
+      break;
+    }
+  }
+  return { text: joinLines2(lastLine), lastLine };
+}
+
 // src/modules/docs/parse.ts
 var FENCE_OPENING = /^ {0,3}(`{3,}|~{3,})(.*)$/;
 var FENCE_CLOSING = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
@@ -7684,6 +7791,353 @@ function blockAt(document, line) {
   return { start: headings[found].line, end: headings[found].blockEnd, headingIndex: found };
 }
 
+// src/modules/docs/blocks.ts
+var INTRO_LABEL = "(intro)";
+function shortHash(text2, length) {
+  return createHash("sha1").update(text2).digest("base64url").slice(0, length);
+}
+function hashLines(document, start, end) {
+  return shortHash(document.lines.slice(start - 1, end).join("\n"), 8);
+}
+function isBlank(document, start, end) {
+  for (let line = start; line <= end; line += 1) {
+    if (document.lines[line - 1].trim() != "") {
+      return false;
+    }
+  }
+  return true;
+}
+function encodeBlocks(blocks) {
+  return JSON.stringify(blocks.map((block) => ({ h: block.key, x: block.hash })));
+}
+function decodeBlocks(text2) {
+  const parsed = JSON.parse(text2);
+  return parsed.map((entry) => ({ key: entry.h, hash: entry.x }));
+}
+function hashBlocks(blocks) {
+  return shortHash(encodeBlocks(blocks), 16);
+}
+function listBlocks(document) {
+  const blocks = [];
+  const headings = document.headings;
+  let introEnd = document.lines.length;
+  if (headings.length > 0) {
+    introEnd = headings[0].line - 1;
+  }
+  if (introEnd >= 1 && isBlank(document, 1, introEnd) == false) {
+    blocks.push({ key: "", hash: hashLines(document, 1, introEnd), start: 1, end: introEnd, headingIndex: null });
+  }
+  for (let index = 0; index < headings.length; index += 1) {
+    const heading = headings[index];
+    blocks.push({
+      key: "#".repeat(heading.level) + " " + heading.text,
+      hash: hashLines(document, heading.line + 1, heading.blockEnd),
+      start: heading.line,
+      end: heading.blockEnd,
+      headingIndex: index
+    });
+  }
+  return { blocks, hash: hashBlocks(blocks) };
+}
+function labelOfBlock(document, block) {
+  if (block.headingIndex == null) {
+    return INTRO_LABEL;
+  }
+  return headingChain(document, block.headingIndex);
+}
+var KEY_PATTERN = /^(#{1,6}) (.*)$/;
+function keyLevel(block) {
+  const match = KEY_PATTERN.exec(block.key);
+  if (match == null) {
+    return 0;
+  }
+  return match[1].length;
+}
+function keyLabel(block) {
+  const match = KEY_PATTERN.exec(block.key);
+  if (match == null) {
+    return INTRO_LABEL;
+  }
+  return match[1] + " " + truncateChars(stripInlineMarkdown(match[2]), TITLE_MAX_CHARS);
+}
+function labelOfRecord(blocks, index) {
+  if (blocks[index].key == "") {
+    return INTRO_LABEL;
+  }
+  let titleIndex = -1;
+  for (let position = 0; position < blocks.length; position += 1) {
+    if (blocks[position].key == "") {
+      continue;
+    }
+    if (keyLevel(blocks[position]) == 1) {
+      titleIndex = position;
+    }
+    break;
+  }
+  const labels = [keyLabel(blocks[index])];
+  let level = keyLevel(blocks[index]);
+  for (let position = index - 1; position >= 0 && level > 1; position -= 1) {
+    const ancestorLevel = keyLevel(blocks[position]);
+    if (ancestorLevel == 0 || ancestorLevel >= level) {
+      continue;
+    }
+    level = ancestorLevel;
+    if (position != titleIndex) {
+      labels.unshift(keyLabel(blocks[position]));
+    }
+  }
+  return labels.join(" \u203A ");
+}
+
+// src/modules/docs/history-store.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+var HISTORY_SCHEMA_VERSION = "1";
+var HISTORY_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
+var HISTORY_BUSY_TIMEOUT_MS = 1e3;
+var DELETED_HASH = "-";
+var HISTORY_REMOVED_MESSAGE = "History was removed. Open a new session to start a new one.";
+var HISTORY_BUSY_MESSAGE = "History is busy right now; try again in a moment.";
+function resolveHistoryFile(home, root) {
+  void root;
+  return join2(home, "history.db");
+}
+var HistoryBusyError = class extends Error {
+  constructor() {
+    super(HISTORY_BUSY_MESSAGE);
+  }
+};
+function describeHistoryTrouble(file2, status) {
+  if (status.removed == true) {
+    return "librian: history.db was removed; changes is off for this session. Open a new session to start a new history.";
+  }
+  return `librian: history is unavailable: ${status.reason}; changes is off. Delete ${file2} to start over.`;
+}
+function historyToolMessage(file2, status) {
+  if (status.removed == true) {
+    return HISTORY_REMOVED_MESSAGE;
+  }
+  return `History is unavailable: ${status.reason}. Delete ${file2} to start over.`;
+}
+var sqliteModule = null;
+function loadSqlite() {
+  if (sqliteModule != null) {
+    return sqliteModule;
+  }
+  const originalEmitWarning = process.emitWarning;
+  process.emitWarning = ((warning, ...rest) => {
+    const text2 = typeof warning == "string" ? warning : warning.message;
+    if (/sqlite/i.test(text2) == true) {
+      return;
+    }
+    return originalEmitWarning.call(process, warning, ...rest);
+  });
+  try {
+    sqliteModule = process.getBuiltinModule("node:sqlite");
+  } finally {
+    process.emitWarning = originalEmitWarning;
+  }
+  return sqliteModule;
+}
+function describeError(error62) {
+  if (error62 instanceof Error) {
+    return error62.message;
+  }
+  return String(error62);
+}
+function isBusyError(error62) {
+  if (error62 instanceof Error == false) {
+    return false;
+  }
+  const code = error62.errcode;
+  if (typeof code == "number" && ((code & 255) == 5 || (code & 255) == 6)) {
+    return true;
+  }
+  return /database is locked|database table is locked|busy/i.test(error62.message);
+}
+function openHistoryStore(file2, now = Date.now) {
+  let status = null;
+  let hasWarnedBusy = false;
+  const listeners = [];
+  function say(line) {
+    for (const listener of listeners) {
+      listener(line);
+    }
+  }
+  function disable(reason, removed) {
+    if (status != null) {
+      return;
+    }
+    status = { reason, removed };
+    say(describeHistoryTrouble(file2, status));
+  }
+  try {
+    mkdirSync2(dirname(file2), { recursive: true });
+    const opened = new (loadSqlite()).DatabaseSync(file2);
+    try {
+      opened.exec(`PRAGMA busy_timeout=${HISTORY_BUSY_TIMEOUT_MS}`);
+      opened.exec("PRAGMA journal_mode=WAL");
+      opened.exec("CREATE TABLE IF NOT EXISTS meta (key text PRIMARY KEY, value text)");
+      const knownVersion = opened.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+      if (knownVersion != null && knownVersion.value != HISTORY_SCHEMA_VERSION) {
+        throw new Error(`unknown history schema version ${knownVersion.value}`);
+      }
+      opened.exec(`CREATE TABLE IF NOT EXISTS file_version (
+                root        text    NOT NULL,
+                path        text    NOT NULL,
+                observed_at integer NOT NULL,
+                blocks_hash text    NOT NULL,
+                blocks      text,
+                CONSTRAINT pk_file_version PRIMARY KEY (root, path, observed_at)
+            )`);
+      opened.prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('schema_version', ?)").run(HISTORY_SCHEMA_VERSION);
+      opened.prepare(`DELETE FROM file_version
+                WHERE observed_at < ?
+                  AND observed_at < (SELECT MAX(newer.observed_at) FROM file_version newer WHERE newer.root = file_version.root AND newer.path = file_version.path)`).run(now() - HISTORY_RETENTION_MS);
+    } finally {
+      opened.close();
+    }
+  } catch (error62) {
+    status = { reason: describeError(error62), removed: false };
+  }
+  function use(work) {
+    if (status != null) {
+      throw new Error(status.reason);
+    }
+    if (existsSync2(file2) == false) {
+      disable("history.db is gone", true);
+      throw new Error("history.db is gone");
+    }
+    let opened = null;
+    try {
+      opened = new (loadSqlite()).DatabaseSync(file2);
+      opened.exec(`PRAGMA busy_timeout=${HISTORY_BUSY_TIMEOUT_MS}`);
+      return work(opened);
+    } catch (error62) {
+      if (isBusyError(error62) == true) {
+        throw new HistoryBusyError();
+      }
+      disable(describeError(error62), false);
+      throw error62;
+    } finally {
+      try {
+        opened?.close();
+      } catch {
+      }
+    }
+  }
+  function read(fallback, work) {
+    if (status != null) {
+      return fallback;
+    }
+    try {
+      return use(work);
+    } catch (error62) {
+      if (error62 instanceof HistoryBusyError) {
+        throw error62;
+      }
+      return fallback;
+    }
+  }
+  function readBaselines(root, sinceMs) {
+    return read(/* @__PURE__ */ new Map(), (opened) => {
+      const rows = opened.prepare(`SELECT v.path AS path, v.observed_at AS observed_at, v.blocks_hash AS blocks_hash, v.blocks IS NULL AS deleted
+                FROM file_version v
+                JOIN (SELECT path, MAX(observed_at) AS at FROM file_version WHERE root = ? AND observed_at <= ? GROUP BY path) latest
+                  ON latest.path = v.path AND latest.at = v.observed_at
+                WHERE v.root = ?`).all(root, sinceMs, root);
+      const result = /* @__PURE__ */ new Map();
+      for (const row of rows) {
+        result.set(row.path, { observedMs: row.observed_at, hash: row.blocks_hash, deleted: row.deleted != 0 });
+      }
+      return result;
+    });
+  }
+  return {
+    file: file2,
+    status: () => status,
+    onTrouble(listener) {
+      listeners.push(listener);
+    },
+    lastHashes(root) {
+      const result = /* @__PURE__ */ new Map();
+      for (const [path, baseline] of readBaselines(root, Number.MAX_SAFE_INTEGER)) {
+        result.set(path, baseline.hash);
+      }
+      return result;
+    },
+    append(root, entries) {
+      if (entries.length == 0) {
+        return true;
+      }
+      try {
+        use((opened) => {
+          const selectLast = opened.prepare("SELECT blocks_hash FROM file_version WHERE root = ? AND path = ? ORDER BY observed_at DESC LIMIT 1");
+          const insert = opened.prepare("INSERT INTO file_version (root, path, observed_at, blocks_hash, blocks) VALUES (?, ?, ?, ?, ?) ON CONFLICT (root, path, observed_at) DO NOTHING");
+          opened.exec("BEGIN IMMEDIATE");
+          try {
+            for (const entry of entries) {
+              const last = selectLast.get(root, entry.path);
+              if (last != null && last.blocks_hash == entry.hash) {
+                continue;
+              }
+              let blocksText = null;
+              if (entry.blocks != null) {
+                blocksText = encodeBlocks(entry.blocks);
+              }
+              insert.run(root, entry.path, entry.observedMs, entry.hash, blocksText);
+            }
+            opened.exec("COMMIT");
+          } catch (error62) {
+            try {
+              opened.exec("ROLLBACK");
+            } catch {
+            }
+            throw error62;
+          }
+        });
+        return true;
+      } catch (error62) {
+        if (error62 instanceof HistoryBusyError && hasWarnedBusy == false) {
+          hasWarnedBusy = true;
+          say("librian: history.db is locked by another process; the change will be recorded on a later round.");
+        }
+        return false;
+      }
+    },
+    firstObservedMs(root) {
+      return read(null, (opened) => {
+        const row = opened.prepare("SELECT MIN(observed_at) AS first FROM file_version WHERE root = ?").get(root);
+        return row.first;
+      });
+    },
+    baselines: readBaselines,
+    blocksAt(root, path, observedMs) {
+      return read(null, (opened) => {
+        const row = opened.prepare("SELECT blocks FROM file_version WHERE root = ? AND path = ? AND observed_at = ?").get(root, path, observedMs);
+        if (row == null || row.blocks == null) {
+          return null;
+        }
+        return decodeBlocks(row.blocks);
+      });
+    },
+    close() {
+      if (status == null) {
+        status = { reason: "the history was closed", removed: false };
+      }
+    }
+  };
+}
+var sharedStores = /* @__PURE__ */ new Map();
+function sharedHistoryStore(file2) {
+  let store = sharedStores.get(file2);
+  if (store == null) {
+    store = openHistoryStore(file2);
+    sharedStores.set(file2, store);
+  }
+  return store;
+}
+
 // src/modules/docs/library.ts
 var ALWAYS_EXCLUDED_DIRECTORY = "node_modules";
 function normalizeExclude(entry) {
@@ -7733,7 +8187,7 @@ function listMarkdownPaths(root, exclude, limits) {
         if (entry.name.startsWith(".") == true || entry.name == ALWAYS_EXCLUDED_DIRECTORY) {
           continue;
         }
-        walk(join2(absoluteDirectory, entry.name), relativePath + "/");
+        walk(join3(absoluteDirectory, entry.name), relativePath + "/");
         continue;
       }
       if (entry.isFile() == true && /\.md$/i.test(entry.name) == true) {
@@ -7758,11 +8212,52 @@ function openLibrary(options) {
     name = root;
   }
   const cache = /* @__PURE__ */ new Map();
+  const store = options.history ?? null;
+  const now = options.now ?? Date.now;
+  let startedMs = null;
+  let observedMs = null;
+  let lastHashes = null;
+  const unrecorded = /* @__PURE__ */ new Map();
   function refresh() {
+    let stamp = now();
+    if (observedMs != null && stamp <= observedMs) {
+      stamp = observedMs + 1;
+    }
+    observedMs = stamp;
+    if (startedMs == null) {
+      startedMs = stamp;
+    }
+    const pending = [];
+    const isFirstRefresh = lastHashes == null;
+    if (store != null && lastHashes == null) {
+      try {
+        lastHashes = store.lastHashes(root);
+      } catch {
+        lastHashes = /* @__PURE__ */ new Map();
+      }
+    }
+    const noteVersion = (path, listed) => {
+      if (lastHashes == null || lastHashes.get(path) == listed.hash) {
+        return;
+      }
+      lastHashes.set(path, listed.hash);
+      pending.push({ path, observedMs: stamp, blocks: listed.blocks, hash: listed.hash });
+    };
+    const noteDeleted = (path) => {
+      if (lastHashes == null) {
+        return;
+      }
+      const last = lastHashes.get(path);
+      if (last == null || last == DELETED_HASH) {
+        return;
+      }
+      lastHashes.set(path, DELETED_HASH);
+      pending.push({ path, observedMs: stamp, blocks: null, hash: DELETED_HASH });
+    };
     const documents = [];
     const seen = /* @__PURE__ */ new Set();
     for (const path of listMarkdownPaths(root, options.exclude).paths.sort(compareText)) {
-      const absolutePath = join2(root, path);
+      const absolutePath = join3(root, path);
       let modifiedMs;
       let size;
       try {
@@ -7787,123 +8282,68 @@ function openLibrary(options) {
       } catch {
         continue;
       }
-      cache.set(path, { modifiedMs, size, document });
+      let listed = null;
+      if (store != null) {
+        listed = listBlocks(document);
+        noteVersion(path, listed);
+      }
+      cache.set(path, { modifiedMs, size, document, listed });
       seen.add(path);
       documents.push(document);
     }
     for (const path of [...cache.keys()]) {
       if (seen.has(path) == false) {
         cache.delete(path);
+        noteDeleted(path);
       }
     }
-    return documents;
-  }
-  return { root, name, refresh };
-}
-
-// src/modules/tools/format.ts
-function textResult(text2) {
-  return { content: [{ type: "text", text: text2 }] };
-}
-function errorResult(message) {
-  return { content: [{ type: "text", text: message }], isError: true };
-}
-function byteLength(text2) {
-  return Buffer.byteLength(text2, "utf8");
-}
-function formatSize(bytes) {
-  if (bytes < 1e3) {
-    return bytes + "B";
-  }
-  if (bytes < 99950) {
-    return (bytes / 1e3).toFixed(1) + "K";
-  }
-  if (bytes < 999500) {
-    return Math.round(bytes / 1e3) + "K";
-  }
-  return (bytes / 1e6).toFixed(2) + "M";
-}
-function pluralize(count, noun) {
-  if (count == 1) {
-    return count + " " + noun;
-  }
-  return count + " " + noun + "s";
-}
-function truncateChars(text2, maxChars) {
-  const characters = Array.from(text2);
-  if (characters.length <= maxChars) {
-    return text2;
-  }
-  return characters.slice(0, maxChars - 1).join("") + "\u2026";
-}
-function takeBytes(text2, maxBytes) {
-  let result = "";
-  let used = 0;
-  for (const character of text2) {
-    const characterBytes = byteLength(character);
-    if (used + characterBytes > maxBytes) {
-      break;
-    }
-    result += character;
-    used += characterBytes;
-  }
-  return result;
-}
-function headingLabel(document, headingIndex) {
-  const heading = document.headings[headingIndex];
-  return "#".repeat(heading.level) + " " + truncateChars(heading.title, TITLE_MAX_CHARS);
-}
-function headingChain(document, headingIndex) {
-  const labels = [headingLabel(document, headingIndex)];
-  let ancestor = document.headings[headingIndex].parent;
-  while (ancestor != null) {
-    if (ancestor != document.titleIndex) {
-      labels.unshift(headingLabel(document, ancestor));
-    }
-    ancestor = document.headings[ancestor].parent;
-  }
-  return labels.join(" \u203A ");
-}
-function rangeHeader(document, start, end, headingIndex) {
-  let header = document.path + ":" + start + "-" + end + " \xB7 " + formatSize(document.bytesOf(start, end));
-  if (headingIndex != null) {
-    header += " \xB7 " + headingChain(document, headingIndex);
-  }
-  return header;
-}
-function cutPage(document, start, end, budgetBytes) {
-  const joinLines2 = (lastLine2) => document.lines.slice(start - 1, lastLine2).join("\n");
-  if (document.bytesOf(start, end) - 1 <= budgetBytes) {
-    return { text: joinLines2(end), lastLine: end };
-  }
-  let fitting = start - 1;
-  let overflowing = end;
-  while (overflowing - fitting > 1) {
-    const middle = fitting + overflowing >> 1;
-    if (document.bytesOf(start, middle) - 1 <= budgetBytes) {
-      fitting = middle;
-    } else {
-      overflowing = middle;
+    if (isFirstRefresh == true && lastHashes != null) {
+      for (const path of [...lastHashes.keys()]) {
+        if (seen.has(path) == false) {
+          noteDeleted(path);
+        }
+      }
     }
-  }
-  if (fitting < start) {
-    const line = document.lines[start - 1];
-    const marker = "[line " + start + " cut: " + byteLength(line) + "B]";
-    const allowed = budgetBytes - byteLength(marker) - 1;
-    if (allowed <= 0) {
-      return { text: marker, lastLine: start };
+    if (store != null) {
+      for (const entry of pending) {
+        unrecorded.set(entry.path, entry);
+      }
+      if (store.status() != null) {
+        unrecorded.clear();
+      } else if (unrecorded.size > 0 && store.append(root, [...unrecorded.values()]) == true) {
+        unrecorded.clear();
+      }
     }
-    return { text: takeBytes(line, allowed) + " " + marker, lastLine: start };
+    return documents;
   }
-  let lastLine = fitting;
-  const halfway = start + Math.floor((fitting - start) / 2);
-  for (let line = fitting; line > halfway; line--) {
-    if (document.lines[line - 1].trim() == "") {
-      lastLine = line;
-      break;
+  const history = {
+    file: store?.file ?? null,
+    get startedMs() {
+      return startedMs;
+    },
+    get observedMs() {
+      return observedMs;
+    },
+    status() {
+      if (store == null) {
+        return { reason: "history is not enabled", removed: false };
+      }
+      return store.status();
+    },
+    currentBlocks(path) {
+      return cache.get(path)?.listed ?? null;
+    },
+    firstObservedMs() {
+      return store?.firstObservedMs(root) ?? null;
+    },
+    baselines(sinceMs) {
+      return store?.baselines(root, sinceMs) ?? /* @__PURE__ */ new Map();
+    },
+    blocksAt(path, at) {
+      return store?.blocksAt(root, path, at) ?? null;
     }
-  }
-  return { text: joinLines2(lastLine), lastLine };
+  };
+  return { root, name, refresh, history };
 }
 
 // src/modules/cli/folder-check.ts
@@ -7969,7 +8409,7 @@ function checkFolder(root, exclude) {
   const sized = scan.paths.map((path) => {
     let bytes = 0;
     try {
-      bytes = statSync2(join3(root, path)).size;
+      bytes = statSync2(join4(root, path)).size;
     } catch {
       bytes = 0;
     }
@@ -9435,7 +9875,7 @@ var USAGE = [
   "",
   "  --catalog          Read the docs folders from <LIBRIAN_HOME>/catalog.json (default ~/.librian)",
   "  --root <folder>    Markdown docs folder to serve",
-  "  --exclude <name>   Skip a folder name (e.g. evidence) or a root-relative path (e.g. ks/archive); repeatable",
+  "  --exclude <name>   Skip a folder name (e.g. evidence) or a root-relative path (e.g. guide/archive); repeatable",
   `  --max-bytes <n>    Response size limit in UTF-8 bytes (default ${DEFAULT_MAX_BYTES}, minimum ${MIN_MAX_BYTES})`,
   "  --help             Show this help",
   "  --version          Show the version"
@@ -38950,6 +39390,142 @@ var StdioServerTransport = class {
   }
 };
 
+// src/_libs/local-time.ts
+function pad(value, width) {
+  return String(value).padStart(width, "0");
+}
+function formatLocalIso(ms) {
+  const date5 = new Date(ms);
+  const offsetMinutes = -date5.getTimezoneOffset();
+  let sign = "+";
+  if (offsetMinutes < 0) {
+    sign = "-";
+  }
+  const absolute = Math.abs(offsetMinutes);
+  const day = `${pad(date5.getFullYear(), 4)}-${pad(date5.getMonth() + 1, 2)}-${pad(date5.getDate(), 2)}`;
+  const time3 = `${pad(date5.getHours(), 2)}:${pad(date5.getMinutes(), 2)}:${pad(date5.getSeconds(), 2)}.${pad(date5.getMilliseconds(), 3)}`;
+  return `${day}T${time3}${sign}${pad(Math.floor(absolute / 60), 2)}:${pad(absolute % 60, 2)}`;
+}
+var SINCE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:[.,](\d{1,9}))?)?(Z|z|[+-]\d{2}(?::?\d{2})?)?)?$/;
+function parseIsoTime(text2) {
+  const match = SINCE_PATTERN.exec(text2.trim());
+  if (match == null) {
+    return null;
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4] ?? "0");
+  const minute = Number(match[5] ?? "0");
+  const second = Number(match[6] ?? "0");
+  const millisecond = Number((match[7] ?? "0").padEnd(3, "0").slice(0, 3));
+  const zone = match[8];
+  if (month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 59) {
+    return null;
+  }
+  const daysInMonth = new Date(Date.UTC(2e3 + year % 400, month, 0)).getUTCDate();
+  if (day > daysInMonth) {
+    return null;
+  }
+  if (zone == null) {
+    const local = new Date(2e3, 0, 1);
+    local.setFullYear(year, month - 1, day);
+    local.setHours(hour, minute, second, millisecond);
+    return local.getTime();
+  }
+  let offsetMinutes = 0;
+  if (zone != "Z" && zone != "z") {
+    const digits = zone.slice(1).replace(":", "");
+    const offsetHours = Number(digits.slice(0, 2));
+    const offsetRest = Number(digits.slice(2, 4) || "0");
+    if (offsetHours > 23 || offsetRest > 59) {
+      return null;
+    }
+    offsetMinutes = offsetHours * 60 + offsetRest;
+    if (zone[0] == "-") {
+      offsetMinutes = -offsetMinutes;
+    }
+  }
+  const utc = new Date(Date.UTC(2e3, 0, 1));
+  utc.setUTCFullYear(year, month - 1, day);
+  utc.setUTCHours(hour, minute, second, millisecond);
+  return utc.getTime() - offsetMinutes * 6e4;
+}
+
+// src/modules/docs/block-diff.ts
+var MAX_DIFF_CELLS = 16e6;
+function compareMatched(before, after, changes) {
+  if (before.hash != after.hash) {
+    changes.push({ kind: "changed", before, after });
+  }
+}
+function diffMiddle(before, offset, after, changes) {
+  const beforeCount = before.length;
+  const afterCount = after.length;
+  const width = afterCount + 1;
+  if (beforeCount == 0 || afterCount == 0 || (beforeCount + 1) * width > MAX_DIFF_CELLS) {
+    for (let position = 0; position < before.length; position += 1) {
+      changes.push({ kind: "removed", before: before[position], index: offset + position });
+    }
+    for (const block of after) {
+      changes.push({ kind: "added", after: block });
+    }
+    return;
+  }
+  const lengths = new Uint16Array((beforeCount + 1) * width);
+  for (let row2 = beforeCount - 1; row2 >= 0; row2 -= 1) {
+    for (let column2 = afterCount - 1; column2 >= 0; column2 -= 1) {
+      if (before[row2].key == after[column2].key) {
+        lengths[row2 * width + column2] = lengths[(row2 + 1) * width + column2 + 1] + 1;
+      } else {
+        lengths[row2 * width + column2] = Math.max(lengths[(row2 + 1) * width + column2], lengths[row2 * width + column2 + 1]);
+      }
+    }
+  }
+  let row = 0;
+  let column = 0;
+  while (row < beforeCount && column < afterCount) {
+    if (before[row].key == after[column].key) {
+      compareMatched(before[row], after[column], changes);
+      row += 1;
+      column += 1;
+    } else if (lengths[(row + 1) * width + column] >= lengths[row * width + column + 1]) {
+      changes.push({ kind: "removed", before: before[row], index: offset + row });
+      row += 1;
+    } else {
+      changes.push({ kind: "added", after: after[column] });
+      column += 1;
+    }
+  }
+  while (row < beforeCount) {
+    changes.push({ kind: "removed", before: before[row], index: offset + row });
+    row += 1;
+  }
+  while (column < afterCount) {
+    changes.push({ kind: "added", after: after[column] });
+    column += 1;
+  }
+}
+function diffBlocks(before, after) {
+  const changes = [];
+  let prefix = 0;
+  while (prefix < before.length && prefix < after.length && before[prefix].key == after[prefix].key) {
+    compareMatched(before[prefix], after[prefix], changes);
+    prefix += 1;
+  }
+  let beforeEnd = before.length;
+  let afterEnd = after.length;
+  while (beforeEnd > prefix && afterEnd > prefix && before[beforeEnd - 1].key == after[afterEnd - 1].key) {
+    beforeEnd -= 1;
+    afterEnd -= 1;
+  }
+  diffMiddle(before.slice(prefix, beforeEnd), prefix, after.slice(prefix, afterEnd), changes);
+  for (let offset = 0; beforeEnd + offset < before.length; offset += 1) {
+    compareMatched(before[beforeEnd + offset], after[afterEnd + offset], changes);
+  }
+  return changes;
+}
+
 // src/modules/tools/list.ts
 var COLLAPSED_NOTE = "Folders are collapsed; call list with prefix to open one.";
 function directoryOf(path) {
@@ -39044,7 +39620,7 @@ function normalizePrefix(prefix) {
 }
 function runList(library, args, maxBytes) {
   if (args.prefix != null && typeof args.prefix != "string") {
-    return errorResult('prefix must be a string: the start of a path such as "ks/ci".');
+    return errorResult('prefix must be a string: the start of a path such as "guide/api".');
   }
   let prefix = "";
   if (typeof args.prefix == "string") {
@@ -39097,6 +39673,193 @@ function runList(library, args, maxBytes) {
   ].join("\n"));
 }
 
+// src/modules/tools/since.ts
+var SINCE_ECHO_MAX_CHARS = 40;
+function readSince(value) {
+  if (value == null) {
+    return { ok: true, sinceMs: null };
+  }
+  if (typeof value == "string") {
+    const sinceMs = parseIsoTime(value);
+    if (sinceMs != null) {
+      return { ok: true, sinceMs };
+    }
+  }
+  const echo = JSON.stringify(truncateChars(String(value), SINCE_ECHO_MAX_CHARS));
+  return {
+    ok: false,
+    result: errorResult(`since ${echo} is not an ISO 8601 time. Use 2026-11-08T09:00:00+09:00, 2026-11-08T09:00:00Z, 2026-11-08T09:00 (local time) or 2026-11-08 (local midnight).`)
+  };
+}
+
+// src/modules/tools/changes.ts
+var SESSION_START_NOTE = "(session start)";
+var ACTION_WIDTH = 7;
+function blockLine(change, document, before) {
+  if (change.kind == "removed") {
+    return "  " + "removed".padEnd(ACTION_WIDTH) + "  " + labelOfRecord(before, change.index);
+  }
+  const block = change.after;
+  const current = document;
+  const size = formatSize(current.bytesOf(block.start, block.end));
+  return "  " + change.kind.padEnd(ACTION_WIDTH) + "  " + current.path + ":" + block.start + "-" + block.end + " \xB7 " + labelOfBlock(current, block) + " \xB7 " + size;
+}
+function reportFile(library, document, path, baseline) {
+  const history = library.history;
+  const hasBaseline = baseline != null && baseline.deleted == false;
+  if (document == null) {
+    if (baseline == null || hasBaseline == false) {
+      return null;
+    }
+    const text2 = path + " \xB7 removed";
+    const count = history.blocksAt(path, baseline.observedMs)?.length ?? 0;
+    return { path, blockCount: count, text: text2, foldedText: text2 };
+  }
+  const current = history.currentBlocks(path);
+  if (current == null) {
+    return null;
+  }
+  if (baseline == null || hasBaseline == false) {
+    const text2 = path + " \xB7 added \xB7 " + formatSize(document.totalBytes);
+    return { path, blockCount: current.blocks.length, text: text2, foldedText: text2 };
+  }
+  if (baseline.hash == current.hash) {
+    return null;
+  }
+  const before = history.blocksAt(path, baseline.observedMs);
+  if (before == null) {
+    return null;
+  }
+  const changes = diffBlocks(before, current.blocks);
+  if (changes.length == 0) {
+    return null;
+  }
+  const removedCount = changes.filter((change) => change.kind == "removed").length;
+  return {
+    path,
+    blockCount: changes.length,
+    text: [path, ...changes.map((change) => blockLine(change, document, before))].join("\n"),
+    foldedText: path + " \xB7 changed \xB7 " + changes.length + " of " + (current.blocks.length + removedCount) + " blocks; outline it"
+  };
+}
+function runChanges(library, args, maxBytes) {
+  const sinceArgument = readSince(args.since);
+  if (sinceArgument.ok == false) {
+    return sinceArgument.result;
+  }
+  let prefix = "";
+  if (typeof args.prefix == "string") {
+    prefix = normalizePrefix(args.prefix);
+  }
+  let offset = 0;
+  if (typeof args.offset == "number") {
+    offset = args.offset;
+  }
+  const documents = library.refresh();
+  const failedBefore = unavailableResult(library);
+  if (failedBefore != null) {
+    return failedBefore;
+  }
+  let result;
+  try {
+    result = buildReport(library, documents, { requestedSinceMs: sinceArgument.sinceMs, prefix, offset, maxBytes });
+  } catch (error62) {
+    if (error62 instanceof HistoryBusyError) {
+      return errorResult(HISTORY_BUSY_MESSAGE);
+    }
+    throw error62;
+  }
+  return unavailableResult(library) ?? result;
+}
+function unavailableResult(library) {
+  const status = library.history.status();
+  if (status == null) {
+    return null;
+  }
+  return errorResult(historyToolMessage(library.history.file ?? "history.db", status));
+}
+function buildReport(library, documents, request) {
+  const { prefix, offset, maxBytes } = request;
+  const history = library.history;
+  const asOfMs = history.observedMs ?? Date.now();
+  const startedMs = history.startedMs ?? asOfMs;
+  const firstMs = history.firstObservedMs() ?? startedMs;
+  let sinceMs = startedMs;
+  if (request.requestedSinceMs != null) {
+    sinceMs = request.requestedSinceMs;
+  }
+  const notes = [];
+  if (sinceMs < firstMs) {
+    sinceMs = firstMs;
+    notes.push(`History starts ${formatLocalIso(firstMs)}; earlier edits were not recorded.`);
+  }
+  let sinceLabel = formatLocalIso(sinceMs);
+  if (sinceMs == startedMs) {
+    sinceLabel += " " + SESSION_START_NOTE;
+  }
+  const asOfLine = "As of " + formatLocalIso(asOfMs) + ". Pass this as `since` to see only later changes.";
+  const documentByPath = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    documentByPath.set(document.path, document);
+  }
+  const baselines = history.baselines(sinceMs);
+  const paths = new Set(documentByPath.keys());
+  for (const path of baselines.keys()) {
+    paths.add(path);
+  }
+  const reports = [];
+  for (const path of [...paths].filter((candidate) => candidate.startsWith(prefix) == true).sort(compareText)) {
+    const report = reportFile(library, documentByPath.get(path), path, baselines.get(path));
+    if (report != null) {
+      reports.push(report);
+    }
+  }
+  if (reports.length == 0) {
+    let scope = "";
+    if (prefix != "") {
+      scope = ` under "${prefix}"`;
+    }
+    return textResult([`No changes since ${sinceLabel}${scope}.`, asOfLine, ...notes].join("\n"));
+  }
+  const totalFiles = reports.length;
+  const totalBlocks = reports.reduce((sum, report) => sum + report.blockCount, 0);
+  const summary = `Changes since ${sinceLabel} \xB7 ${pluralize(totalFiles, "file")} \xB7 ${pluralize(totalBlocks, "block")}`;
+  if (offset >= totalFiles) {
+    return textResult([summary, asOfLine, ...notes, `Offset ${offset} is past the last file; ${pluralize(totalFiles, "file")} changed.`].join("\n"));
+  }
+  const fixedBytes = byteLength([`${summary} \xB7 files ${totalFiles}-${totalFiles}`, asOfLine, ...notes, ""].join("\n")) + 1;
+  const moreReserve = byteLength(`More: offset=${totalFiles}`) + 1;
+  const chunks = [];
+  let used = fixedBytes;
+  for (let position = offset; position < totalFiles; position += 1) {
+    const report = reports[position];
+    let reserve = 0;
+    if (position < totalFiles - 1) {
+      reserve = moreReserve;
+    }
+    let text2 = report.text;
+    if (chunks.length == 0 && used + byteLength(text2) + 1 + moreReserve > maxBytes) {
+      text2 = report.foldedText;
+    }
+    const chunkBytes = byteLength(text2) + 1;
+    if (chunks.length > 0 && used + chunkBytes + reserve > maxBytes) {
+      break;
+    }
+    chunks.push(text2);
+    used += chunkBytes;
+  }
+  const shown = chunks.length;
+  let header = summary;
+  if (offset > 0 || offset + shown < totalFiles) {
+    header += ` \xB7 files ${offset + 1}-${offset + shown}`;
+  }
+  const lines = [header, asOfLine, ...notes, "", ...chunks];
+  if (offset + shown < totalFiles) {
+    lines.push(`More: offset=${offset + shown}`);
+  }
+  return textResult(lines.join("\n"));
+}
+
 // src/modules/docs/reference.ts
 import { realpathSync as realpathSync2 } from "node:fs";
 import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve3, sep as sep2 } from "node:path";
@@ -39508,6 +40271,8 @@ var ELLIPSIS2 = "\u2026";
 var ELLIPSIS_BYTES = Buffer.byteLength(ELLIPSIS2);
 var QUERY_ECHO_MAX_CHARS = 80;
 var WORD_CHARACTERS = /[a-z0-9_]/;
+var BM25_K1 = 1.2;
+var BM25_B = 0.75;
 function normalize(text2) {
   return text2.normalize("NFC").toLowerCase();
 }
@@ -39576,7 +40341,7 @@ function chainIndices(document, index) {
   }
   return chain;
 }
-function isBlank(document, start, end) {
+function isBlank2(document, start, end) {
   for (let line = start; line <= end; line += 1) {
     if (document.lines[line - 1].trim() != "") {
       return false;
@@ -39605,14 +40370,18 @@ function matchBlock(document, start, end, chainText, label, bodyStart, terms) {
     }
     hits += counts[termIndex];
   }
-  return { document, start, end, label, bytes: document.bytesOf(start, end), hits, titleHits, bodyStart };
+  return { document, start, end, label, bytes: document.bytesOf(start, end), termCounts: counts, hits, titleHits, score: 0, bodyStart };
 }
 function collectMatches(documents, terms) {
   const matches = [];
+  let scannedBytes = 0;
+  let scannedBlocks = 0;
   for (const document of documents) {
     const headings = document.headings;
     const introEnd = headings.length == 0 ? document.lines.length : headings[0].line - 1;
-    if (introEnd >= 1 && isBlank(document, 1, introEnd) == false) {
+    if (introEnd >= 1 && isBlank2(document, 1, introEnd) == false) {
+      scannedBytes += document.bytesOf(1, introEnd);
+      scannedBlocks += 1;
       const introMatch = matchBlock(document, 1, introEnd, "", INTRO_TITLE, 1, terms);
       if (introMatch != null) {
         matches.push(introMatch);
@@ -39620,6 +40389,8 @@ function collectMatches(documents, terms) {
     }
     for (let index = 0; index < headings.length; index += 1) {
       const heading = headings[index];
+      scannedBytes += document.bytesOf(heading.line, heading.blockEnd);
+      scannedBlocks += 1;
       const chainText = chainIndices(document, index).map((position) => document.headings[position].title).join("\n");
       const label = headingChain(document, index);
       const match = matchBlock(document, heading.line, heading.blockEnd, chainText, label, heading.line + 1, terms);
@@ -39628,14 +40399,22 @@ function collectMatches(documents, terms) {
       }
     }
   }
-  return matches;
+  return { matches, averageBytes: scannedBlocks == 0 ? 1 : scannedBytes / scannedBlocks };
+}
+function scoreMatch(match, averageBytes) {
+  const lengthFactor = 1 - BM25_B + BM25_B * (match.bytes / averageBytes);
+  let score = 0;
+  for (const termCount of match.termCounts) {
+    score += termCount * (BM25_K1 + 1) / (termCount + BM25_K1 * lengthFactor);
+  }
+  return score;
 }
 function compareMatches(left, right) {
   if (left.titleHits != right.titleHits) {
     return right.titleHits - left.titleHits;
   }
-  if (left.hits != right.hits) {
-    return right.hits - left.hits;
+  if (left.score != right.score) {
+    return right.score - left.score;
   }
   const byPath = compareText(left.document.path, right.document.path);
   if (byPath != 0) {
@@ -39725,7 +40504,10 @@ function runSearch(library, args, maxBytes) {
     return errorResult("Query is empty. Give one or more words; wrap a phrase in double quotes.");
   }
   const documents = library.refresh().filter((document) => document.path.startsWith(prefix));
-  const matches = collectMatches(documents, terms);
+  const { matches, averageBytes } = collectMatches(documents, terms);
+  for (const match of matches) {
+    match.score = scoreMatch(match, averageBytes);
+  }
   matches.sort(compareMatches);
   const fileCount = new Set(matches.map((match) => match.document.path)).size;
   const echo = JSON.stringify(truncateChars(query.trim(), QUERY_ECHO_MAX_CHARS));
@@ -39789,7 +40571,8 @@ var INSTRUCTIONS_USAGE = [
   "Start with `list` (files with size and title) or `search` (blocks matching all words), `outline` a file to see headings with line ranges and sizes, then `read` only the part you need.",
   "A ref is `path`, `path#heading` (heading text or GitHub anchor) or `path:start-end`.",
   "Every call re-reads files changed on disk, so line numbers are always current.",
-  "When you hand a ref to another agent, prefer `path#heading`: line ranges move when the file is edited."
+  "When you hand a ref to another agent, prefer `path#heading`: line ranges move when the file is edited.",
+  "To see what others edited while you worked, call `changes` (blocks added, changed or removed since the session start) and pass its `As of` time back as `since` to get only later edits."
 ].join(" ");
 function buildRootInstructions(rootName) {
   return `librian reads the markdown docs under \`${rootName}\` without loading whole files. ${INSTRUCTIONS_USAGE}`;
@@ -39801,9 +40584,9 @@ function describeTools(folder) {
   return [
     {
       name: nameOf("list"),
-      description: `${tag}List the markdown files under ${where} with size and document title, grouped by folder. Use prefix to open one folder: \`ks/ci\` matches \`ks/ci/\u2026\` and \`ks/ci-web-renewal.md\`, \`ks/ci/\` matches the folder only.`,
+      description: `${tag}List the markdown files under ${where} with size and document title, grouped by folder. Use prefix to open one folder: \`guide/api\` matches \`guide/api/\u2026\` and \`guide/api-notes.md\`, \`guide/api/\` matches the folder only.`,
       inputSchema: {
-        prefix: external_exports.string().optional().describe("Root-relative path prefix, e.g. `ks/ci/`. Omit to list everything.")
+        prefix: external_exports.string().optional().describe("Root-relative path prefix, e.g. `guide/api/`. Omit to list everything.")
       },
       runner: runList
     },
@@ -39833,6 +40616,16 @@ function describeTools(folder) {
         offset: external_exports.number().int().min(0).optional().describe("Results to skip, from the `More: offset=N` line of the previous page.")
       },
       runner: runSearch
+    },
+    {
+      name: nameOf("changes"),
+      description: `${tag}List the blocks (a heading and the text up to the next heading) that were added, changed or removed since this session started, or since a time you give, so you can read only what moved. Added and removed files appear as one line. Each result gives \`path:start-end\` to pass to read. The result ends with an \`As of\` time: pass it as since next time to get only later edits (when paging with offset, keep the same since). The history of block hashes is kept for 30 days across restarts, so an earlier since works too.`,
+      inputSchema: {
+        since: external_exports.string().optional().describe("ISO 8601 time, e.g. `2026-11-08T09:00:00+09:00`; local time when it has no zone. Omit for the session start (when this server started)."),
+        prefix: external_exports.string().optional().describe("Root-relative path prefix to look under."),
+        offset: external_exports.number().int().min(0).optional().describe("Files to skip, from the `More: offset=N` line of the previous page.")
+      },
+      runner: runChanges
     }
   ];
 }
@@ -39868,7 +40661,7 @@ function createLibrianServer(options) {
     version: options.version
   });
 }
-async function serveOverStdio(server) {
+async function serveOverStdio(server, options = {}) {
   let stopping = false;
   let stdoutBroken = false;
   function shutdown(exitCode) {
@@ -39876,6 +40669,7 @@ async function serveOverStdio(server) {
       return;
     }
     stopping = true;
+    options.onShutdown?.();
     const deadline = setTimeout(() => {
       process.exit(exitCode);
     }, SHUTDOWN_DEADLINE_MS);
@@ -39901,11 +40695,18 @@ async function serveOverStdio(server) {
     stdoutBroken = true;
     shutdown(0);
   });
+  process.on("SIGINT", () => {
+    shutdown(0);
+  });
+  process.on("SIGTERM", () => {
+    shutdown(0);
+  });
   process.on("uncaughtException", (error62) => {
     writeStderrLine(`librian: uncaught exception: ${error62.stack ?? error62.message}`);
     shutdown(1);
   });
   await server.connect(new StdioServerTransport());
+  return { shutdown };
 }
 
 // src/modules/mcp/catalog-server.ts
@@ -39916,7 +40717,7 @@ function isFolder2(path) {
     return false;
   }
 }
-function openCatalogFolders(catalog) {
+function openCatalogFolders(catalog, historyFor) {
   const folders = [];
   const unavailable = [];
   for (const entry of catalog.entries) {
@@ -39924,7 +40725,7 @@ function openCatalogFolders(catalog) {
       unavailable.push({ name: entry.name, root: entry.root });
       continue;
     }
-    const library = openLibrary({ root: entry.root, exclude: entry.exclude });
+    const library = openLibrary({ root: entry.root, exclude: entry.exclude, history: historyFor?.(entry.root) });
     folders.push({ name: entry.name, root: library.root, library, maxBytes: entry.maxBytes, fileCount: library.refresh().length });
   }
   return { folders, unavailable };
@@ -39976,14 +40777,62 @@ function catalogReadyLine(version2, home, catalog, opened) {
   return parts.join(" \xB7 ");
 }
 
+// src/modules/mcp/history-observer.ts
+function isParentProcessAlive() {
+  try {
+    process.kill(process.ppid, 0);
+    return true;
+  } catch (error62) {
+    return error62.code != "ESRCH";
+  }
+}
+function startHistoryObserver(options) {
+  let isRunning = false;
+  let isStopped = false;
+  const isParentAlive = options.isParentAlive ?? isParentProcessAlive;
+  const timer = setInterval(() => {
+    if (isRunning == true || isStopped == true) {
+      return;
+    }
+    if (isParentAlive() == false) {
+      isStopped = true;
+      clearInterval(timer);
+      options.onParentGone?.();
+      return;
+    }
+    isRunning = true;
+    try {
+      for (const library of options.libraries) {
+        if (isStopped == true) {
+          break;
+        }
+        try {
+          library.refresh();
+        } catch (error62) {
+          options.writeError(`librian: history refresh of ${library.root} failed: ${error62 instanceof Error ? error62.message : String(error62)}`);
+        }
+      }
+    } finally {
+      isRunning = false;
+    }
+  }, options.intervalMs);
+  timer.unref();
+  return {
+    stop() {
+      isStopped = true;
+      clearInterval(timer);
+    }
+  };
+}
+
 // src/modules/setup/runtime.ts
-import { existsSync as existsSync2, lstatSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, realpathSync as realpathSync3, rmSync as rmSync2 } from "node:fs";
-import { dirname, join as join5, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync3, lstatSync, mkdirSync as mkdirSync3, readFileSync as readFileSync3, realpathSync as realpathSync3, rmSync as rmSync2 } from "node:fs";
+import { dirname as dirname2, join as join6, resolve as resolve4 } from "node:path";
 
 // src/modules/setup/commands.ts
 import { spawn } from "node:child_process";
 import { accessSync, constants, statSync as statSync4 } from "node:fs";
-import { delimiter, join as join4 } from "node:path";
+import { delimiter, join as join5 } from "node:path";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var WINDOWS_SCRIPT_PATTERN = /\.(cmd|bat)$/i;
 function quotePart(part) {
@@ -40012,7 +40861,7 @@ function findOnPath(name, env = process.env, platform = process.platform) {
   }
   for (const directory of directories) {
     for (const candidate of candidates) {
-      const path = join4(directory, candidate);
+      const path = join5(directory, candidate);
       try {
         if (statSync4(path).isFile() == false) {
           continue;
@@ -40121,17 +40970,17 @@ var PACKAGE_NAME = "librian";
 var INSTALL_TIMEOUT_MS = 18e4;
 var VIEW_TIMEOUT_MS = 3e4;
 function runtimeDirectory(home) {
-  return join5(home, "runtime");
+  return join6(home, "runtime");
 }
 function packageDirectory(home) {
-  return join5(runtimeDirectory(home), "node_modules", PACKAGE_NAME);
+  return join6(runtimeDirectory(home), "node_modules", PACKAGE_NAME);
 }
 function runtimeCliPath(home) {
-  return join5(packageDirectory(home), "dist", "cli.js");
+  return join6(packageDirectory(home), "dist", "cli.js");
 }
 function readPackageVersion(directory) {
   try {
-    const parsed = JSON.parse(readFileSync3(join5(directory, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync3(join6(directory, "package.json"), "utf8"));
     return typeof parsed.version == "string" ? parsed.version : null;
   } catch {
     return null;
@@ -40139,7 +40988,7 @@ function readPackageVersion(directory) {
 }
 function runtimeStatus(home) {
   const cliPath = runtimeCliPath(home);
-  if (existsSync2(cliPath) == false) {
+  if (existsSync3(cliPath) == false) {
     return { state: "missing", version: null, cliPath };
   }
   const directory = packageDirectory(home);
@@ -40161,13 +41010,13 @@ function compareVersions(left, right) {
   return 0;
 }
 function findNpmCli(nodePath) {
-  const nodeDirectory = dirname(nodePath);
+  const nodeDirectory = dirname2(nodePath);
   const candidates = [
-    join5(nodeDirectory, "node_modules", "npm", "bin", "npm-cli.js"),
-    join5(nodeDirectory, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js")
+    join6(nodeDirectory, "node_modules", "npm", "bin", "npm-cli.js"),
+    join6(nodeDirectory, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js")
   ];
   for (const candidate of candidates) {
-    if (existsSync2(candidate) == true) {
+    if (existsSync3(candidate) == true) {
       return resolve4(candidate);
     }
   }
@@ -40199,7 +41048,7 @@ async function runNpm(toolchain, npmArguments, timeoutMs) {
 }
 async function installRuntime(home, spec, toolchain) {
   const directory = runtimeDirectory(home);
-  mkdirSync2(directory, { recursive: true });
+  mkdirSync3(directory, { recursive: true });
   const installed = await runNpm(toolchain, ["install", "--prefix", directory, "--no-audit", "--no-fund", spec], INSTALL_TIMEOUT_MS);
   if (installed.ok == false) {
     return { ok: false, reason: installed.reason };
@@ -40228,10 +41077,21 @@ function uninstallRuntime(home) {
   }
   rmSync2(directory, { recursive: true, force: true });
 }
+function removeHistoryFiles(home) {
+  const file2 = resolveHistoryFile(home, "");
+  for (const path of [file2, file2 + "-wal", file2 + "-shm"]) {
+    try {
+      rmSync2(path, { force: true });
+    } catch (error62) {
+      return `${path} could not be removed (${error62 instanceof Error ? error62.message : String(error62)}); stop the running AI sessions and delete it by hand`;
+    }
+  }
+  return null;
+}
 
 // src/modules/setup/services.ts
 import { homedir as homedir3 } from "node:os";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/modules/setup/probe.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -40338,7 +41198,7 @@ function defaultServiceDependencies() {
   return { ...defaultToolchain(), probe: probeServer };
 }
 function isDefaultHome(home) {
-  return normalizeForCompare(home) == normalizeForCompare(join6(homedir3(), ".librian"));
+  return normalizeForCompare(home) == normalizeForCompare(join7(homedir3(), ".librian"));
 }
 function expectedRegistration(home, toolchain) {
   const environment = {};
@@ -40589,7 +41449,7 @@ async function askConfirm(question, defaultYes) {
   }
 }
 async function uninstall(home, dependencies) {
-  if (await askConfirm("Uninstall the runtime? Docs folders and the catalog are kept.", false) == false) {
+  if (await askConfirm("Uninstall the runtime and the history (history.db)? Docs folders and the catalog are kept.", false) == false) {
     return;
   }
   const registered = readCatalog(home).services;
@@ -40609,7 +41469,13 @@ async function uninstall(home, dependencies) {
     }
   }
   uninstallRuntime(home);
+  const historyProblem = removeHistoryFiles(home);
+  if (historyProblem == null) {
+    writeLine(`${styled("done", "green")} uninstall: the runtime folder and history.db are removed`);
+    return;
+  }
   writeLine(`${styled("done", "green")} uninstall: the runtime folder is removed`);
+  writeLine(styled(historyProblem, "yellow"));
 }
 async function openRuntimeScreen(home, dependencies = defaultServiceDependencies()) {
   let latest = null;
@@ -40772,6 +41638,21 @@ async function openServicesScreen(home, dependencies = defaultServiceDependencie
 
 // src/cli.ts
 var EXIT_USAGE2 = 2;
+function watchHistory(stores) {
+  for (const store of new Set(stores)) {
+    const status = store.status();
+    if (status != null) {
+      writeStderrLine(describeHistoryTrouble(store.file, status));
+    }
+    store.onTrouble(writeStderrLine);
+  }
+}
+function stopHistory(observer, stores) {
+  observer?.stop();
+  for (const store of stores) {
+    store.close();
+  }
+}
 async function main() {
   const parsed = parseArguments(process.argv.slice(2));
   if (parsed.kind == "help") {
@@ -40823,13 +41704,26 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    const opened = openCatalogFolders(catalog);
+    const stores = [];
+    const opened = openCatalogFolders(catalog, (root2) => {
+      const store2 = sharedHistoryStore(resolveHistoryFile(home, root2));
+      stores.push(store2);
+      return store2;
+    });
     for (const folder of opened.unavailable) {
       writeStderrLine(`librian: docs folder "${folder.name}" (${folder.root}) does not exist or is not a folder; its tools are not offered.`);
     }
     const server2 = createCatalogServer(catalog, opened, package_default.version);
-    await serveOverStdio(server2);
+    let observer2 = null;
+    const serving2 = await serveOverStdio(server2, { onShutdown: () => stopHistory(observer2, stores) });
+    observer2 = startHistoryObserver({
+      libraries: opened.folders.map((folder) => folder.library),
+      intervalMs: HISTORY_REFRESH_MS,
+      writeError: writeStderrLine,
+      onParentGone: () => serving2.shutdown(0)
+    });
     writeStderrLine(catalogReadyLine(package_default.version, home, catalog, opened));
+    watchHistory(stores);
     return;
   }
   const root = resolve5(parsed.root);
@@ -40844,11 +41738,15 @@ async function main() {
     process.exitCode = EXIT_USAGE2;
     return;
   }
-  const library = openLibrary({ root, exclude: parsed.exclude });
+  const store = sharedHistoryStore(resolveHistoryFile(librianHome(), root));
+  const library = openLibrary({ root, exclude: parsed.exclude, history: store });
   const fileCount = library.refresh().length;
   const server = createLibrianServer({ library, maxBytes: parsed.maxBytes, version: package_default.version });
-  await serveOverStdio(server);
+  let observer = null;
+  const serving = await serveOverStdio(server, { onShutdown: () => stopHistory(observer, [store]) });
+  observer = startHistoryObserver({ libraries: [library], intervalMs: HISTORY_REFRESH_MS, writeError: writeStderrLine, onParentGone: () => serving.shutdown(0) });
   writeStderrLine(`librian ${package_default.version} ready \xB7 root ${library.root} \xB7 ${fileCount} files \xB7 pid ${process.pid}`);
+  watchHistory([store]);
 }
 main().catch((error62) => {
   const message = error62 instanceof Error ? error62.stack ?? error62.message : String(error62);