@yurtsever/capsa 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/index.js

@@ -2807,8 +2807,8 @@ var require_validate = __commonJS({
           return data;
       }
       let expr = data;
-      const segments3 = jsonPointer.split("/");
-      for (const segment of segments3) {
+      const segments4 = jsonPointer.split("/");
+      for (const segment of segments4) {
         if (segment) {
           data = (0, codegen_1._)`${data}${(0, codegen_1.getProperty)((0, util_1.unescapeJsonPointer)(segment))}`;
           expr = (0, codegen_1._)`${expr} && ${data}`;
@@ -3870,49 +3870,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative6, options, skipNormalization) {
+    function resolveComponent(base, relative7, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative6 = parse3(serialize(relative6, options), options);
+        relative7 = parse3(serialize(relative7, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative6.scheme) {
-        target.scheme = relative6.scheme;
-        target.userinfo = relative6.userinfo;
-        target.host = relative6.host;
-        target.port = relative6.port;
-        target.path = removeDotSegments(relative6.path || "");
-        target.query = relative6.query;
+      if (!options.tolerant && relative7.scheme) {
+        target.scheme = relative7.scheme;
+        target.userinfo = relative7.userinfo;
+        target.host = relative7.host;
+        target.port = relative7.port;
+        target.path = removeDotSegments(relative7.path || "");
+        target.query = relative7.query;
       } else {
-        if (relative6.userinfo !== void 0 || relative6.host !== void 0 || relative6.port !== void 0) {
-          target.userinfo = relative6.userinfo;
-          target.host = relative6.host;
-          target.port = relative6.port;
-          target.path = removeDotSegments(relative6.path || "");
-          target.query = relative6.query;
+        if (relative7.userinfo !== void 0 || relative7.host !== void 0 || relative7.port !== void 0) {
+          target.userinfo = relative7.userinfo;
+          target.host = relative7.host;
+          target.port = relative7.port;
+          target.path = removeDotSegments(relative7.path || "");
+          target.query = relative7.query;
         } else {
-          if (!relative6.path) {
+          if (!relative7.path) {
             target.path = base.path;
-            if (relative6.query !== void 0) {
-              target.query = relative6.query;
+            if (relative7.query !== void 0) {
+              target.query = relative7.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative6.path[0] === "/") {
-              target.path = removeDotSegments(relative6.path);
+            if (relative7.path[0] === "/") {
+              target.path = removeDotSegments(relative7.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative6.path;
+                target.path = "/" + relative7.path;
               } else if (!base.path) {
-                target.path = relative6.path;
+                target.path = relative7.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative6.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative7.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative6.query;
+            target.query = relative7.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3920,7 +3920,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative6.fragment;
+      target.fragment = relative7.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -4621,15 +4621,15 @@ var require_core = __commonJS({
       errorsText(errors = this.errors, { separator = ", ", dataVar = "data" } = {}) {
         if (!errors || errors.length === 0)
           return "No errors";
-        return errors.map((e) => `${dataVar}${e.instancePath} ${e.message}`).reduce((text, msg) => text + separator + msg);
+        return errors.map((e) => `${dataVar}${e.instancePath} ${e.message}`).reduce((text2, msg) => text2 + separator + msg);
       }
       $dataMetaSchema(metaSchema, keywordsJsonPointers) {
         const rules = this.RULES.all;
         metaSchema = JSON.parse(JSON.stringify(metaSchema));
         for (const jsonPointer of keywordsJsonPointers) {
-          const segments3 = jsonPointer.split("/").slice(1);
+          const segments4 = jsonPointer.split("/").slice(1);
           let keywords = metaSchema;
-          for (const seg of segments3)
+          for (const seg of segments4)
             keywords = keywords[seg];
           for (const key in rules) {
             const rule = rules[key];
@@ -7196,8 +7196,8 @@ var require_dist = __commonJS({
 });
 
 // src/index.ts
-import { readFile as readFile7 } from "fs/promises";
-import { dirname as dirname9, resolve as resolve4 } from "path";
+import { readFile as readFile8 } from "fs/promises";
+import { dirname as dirname10, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // ../core/dist/scanner.js
@@ -7247,7 +7247,7 @@ async function scan(adapters, options = {}) {
   const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
   const issues = [];
   const items = [];
-  const seenItemPaths = /* @__PURE__ */ new Set();
+  const seenItemPaths = /* @__PURE__ */ new Map();
   const scannedRoots = [];
   const formatAdapters = adapters.filter((a) => !isSourceAdapter(a));
   const sourceAdapters = adapters.filter(isSourceAdapter);
@@ -7259,10 +7259,19 @@ async function scan(adapters, options = {}) {
       rootSet.add(resolve(r));
   }
   const roots = [...rootSet].filter((r) => ![...rootSet].some((other) => other !== r && r.startsWith(other + "/")));
-  const addItem = (item) => {
-    if (seenItemPaths.has(item.path))
+  const addItem = (item, adapterId) => {
+    const owner = seenItemPaths.get(item.path);
+    if (owner !== void 0) {
+      if (owner !== adapterId) {
+        issues.push({
+          path: item.path,
+          adapter: adapterId,
+          message: `claimed by both "${owner}" and "${adapterId}"; kept "${owner}" \u2014 two adapters' conventions overlap here`
+        });
+      }
       return;
-    seenItemPaths.add(item.path);
+    }
+    seenItemPaths.set(item.path, adapterId);
     items.push(item);
   };
   const handleEntry = async (entry) => {
@@ -7281,8 +7290,13 @@ async function scan(adapters, options = {}) {
       if (!matched)
         continue;
       try {
-        for (const item of await adapter.parse(entry, env))
-          addItem(item);
+        const parsed = await adapter.parse(entry, env);
+        const result = Array.isArray(parsed) ? { items: parsed } : parsed;
+        for (const item of result.items)
+          addItem(item, adapter.id);
+        for (const issue2 of result.issues ?? []) {
+          issues.push({ adapter: adapter.id, ...issue2 });
+        }
       } catch (err) {
         issues.push({
           path: entry.absPath,
@@ -7356,7 +7370,7 @@ async function scan(adapters, options = {}) {
     for (const adapter of sourceAdapters) {
       try {
         for (const item of await adapter.collect(root, env))
-          addItem(item);
+          addItem(item, adapter.id);
       } catch (err) {
         issues.push({
           path: root,
@@ -7414,20 +7428,24 @@ function findProjectRoot(startDir, homeDir) {
 
 // ../core/dist/chunk.js
 var DEFAULT_MAX_CHARS = 2e3;
-function chunkMarkdown(markdown, maxChars = DEFAULT_MAX_CHARS) {
+var DEFAULT_MAX_HEADING_LEVEL = 6;
+function chunkMarkdown(markdown, options = {}) {
+  const maxChars = options.maxChars ?? DEFAULT_MAX_CHARS;
+  const maxHeadingLevel = options.maxHeadingLevel ?? DEFAULT_MAX_HEADING_LEVEL;
   const body = parseFrontmatter(markdown).body;
   const chunks = [];
   const trail = [];
   let buffer = [];
   let inFence = false;
+  let openPath = [];
+  const path = () => trail.filter((s) => Boolean(s));
   const flush = () => {
-    const text = buffer.join("\n").trim();
+    const text2 = buffer.join("\n").trim();
     buffer = [];
-    if (!text)
+    if (!text2)
       return;
-    const headingPath = trail.filter((s) => Boolean(s));
-    for (const part of splitLong(text, maxChars)) {
-      chunks.push({ index: chunks.length, headingPath, text: part });
+    for (const part of splitLong(text2, maxChars)) {
+      chunks.push({ index: chunks.length, headingPath: openPath, text: part });
     }
   };
   for (const line of body.split(/\r?\n/)) {
@@ -7435,10 +7453,13 @@ function chunkMarkdown(markdown, maxChars = DEFAULT_MAX_CHARS) {
       inFence = !inFence;
     const heading = !inFence && /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
     if (heading) {
-      flush();
       const level = heading[1].length;
+      if (level <= maxHeadingLevel)
+        flush();
       trail.splice(level - 1);
       trail[level - 1] = heading[2];
+      if (buffer.length === 0)
+        openPath = path();
       buffer.push(line);
       continue;
     }
@@ -7447,25 +7468,58 @@ function chunkMarkdown(markdown, maxChars = DEFAULT_MAX_CHARS) {
   flush();
   return chunks;
 }
-function splitLong(text, maxChars) {
-  if (text.length <= maxChars)
-    return [text];
+function splitLong(text2, maxChars) {
+  if (text2.length <= maxChars)
+    return [text2];
   const out = [];
   let current = "";
-  for (const para of text.split(/\n{2,}/)) {
-    if (current && current.length + para.length + 2 > maxChars) {
+  for (const { sep: sep7, piece } of pieces(text2, maxChars)) {
+    if (current && current.length + sep7.length + piece.length > maxChars) {
       out.push(current);
-      current = para;
+      current = piece;
     } else {
-      current = current ? `${current}
-
-${para}` : para;
+      current = current ? current + sep7 + piece : piece;
     }
   }
   if (current)
     out.push(current);
   return out;
 }
+var SENTENCE_BREAK = /(?<=[.!?…]["'’”»)\]]*)(\s+)/;
+function* pieces(text2, maxChars) {
+  let sep7 = "";
+  for (const para of text2.split(/\n{2,}/)) {
+    if (para.length <= maxChars) {
+      yield { sep: sep7, piece: para };
+    } else {
+      const parts = para.split(SENTENCE_BREAK);
+      for (let i = 0; i < parts.length; i += 2) {
+        yield* cut(parts[i], sep7, maxChars);
+        sep7 = parts[i + 1] ?? "";
+      }
+    }
+    sep7 = "\n\n";
+  }
+}
+function* cut(sentence, sep7, maxChars) {
+  let rest = sentence;
+  while (rest.length > maxChars) {
+    const window = rest.slice(0, maxChars + 1);
+    let at = window.lastIndexOf("\n");
+    if (at < maxChars / 2)
+      at = Math.max(at, window.lastIndexOf(" "));
+    if (at <= 0)
+      at = Math.max(maxChars, 1);
+    const piece = rest.slice(0, at).trimEnd();
+    const gap = /^\s*/.exec(rest.slice(piece.length))[0];
+    if (piece)
+      yield { sep: sep7, piece };
+    sep7 = piece ? gap : sep7 + gap;
+    rest = rest.slice(piece.length + gap.length);
+  }
+  if (rest)
+    yield { sep: sep7, piece: rest };
+}
 
 // ../adapter-claude-skills/dist/index.js
 import { readFile } from "fs/promises";
@@ -7516,10 +7570,10 @@ import { readFile as readFile2 } from "fs/promises";
 import { basename as basename2, dirname as dirname3, join as join4, relative as relative2 } from "path";
 var INSTRUCTION_FILES = /* @__PURE__ */ new Set(["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]);
 var MAX_DESCRIPTION_LENGTH = 120;
-function truncate(text) {
-  if (text.length <= MAX_DESCRIPTION_LENGTH)
-    return text;
-  return text.slice(0, MAX_DESCRIPTION_LENGTH - 1).trimEnd() + "\u2026";
+function truncate(text2) {
+  if (text2.length <= MAX_DESCRIPTION_LENGTH)
+    return text2;
+  return text2.slice(0, MAX_DESCRIPTION_LENGTH - 1).trimEnd() + "\u2026";
 }
 function deriveDescription(raw2) {
   let firstNonEmpty;
@@ -7583,8 +7637,8 @@ var LEGACY_FILE = ".cursorrules";
 var MDC_EXTENSION = ".mdc";
 var RULES_MARKER = sep2 + join5(".cursor", "rules") + sep2;
 var MAX_DESCRIPTION_LENGTH2 = 120;
-function firstLine(text) {
-  for (const line of text.split(/\r?\n/)) {
+function firstLine(text2) {
+  for (const line of text2.split(/\r?\n/)) {
     const trimmed = line.trim();
     if (!trimmed)
       continue;
@@ -7958,10 +8012,10 @@ var checkOptionalParameter = (path) => {
   if (path.charCodeAt(path.length - 1) !== 63 || !path.includes(":")) {
     return null;
   }
-  const segments3 = path.split("/");
+  const segments4 = path.split("/");
   const results = [];
   let basePath = "";
-  segments3.forEach((segment) => {
+  segments4.forEach((segment) => {
     if (segment !== "" && !/\:/.test(segment)) {
       basePath += "/" + segment;
     } else if (/\:/.test(segment)) {
@@ -8178,7 +8232,7 @@ var HonoRequest = class {
    * ```
    */
   json() {
-    return this.#cachedBody("text").then((text) => JSON.parse(text));
+    return this.#cachedBody("text").then((text2) => JSON.parse(text2));
   }
   /**
    * `.text()` can parse Request body of type `text/plain`
@@ -8744,9 +8798,9 @@ var Context = class {
    * })
    * ```
    */
-  text = (text, arg, headers) => {
-    return !this.#preparedHeaders && !this.#status && !arg && !headers && !this.finalized ? new Response(text) : this.#newResponse(
-      text,
+  text = (text2, arg, headers) => {
+    return !this.#preparedHeaders && !this.#status && !arg && !headers && !this.finalized ? new Response(text2) : this.#newResponse(
+      text2,
       arg,
       setDefaultContentType(TEXT_PLAIN, headers)
     );
@@ -10050,8 +10104,8 @@ function ollamaEmbedder(options = {}) {
     }
   };
 }
-function estimateTokens(text) {
-  return Math.ceil(text.length / 4);
+function estimateTokens(text2) {
+  return Math.ceil(text2.length / 4);
 }
 
 // ../index/dist/store.js
@@ -10074,7 +10128,10 @@ function loadSqlite() {
 }
 var DB_DIR = ".capsa";
 var DB_FILE = "index.db";
-var SCHEMA_VERSION = 5;
+var SCHEMA_VERSION = 11;
+var META_INDEXED_AT = "indexed_at";
+var META_INDEX_FAILED_AT = "index_failed_at";
+var META_INDEX_ERROR = "index_error";
 var CONTEXT_LOG_DDL = `
       -- Every context delivery. This is the measurement for the MVP gate and
       -- the seed of the organisation tier's audit log. Alone among these
@@ -10088,6 +10145,12 @@ var CONTEXT_LOG_DDL = `
         query        TEXT NOT NULL,
         delivered    TEXT NOT NULL,
         tokens_est   INTEGER NOT NULL,
+        -- The ceiling this call ran under. Without it a row says what was
+        -- spent but not what it was allowed to spend, and two deliveries are
+        -- only comparable when that number matches. NULL on rows written
+        -- before v6: they ran under a budget nobody recorded, and filling in
+        -- today's default would be a guess wearing the costume of data.
+        tokens_budget INTEGER,
         duration_ms  INTEGER NOT NULL
       );
 `;
@@ -10109,24 +10172,44 @@ var Store = class {
   }
   /** True when this index was written by an older schema and must be rebuilt. */
   needsRebuild() {
-    const row = this.db.prepare("SELECT value FROM meta WHERE key = 'schema'").get();
-    return row?.value !== String(SCHEMA_VERSION);
+    return this.getMeta("schema") !== String(SCHEMA_VERSION);
+  }
+  getMeta(key) {
+    const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value;
+  }
+  setMeta(key, value) {
+    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)").run(key, value);
+  }
+  deleteMeta(key) {
+    this.db.prepare("DELETE FROM meta WHERE key = ?").run(key);
   }
   /**
     * Drop all indexed content (not the log, not decisions) and mark the schema
-    * current. The virtual tables are dropped and recreated, not emptied:
-    * `CREATE VIRTUAL TABLE IF NOT EXISTS` would keep an old tokenizer alive
-    * through a rebuild — which once left FTS without stemming after v2.
+    * current. Every one of these tables is dropped and recreated, not emptied,
+    * because `CREATE TABLE IF NOT EXISTS` in migrate() is a no-op against a
+    * table that already exists under its old shape. For the virtual tables that
+    * once left FTS without stemming after v2; for `items` it meant a schema
+    * bump could not add a column at all — v7 added `title` and the rebuild it
+    * asked for failed with "table items has no column named title", because
+    * DELETE had emptied the v6 table and left it standing.
+    *
+    * Nothing here is a source of truth: items and chunks are derived from files
+    * on disk and from `decisions`, which is one of the two tables a reset
+    * spares.
     */
   reset() {
     this.db.exec(`
       DROP TABLE IF EXISTS chunks_fts;
       DROP TABLE IF EXISTS chunks_vec;
-      DELETE FROM chunks;
-      DELETE FROM items;
+      DROP TABLE IF EXISTS chunks;
+      DROP TABLE IF EXISTS items;
     `);
     this.migrate();
-    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES ('schema', ?)").run(String(SCHEMA_VERSION));
+    this.setMeta("schema", String(SCHEMA_VERSION));
+    this.deleteMeta(META_INDEXED_AT);
+    this.deleteMeta(META_INDEX_FAILED_AT);
+    this.deleteMeta(META_INDEX_ERROR);
   }
   migrate() {
     this.db.exec(`
@@ -10137,12 +10220,14 @@ var Store = class {
         format       TEXT NOT NULL,
         kind         TEXT NOT NULL,
         name         TEXT NOT NULL,
+        title        TEXT NOT NULL,
         path         TEXT NOT NULL UNIQUE,
         rel_path     TEXT NOT NULL,
         content_hash TEXT NOT NULL,
         status       TEXT,
         updated_at   TEXT,
         tags         TEXT,
+        metadata     TEXT,
         origin       TEXT NOT NULL DEFAULT 'local',
         indexed_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
       );
@@ -10179,27 +10264,40 @@ var Store = class {
       ${CONTEXT_LOG_DDL}
     `);
     this.migrateContextLog();
-    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES ('dimensions', ?)").run(String(this.dimensions));
+    this.setMeta("dimensions", String(this.dimensions));
   }
   /**
    * `context_log` outlives every rebuild, so it is the one table that has to
-   * be migrated in place instead of recreated. v5 replaced `chunk_ids` with
-   * `delivered`: a chunk id is a rowid the next `capsa index` reassigns, so an
-   * older row ended up naming whatever text inherited its ids — the measurement
-   * quietly decayed. Rows written before v5 keep everything that still means
-   * something (when, who asked, what for, at what cost) and carry an empty
-   * delivery, because their ids can no longer be resolved honestly.
+   * be migrated in place instead of recreated — twice now.
+   *
+   * v5 replaced `chunk_ids` with `delivered`: a chunk id is a rowid the next
+   * `capsa index` reassigns, so an older row ended up naming whatever text
+   * inherited its ids — the measurement quietly decayed. Rows written before
+   * v5 keep everything that still means something (when, who asked, what for,
+   * at what cost) and carry an empty delivery, because their ids can no longer
+   * be resolved honestly.
+   *
+   * v6 added `tokens_budget`. A delivery of 1727 tokens against one of 758
+   * reads like a saving until you learn the first ran on a larger ceiling;
+   * that comparison was attempted on this repo's own log and could not be
+   * settled, because the number was never written down. Old rows get NULL
+   * rather than a backfilled default — an unknown budget is a fact about the
+   * measurement, and inventing one would hide exactly the gap this closes.
+   *
+   * Keyed on the newest column, so a v4 database reaches v6 in one pass.
    */
   migrateContextLog() {
     const columns = this.db.prepare("PRAGMA table_info(context_log)").all();
-    if (columns.some((c) => c.name === "delivered"))
+    const names = new Set(columns.map((c) => c.name));
+    if (names.has("tokens_budget"))
       return;
+    const delivered = names.has("delivered") ? "delivered" : "'[]'";
     this.db.exec(`
-      ALTER TABLE context_log RENAME TO context_log_v4;
+      ALTER TABLE context_log RENAME TO context_log_old;
       ${CONTEXT_LOG_DDL}
-      INSERT INTO context_log (id, created_at, source, query, delivered, tokens_est, duration_ms)
-        SELECT id, created_at, source, query, '[]', tokens_est, duration_ms FROM context_log_v4;
-      DROP TABLE context_log_v4;
+      INSERT INTO context_log (id, created_at, source, query, delivered, tokens_est, tokens_budget, duration_ms)
+        SELECT id, created_at, source, query, ${delivered}, tokens_est, NULL, duration_ms FROM context_log_old;
+      DROP TABLE context_log_old;
     `);
   }
   getItem(path) {
@@ -10217,20 +10315,22 @@ var Store = class {
     this.db.prepare("DELETE FROM items WHERE id = ?").run(id);
   }
   upsertItem(row) {
-    this.db.prepare(`INSERT INTO items (id, format, kind, name, path, rel_path, content_hash, status, updated_at, tags)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    this.db.prepare(`INSERT INTO items (id, format, kind, name, title, path, rel_path, content_hash, status, updated_at, tags, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(id) DO UPDATE SET
            format = excluded.format, kind = excluded.kind, name = excluded.name,
+           title = excluded.title,
            rel_path = excluded.rel_path, content_hash = excluded.content_hash,
            status = excluded.status, updated_at = excluded.updated_at, tags = excluded.tags,
-           indexed_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`).run(row.id, row.format, row.kind, row.name, row.path, row.rel_path, row.content_hash, row.status, row.updated_at, row.tags);
+           metadata = excluded.metadata,
+           indexed_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`).run(row.id, row.format, row.kind, row.name, row.title, row.path, row.rel_path, row.content_hash, row.status, row.updated_at, row.tags, row.metadata);
   }
   /**
    * `text` is what the user sees; `searchText` (chunk + provenance header)
    * is what FTS and the embedder see. Falls back to `text` when omitted.
    */
-  insertChunk(itemId, idx, headingPath, text, embedding, searchText = text) {
-    const res = this.db.prepare("INSERT INTO chunks (item_id, idx, heading_path, text) VALUES (?, ?, ?, ?)").run(itemId, idx, JSON.stringify(headingPath), text);
+  insertChunk(itemId, idx, headingPath, text2, embedding, searchText = text2) {
+    const res = this.db.prepare("INSERT INTO chunks (item_id, idx, heading_path, text) VALUES (?, ?, ?, ?)").run(itemId, idx, JSON.stringify(headingPath), text2);
     const id = Number(res.lastInsertRowid);
     this.db.prepare("INSERT INTO chunks_fts (rowid, text) VALUES (?, ?)").run(id, searchText);
     this.db.prepare("INSERT INTO chunks_vec (chunk_id, embedding) VALUES (?, ?)").run(BigInt(id), new Uint8Array(embedding.buffer, embedding.byteOffset, embedding.byteLength));
@@ -10254,7 +10354,7 @@ var Store = class {
       return [];
     const placeholders = ids.map(() => "?").join(",");
     const rows = this.db.prepare(`SELECT c.id, c.item_id, c.idx, c.heading_path, c.text,
-                i.id AS i_id, i.format, i.kind, i.name, i.path, i.rel_path, i.content_hash, i.status, i.updated_at, i.tags
+                i.id AS i_id, i.format, i.kind, i.name, i.title, i.path, i.rel_path, i.content_hash, i.status, i.updated_at, i.tags, i.metadata
          FROM chunks c JOIN items i ON i.id = c.item_id WHERE c.id IN (${placeholders})`).all(...ids);
     return rows.map((r) => ({
       id: r["id"],
@@ -10267,12 +10367,14 @@ var Store = class {
         format: r["format"],
         kind: r["kind"],
         name: r["name"],
+        title: r["title"],
         path: r["path"],
         rel_path: r["rel_path"],
         content_hash: r["content_hash"],
         status: r["status"],
         updated_at: r["updated_at"],
-        tags: r["tags"]
+        tags: r["tags"],
+        metadata: r["metadata"]
       }
     }));
   }
@@ -10284,7 +10386,7 @@ var Store = class {
     return this.db.prepare("SELECT * FROM items ORDER BY kind, rel_path").all();
   }
   logContext(entry) {
-    this.db.prepare("INSERT INTO context_log (source, query, delivered, tokens_est, duration_ms) VALUES (?, ?, ?, ?, ?)").run(entry.source, entry.query, JSON.stringify(entry.delivered), entry.tokensEst, entry.durationMs);
+    this.db.prepare("INSERT INTO context_log (source, query, delivered, tokens_est, tokens_budget, duration_ms) VALUES (?, ?, ?, ?, ?, ?)").run(entry.source, entry.query, JSON.stringify(entry.delivered), entry.tokensEst, entry.tokensBudget, entry.durationMs);
   }
   /**
    * Returns the stored row, not just its id: `created_at` is SQL's to write,
@@ -10308,12 +10410,116 @@ var Store = class {
 
 // ../index/dist/indexer.js
 import { createHash as createHash2 } from "crypto";
-import { relative as relative5 } from "path";
+import { relative as relative6 } from "path";
+
+// ../adapter-documents/dist/index.js
+import { readFile as readFile5 } from "fs/promises";
+import { basename as basename4, dirname as dirname7, relative as relative3, sep as sep4 } from "path";
+var BOOK_DIR = "books";
+var OUTLINE_FILE = "index.md";
+var CHAPTER_HEADING_LEVEL = 3;
+var CHAPTER_MAX_CHARS = 1e3;
+function segments(relPath) {
+  return relPath.split(/[\\/]/).filter(Boolean);
+}
+function documentsAdapter() {
+  return {
+    id: "documents",
+    displayName: "Document",
+    matches(entry) {
+      if (!entry.isFile || !entry.name.toLowerCase().endsWith(".md"))
+        return false;
+      return segments(entry.relPath).slice(0, -1).some((p) => p.toLowerCase() === BOOK_DIR);
+    },
+    async parse(entry, env) {
+      let raw2;
+      try {
+        raw2 = await readFile5(entry.absPath, "utf8");
+      } catch {
+        return { items: [] };
+      }
+      const fm = parseFrontmatter(raw2);
+      const book = fm.data["book"];
+      if (!book) {
+        return {
+          items: [],
+          issues: [
+            {
+              path: entry.absPath,
+              message: `no \`book:\` in frontmatter \u2014 a markdown file under ${BOOK_DIR}/ is a chapter of a document or it is nothing`
+            }
+          ]
+        };
+      }
+      const projectRoot = findProjectRoot(dirname7(entry.absPath), env.homeDir);
+      const relPathInProject = relative3(projectRoot, entry.absPath);
+      const outline = entry.name.toLowerCase() === OUTLINE_FILE;
+      const title = fm.data["title"] || firstHeading(fm.body) || basename4(entry.name, ".md");
+      const chapter = fm.data["chapter"];
+      const metadata = {
+        relPathInProject,
+        book,
+        title,
+        ...fm.data["author"] ? { author: fm.data["author"] } : {},
+        ...chapter ? { chapter: number(chapter) } : {},
+        ...pages("printed_pages", fm.data["printed_pages"]),
+        ...pages("pdf_pages", fm.data["pdf_pages"])
+      };
+      return {
+        items: [
+          {
+            id: stableId(entry.absPath),
+            format: "documents",
+            formatLabel: outline ? "Outline" : "Document",
+            name: `${basename4(projectRoot)}${sep4}${relPathInProject}`,
+            // What the item calls itself, and what a pinned item's
+            // neighbourhood is searched with: a chapter title alone
+            // ("Conclusion") belongs to nine books at once.
+            description: outline ? `${book} \u2014 Contents` : `${book} \u2014 ${chapterLabel(chapter, title)}`,
+            path: entry.absPath,
+            scope: "project",
+            projectRoot,
+            content: raw2,
+            metadata,
+            knowledge: { kind: outline ? "outline" : "document" },
+            // An outline is delivered whole or not at all — a table of
+            // contents retrieved three lines at a time is noise. Empty, so
+            // the indexer stores it and embeds nothing of it.
+            chunks: outline ? [] : chapterChunks(raw2)
+          }
+        ]
+      };
+    }
+  };
+}
+function chapterLabel(chapter, title) {
+  return chapter === void 0 || chapter === "" ? title : `Ch. ${chapter} ${title}`;
+}
+function chapterChunks(raw2) {
+  return chunkMarkdown(raw2, { maxHeadingLevel: CHAPTER_HEADING_LEVEL, maxChars: CHAPTER_MAX_CHARS });
+}
+function pages(key, value) {
+  if (!value)
+    return {};
+  const parts = value.replace(/^\[|\]$/g, "").split(",").map((p) => p.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+  return parts.length ? { [key]: parts.map(number) } : {};
+}
+function number(value) {
+  return /^\d+$/.test(value) ? Number(value) : value;
+}
+function firstHeading(body) {
+  for (const line of body.split(/\r?\n/)) {
+    const m = /^#{1,6}\s+(.*\S)\s*$/.exec(line.trim());
+    if (m)
+      return m[1];
+  }
+  return void 0;
+}
 
 // ../adapter-git-log/dist/index.js
 import { execFile } from "child_process";
 import { existsSync as existsSync2 } from "fs";
-import { basename as basename4, join as join7 } from "path";
+import { basename as basename5, join as join7 } from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var DEFAULTS = {
@@ -10416,7 +10622,7 @@ function toItem(root, c, opts) {
       author: c.author,
       subject,
       files: c.files,
-      repo: basename4(root)
+      repo: basename5(root)
     },
     knowledge: {
       kind: "commit",
@@ -10461,18 +10667,27 @@ function conventionalTags(subject) {
   const tags = [m[1], ...m[2] ? [m[2]] : []];
   return tags;
 }
-function firstLine2(text) {
-  return (text ?? "").split("\n").find((l) => l.trim()) ?? "";
+function firstLine2(text2) {
+  return (text2 ?? "").split("\n").find((l) => l.trim()) ?? "";
 }
 
 // ../adapter-runbooks/dist/index.js
-import { readFile as readFile5, stat as stat3 } from "fs/promises";
-import { basename as basename5, dirname as dirname7, relative as relative3, sep as sep4 } from "path";
+import { readFile as readFile6, stat as stat3 } from "fs/promises";
+import { basename as basename6, dirname as dirname8, relative as relative4, sep as sep5 } from "path";
 var DOC_DIRS = /* @__PURE__ */ new Set(["docs", "doc", "runbooks", "runbook", "wiki", "adr", "decisions"]);
-var EXCLUDED_DIRS = /* @__PURE__ */ new Set(["tickets", "issues", "todo", "backlog", "plans", "plan", "roadmap", "milestones", "milestone", "node_modules"]);
-function segments(relPath) {
+var CLAIMED_ELSEWHERE = /* @__PURE__ */ new Set(["skill.md"]);
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set(["books", "tickets", "issues", "todo", "backlog", "plans", "plan", "roadmap", "milestones", "milestone", "node_modules"]);
+function segments2(relPath) {
   return relPath.split(/[\\/]/).filter(Boolean);
 }
+function kindOf(relPathInProject) {
+  const parts = segments2(relPathInProject).map((p) => p.toLowerCase());
+  if (parts.some((p) => p === "adr" || p === "decisions"))
+    return "decision";
+  if (parts.some((p) => p === "runbooks" || p === "runbook"))
+    return "runbook";
+  return "doc";
+}
 function runbooksAdapter() {
   return {
     id: "runbooks",
@@ -10480,7 +10695,9 @@ function runbooksAdapter() {
     matches(entry) {
       if (!entry.isFile || !entry.name.toLowerCase().endsWith(".md"))
         return false;
-      const parts = segments(entry.relPath).slice(0, -1);
+      if (CLAIMED_ELSEWHERE.has(entry.name.toLowerCase()))
+        return false;
+      const parts = segments2(entry.relPath).slice(0, -1);
       if (!parts.some((p) => DOC_DIRS.has(p.toLowerCase())))
         return false;
       return !parts.some((p) => EXCLUDED_DIRS.has(p.toLowerCase()));
@@ -10489,24 +10706,23 @@ function runbooksAdapter() {
       let raw2;
       let mtime;
       try {
-        raw2 = await readFile5(entry.absPath, "utf8");
+        raw2 = await readFile6(entry.absPath, "utf8");
         mtime = (await stat3(entry.absPath)).mtime;
       } catch {
         return [];
       }
-      const projectRoot = findProjectRoot(dirname7(entry.absPath), env.homeDir);
-      const relPathInProject = relative3(projectRoot, entry.absPath);
+      const projectRoot = findProjectRoot(dirname8(entry.absPath), env.homeDir);
+      const relPathInProject = relative4(projectRoot, entry.absPath);
       const fm = parseFrontmatter(raw2);
       const data = fm.data;
-      const title = data["title"] || firstHeading(raw2) || basename5(entry.name, ".md");
-      const kindFromPath = segments(relPathInProject).some((p) => ["adr", "decisions"].includes(p.toLowerCase())) ? "decision" : "runbook";
+      const title = data["title"] || firstHeading2(raw2) || basename6(entry.name, ".md");
       const tags = parseTags(data["tags"]);
       return [
         {
           id: stableId(entry.absPath),
           format: "runbooks",
           formatLabel: "Runbook",
-          name: `${basename5(projectRoot)}${sep4}${relPathInProject}`,
+          name: `${basename6(projectRoot)}${sep5}${relPathInProject}`,
           description: title,
           path: entry.absPath,
           scope: "project",
@@ -10514,7 +10730,7 @@ function runbooksAdapter() {
           content: raw2,
           metadata: { relPathInProject, title },
           knowledge: {
-            kind: kindFromPath,
+            kind: kindOf(relPathInProject),
             updatedAt: mtime?.toISOString(),
             tags
           }
@@ -10529,7 +10745,7 @@ function parseTags(value) {
   const tags = value.replace(/^\[|\]$/g, "").split(",").map((t) => t.trim()).filter(Boolean);
   return tags.length ? tags : void 0;
 }
-function firstHeading(raw2) {
+function firstHeading2(raw2) {
   for (const line of raw2.split(/\r?\n/)) {
     const m = /^#{1,6}\s+(.*\S)\s*$/.exec(line.trim());
     if (m)
@@ -10539,12 +10755,12 @@ function firstHeading(raw2) {
 }
 
 // ../adapter-tickets/dist/index.js
-import { readFile as readFile6, stat as stat4 } from "fs/promises";
-import { basename as basename6, dirname as dirname8, relative as relative4, sep as sep5 } from "path";
+import { readFile as readFile7, stat as stat4 } from "fs/promises";
+import { basename as basename7, dirname as dirname9, relative as relative5, sep as sep6 } from "path";
 var TICKET_DIRS = /* @__PURE__ */ new Set(["tickets", "issues", "todo", "backlog"]);
 var PLAN_DIRS = /* @__PURE__ */ new Set(["plans", "plan", "roadmap", "milestones", "milestone"]);
 var CHECKBOX = /^\s*[-*+]\s+\[( |x|X)\]\s+/gm;
-function segments2(relPath) {
+function segments3(relPath) {
   return relPath.split(/[\\/]/).filter(Boolean);
 }
 function deriveStatus(raw2) {
@@ -10582,33 +10798,33 @@ function ticketsAdapter() {
     matches(entry) {
       if (!entry.isFile || !entry.name.toLowerCase().endsWith(".md"))
         return false;
-      const parts = segments2(entry.relPath).slice(0, -1).map((p) => p.toLowerCase());
+      const parts = segments3(entry.relPath).slice(0, -1).map((p) => p.toLowerCase());
       return parts.some((p) => TICKET_DIRS.has(p) || PLAN_DIRS.has(p));
     },
     async parse(entry, env) {
       let raw2;
       let mtime;
       try {
-        raw2 = await readFile6(entry.absPath, "utf8");
+        raw2 = await readFile7(entry.absPath, "utf8");
         mtime = (await stat4(entry.absPath)).mtime;
       } catch {
         return [];
       }
-      const projectRoot = findProjectRoot(dirname8(entry.absPath), env.homeDir);
-      const relPathInProject = relative4(projectRoot, entry.absPath);
-      const isPlan = segments2(relPathInProject).slice(0, -1).some((p) => PLAN_DIRS.has(p.toLowerCase()));
+      const projectRoot = findProjectRoot(dirname9(entry.absPath), env.homeDir);
+      const relPathInProject = relative5(projectRoot, entry.absPath);
+      const isPlan = segments3(relPathInProject).slice(0, -1).some((p) => PLAN_DIRS.has(p.toLowerCase()));
       const fm = parseFrontmatter(raw2);
       const data = fm.data;
       const derived2 = deriveStatus(raw2);
       const status = normaliseStatus(data["status"]) ?? derived2.status;
-      const title = data["title"] || firstHeading2(raw2) || basename6(entry.name, ".md");
+      const title = data["title"] || firstHeading3(raw2) || basename7(entry.name, ".md");
       const tags = parseTags2(data["tags"]);
       return [
         {
           id: stableId(entry.absPath),
           format: "tickets",
           formatLabel: isPlan ? "Plan" : "Ticket",
-          name: `${basename6(projectRoot)}${sep5}${relPathInProject}`,
+          name: `${basename7(projectRoot)}${sep6}${relPathInProject}`,
           description: title,
           path: entry.absPath,
           scope: "project",
@@ -10636,7 +10852,7 @@ function parseTags2(value) {
   const tags = value.replace(/^\[|\]$/g, "").split(",").map((t) => t.trim()).filter(Boolean);
   return tags.length ? tags : void 0;
 }
-function firstHeading2(raw2) {
+function firstHeading3(raw2) {
   for (const line of raw2.split(/\r?\n/)) {
     const m = /^#{1,6}\s+(.*\S)\s*$/.exec(line.trim());
     if (m)
@@ -10713,6 +10929,7 @@ function knowledgeAdapters() {
     cursorRulesAdapter(),
     runbooksAdapter(),
     ticketsAdapter(),
+    documentsAdapter(),
     gitLogAdapter()
   ];
 }
@@ -10720,76 +10937,116 @@ function openStore(projectRoot, embedder) {
   return new Store(dbPath(projectRoot), embedder.dimensions);
 }
 async function indexProject(projectRoot, embedder, onProgress) {
-  const started = Date.now();
   const store = openStore(projectRoot, embedder);
   try {
-    if (store.needsRebuild()) {
-      onProgress?.({ phase: "rebuild" });
-      store.reset();
-    }
-    onProgress?.({ phase: "scan" });
-    const result = await scan(knowledgeAdapters(), { roots: [projectRoot] });
-    const items = result.items.filter((i) => i.scope === "project" && isInside(projectRoot, i.path));
-    let indexed = 0;
-    let skipped = 0;
-    const seen = /* @__PURE__ */ new Set();
-    for (const item of items) {
-      seen.add(item.path);
-      const hash2 = sha1(item.content);
-      const existing = store.getItem(item.path);
-      if (existing && existing.content_hash === hash2) {
-        skipped++;
-        continue;
-      }
-      if (existing)
-        store.deleteItem(existing.id);
-      await indexItem(store, embedder, item, projectRoot, hash2);
-      indexed++;
-      onProgress?.({ phase: "embed", scanned: items.length, indexed, skipped });
-    }
-    const decisions = await indexDecisions(store, embedder, projectRoot);
-    for (const path of decisions.paths)
-      seen.add(path);
-    indexed += decisions.indexed;
-    skipped += decisions.skipped;
-    let removed = 0;
-    for (const row of store.listItems()) {
-      if (!seen.has(row.path)) {
-        store.deleteItem(row.id);
-        removed++;
-      }
-    }
-    const out = {
-      scanned: items.length + decisions.paths.length,
-      indexed,
-      skipped,
-      removed,
-      issues: result.issues.map((i) => ({ path: i.path, message: i.message })),
-      durationMs: Date.now() - started
-    };
-    onProgress?.({ phase: "done", ...out, issues: out.issues.length });
-    return out;
+    return await indexInto(store, projectRoot, embedder, { onProgress });
   } finally {
     store.close();
   }
 }
-async function indexDecisions(store, embedder, projectRoot) {
-  const out = { paths: [], indexed: 0, skipped: 0 };
-  for (const row of store.listDecisions()) {
-    const item = decisionItem(projectRoot, row);
-    out.paths.push(item.path);
+var TooManyChangesError = class extends Error {
+  changed;
+  limit;
+  constructor(changed, limit) {
+    super(`${changed} items changed since the last index \u2014 run \`capsa index\``);
+    this.changed = changed;
+    this.limit = limit;
+    this.name = "TooManyChangesError";
+  }
+};
+async function indexInto(store, projectRoot, embedder, options = {}) {
+  const { onProgress, maxChanges } = options;
+  const started = Date.now();
+  if (store.needsRebuild()) {
+    onProgress?.({ phase: "rebuild" });
+    store.reset();
+  }
+  onProgress?.({ phase: "scan" });
+  const result = await scan(knowledgeAdapters(), { roots: [projectRoot] });
+  const items = result.items.filter((i) => i.scope === "project" && isInside(projectRoot, i.path));
+  const all = [...items, ...decisionItems(store, projectRoot)];
+  const { changed, skipped } = changedItems(store, all);
+  if (maxChanges !== void 0 && changed.length > maxChanges) {
+    throw new TooManyChangesError(changed.length, maxChanges);
+  }
+  let indexed = 0;
+  for (const c of changed) {
+    await indexItem(store, embedder, c.item, projectRoot, c.hash, c.previousId);
+    indexed++;
+    onProgress?.({ phase: "embed", scanned: all.length, indexed, skipped });
+  }
+  const seen = new Set(all.map((i) => i.path));
+  let removed = 0;
+  for (const row of store.listItems()) {
+    if (!seen.has(row.path)) {
+      store.deleteItem(row.id);
+      removed++;
+    }
+  }
+  const out = {
+    scanned: all.length,
+    indexed,
+    skipped,
+    removed,
+    issues: result.issues.map((i) => ({ path: i.path, message: i.message })),
+    durationMs: Date.now() - started
+  };
+  store.setMeta(META_INDEXED_AT, new Date(started).toISOString());
+  store.deleteMeta(META_INDEX_FAILED_AT);
+  store.deleteMeta(META_INDEX_ERROR);
+  onProgress?.({ phase: "done", ...out, issues: out.issues.length });
+  return out;
+}
+var DEFAULT_MAX_INDEX_AGE_MS = 6e4;
+var DEFAULT_MAX_REFRESH_CHANGES = 20;
+async function freshenIndex(store, projectRoot, embedder, options = {}) {
+  const maxAge = options.maxAgeMs ?? DEFAULT_MAX_INDEX_AGE_MS;
+  const maxChanges = options.maxChanges ?? DEFAULT_MAX_REFRESH_CHANGES;
+  const now = Date.now();
+  if (ageMs(store.getMeta(META_INDEXED_AT), now) <= maxAge)
+    return { refreshed: false, stale: false };
+  if (store.needsRebuild()) {
+    return {
+      refreshed: false,
+      stale: true,
+      reason: "this index was never built or its schema changed \u2014 run `capsa index`"
+    };
+  }
+  if (ageMs(store.getMeta(META_INDEX_FAILED_AT), now) <= maxAge) {
+    return { refreshed: false, stale: true, reason: store.getMeta(META_INDEX_ERROR) ?? "the last index run failed" };
+  }
+  try {
+    const res = await indexInto(store, projectRoot, embedder, { maxChanges });
+    return { refreshed: true, stale: false, indexed: res.indexed, removed: res.removed };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    store.setMeta(META_INDEX_FAILED_AT, (/* @__PURE__ */ new Date()).toISOString());
+    store.setMeta(META_INDEX_ERROR, reason);
+    return { refreshed: false, stale: true, reason };
+  }
+}
+function ageMs(iso, now) {
+  if (!iso)
+    return Number.POSITIVE_INFINITY;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? Number.POSITIVE_INFINITY : now - t;
+}
+function changedItems(store, items) {
+  const changed = [];
+  let skipped = 0;
+  for (const item of items) {
     const hash2 = sha1(item.content);
     const existing = store.getItem(item.path);
     if (existing && existing.content_hash === hash2) {
-      out.skipped++;
+      skipped++;
       continue;
     }
-    if (existing)
-      store.deleteItem(existing.id);
-    await indexItem(store, embedder, item, projectRoot, hash2);
-    out.indexed++;
+    changed.push({ item, hash: hash2, previousId: existing?.id });
   }
-  return out;
+  return { changed, skipped };
+}
+function decisionItems(store, projectRoot) {
+  return store.listDecisions().map((row) => decisionItem(projectRoot, row));
 }
 async function recordDecision(store, embedder, projectRoot, input2) {
   const row = store.recordDecision(input2.title, input2.body, input2.related);
@@ -10801,37 +11058,44 @@ async function recordDecision(store, embedder, projectRoot, input2) {
     return { id: row.id, indexed: false, reason: err.message };
   }
 }
-async function indexItem(store, embedder, item, projectRoot, hash2) {
-  const chunks = chunkMarkdown(item.content);
+async function indexItem(store, embedder, item, projectRoot, hash2, previousId) {
+  const chunks = item.chunks ?? chunkMarkdown(item.content);
   const searchTexts = chunks.map((c) => withContext(item, c.headingPath, c.text));
   const vectors = searchTexts.length ? await embedder.embed(searchTexts) : [];
+  if (previousId)
+    store.deleteItem(previousId);
   const k = item.knowledge;
   store.upsertItem({
     id: item.id,
     format: item.format,
     kind: k?.kind ?? "instruction",
     name: item.name,
+    // The same expression the provenance header uses (see withContext): the
+    // title an item claims for itself, falling back to its name when the
+    // format has none to give.
+    title: item.description ?? item.name,
     path: item.path,
-    rel_path: relative5(projectRoot, item.path),
+    rel_path: relative6(projectRoot, item.path),
     content_hash: hash2,
     status: k?.status ?? null,
     updated_at: k?.updatedAt ?? null,
-    tags: k?.tags ? JSON.stringify(k.tags) : null
+    tags: k?.tags ? JSON.stringify(k.tags) : null,
+    metadata: item.metadata ? JSON.stringify(item.metadata) : null
   });
   chunks.forEach((c, i) => store.insertChunk(item.id, c.index, c.headingPath, c.text, vectors[i], searchTexts[i]));
 }
-function withContext(item, headingPath, text) {
+function withContext(item, headingPath, text2) {
   const kind = item.knowledge?.kind ?? "instruction";
   const head = [kind, item.description ?? item.name, ...headingPath].filter(Boolean).join(" \u203A ");
   return `${head}
 
-${text}`;
+${text2}`;
 }
 function sha1(s) {
   return createHash2("sha1").update(s).digest("hex");
 }
 function isInside(root, path) {
-  const rel = relative5(root, path);
+  const rel = relative6(root, path);
   return !!rel && !rel.startsWith("..") && !rel.includes(":");
 }
 
@@ -10852,6 +11116,13 @@ var DEFAULT_WEIGHTS = {
     plan: 1.05,
     ticket: 1,
     runbook: 1,
+    // A book is reference, not project knowledge: neutral until the context
+    // log says otherwise. It carries no recency and no status either — see
+    // the documents adapter on what it refuses to claim.
+    document: 1,
+    // Never ranked: an outline has no chunks to rank. The map is total, so
+    // it needs a number; 1.0 is the one that says nothing.
+    outline: 1,
     doc: 0.95,
     wiki: 0.95,
     commit: 0.85
@@ -10884,15 +11155,19 @@ function rrf(lists, k = DEFAULT_WEIGHTS.rrfK) {
 
 // ../index/dist/pin.js
 var LEADING_ID = /^([A-Za-z]{1,8}-?\d{1,5}(?:-\d{1,5})?|\d{2,6})(?=[-_.\s]|$)/;
+var POSITIONAL_KINDS = /* @__PURE__ */ new Set(["document", "outline"]);
 function leadingId(relPath) {
   const base = relPath.split(/[\\/]/).pop() ?? "";
   return LEADING_ID.exec(base)?.[1];
 }
+function pinnableId(item) {
+  return POSITIONAL_KINDS.has(item.kind) ? void 0 : leadingId(item.rel_path);
+}
 function pinnedItems(query, items) {
   const q = query.toLowerCase();
   const idCount = /* @__PURE__ */ new Map();
   for (const item of items) {
-    const id = leadingId(item.rel_path)?.toLowerCase();
+    const id = pinnableId(item)?.toLowerCase();
     if (id)
       idCount.set(id, (idCount.get(id) ?? 0) + 1);
   }
@@ -10903,7 +11178,7 @@ function pinnedItems(query, items) {
       out.push(item);
       continue;
     }
-    const id = leadingId(item.rel_path);
+    const id = pinnableId(item);
     if (!id || (idCount.get(id.toLowerCase()) ?? 0) > 1)
       continue;
     const re = new RegExp(`(^|[^\\w-])${escape2(id)}(?=$|[^\\w-])`, "i");
@@ -10923,6 +11198,7 @@ async function retrieve(store, embedder, query, options = {}) {
   const candidates = options.candidates ?? 30;
   const weights = options.weights ?? DEFAULT_WEIGHTS;
   const minRelative = options.minRelativeScore ?? 0.5;
+  const perItemCap = { ...DEFAULT_PER_ITEM_CAP, ...options.perItemCap };
   const perItem = /* @__PURE__ */ new Map();
   const chunks = [];
   const debug = [];
@@ -10932,11 +11208,13 @@ async function retrieve(store, embedder, query, options = {}) {
     for (const c of store.chunksForItem(item.id)) {
       const t = estimateTokens(c.text);
       const fits = tokens + t <= maxTokens || chunks.length === 0;
+      const metadata = parseMetadata(item.metadata);
       if (options.debug) {
         debug.push({
           chunkId: c.id,
           relPath: item.rel_path,
           headingPath: JSON.parse(c.heading_path),
+          metadata,
           kind: item.kind,
           status: item.status,
           vecRank: null,
@@ -10961,16 +11239,25 @@ async function retrieve(store, embedder, query, options = {}) {
         relPath: item.rel_path,
         headingPath: JSON.parse(c.heading_path),
         text: c.text,
-        tokens: t
+        tokens: t,
+        ...metadata ? { metadata } : {}
       });
     }
   }
   const pinnedIds = new Set(pinned.map((i) => i.id));
   const neighbourCutoff = pinned.length ? Math.max(minRelative, 0.75) : minRelative;
   const neighbourBudget = pinned.length ? Math.min(maxTokens, tokens + Math.floor(maxTokens / 3)) : maxTokens;
-  const [qv] = await embedder.embed([query]);
-  const vec = qv ? store.vectorSearch(qv, candidates).map((r) => r.chunkId) : [];
-  const fts = store.textSearch(query, candidates).map((r) => r.chunkId);
+  const searchText = neighbourQuery(query, pinned);
+  let vec = [];
+  let degraded;
+  try {
+    const [qv] = await embedder.embed([searchText]);
+    if (qv)
+      vec = store.vectorSearch(qv, candidates).map((r) => r.chunkId);
+  } catch (err) {
+    degraded = err instanceof Error ? err.message : String(err);
+  }
+  const fts = store.textSearch(searchText, candidates).map((r) => r.chunkId);
   const fused = rrf([vec, fts], weights.rrfK);
   const rows = store.chunksWithItems([...fused.keys()]).filter((r) => !pinnedIds.has(r.item_id));
   const now = Date.now();
@@ -10979,24 +11266,45 @@ async function retrieve(store, embedder, query, options = {}) {
     const factor = signalFactor({ kind: r.item.kind, status: r.item.status, updatedAt: r.item.updated_at }, weights, now);
     return { row: r, fusedScore, factor, score: fusedScore * factor };
   }).sort((a, b) => b.score - a.score);
-  const best = scored[0]?.score ?? 0;
-  let cut = tokens >= maxTokens;
-  let kept = 0;
-  for (const { row, fusedScore, factor, score } of scored) {
-    let why = "kept";
-    if (cut || kept > 0 && score < best * neighbourCutoff) {
-      cut = true;
-      why = "cutoff";
-    } else if ((perItem.get(row.item_id) ?? 0) >= 2) {
-      why = "per-item cap";
-    } else if (tokens + estimateTokens(row.text) > neighbourBudget && chunks.length > 0) {
-      why = "budget";
+  const neighbourhood = [];
+  for (const c of scored) {
+    if (options.excludeRootInstructions && isRootInstruction(c.row.item.rel_path)) {
+      if (options.debug) {
+        debug.push({
+          chunkId: c.row.id,
+          relPath: c.row.item.rel_path,
+          headingPath: JSON.parse(c.row.heading_path),
+          metadata: parseMetadata(c.row.item.metadata),
+          kind: c.row.item.kind,
+          status: c.row.item.status,
+          vecRank: rankIn(vec, c.row.id),
+          ftsRank: rankIn(fts, c.row.id),
+          fused: c.fusedScore,
+          factor: c.factor,
+          score: c.score,
+          kept: false,
+          why: "in prompt"
+        });
+      }
+      continue;
     }
+    neighbourhood.push(c);
+  }
+  const verdicts = keep(neighbourhood.map((c) => ({
+    itemId: c.row.item_id,
+    kind: c.row.item.kind,
+    score: c.score,
+    tokens: estimateTokens(c.row.text)
+  })), { budget: neighbourBudget, minRelativeScore: neighbourCutoff, perItemCap }, { tokens, chunks: chunks.length, perItem });
+  for (const [i, { row, fusedScore, factor, score }] of neighbourhood.entries()) {
+    const why = verdicts[i];
+    const metadata = parseMetadata(row.item.metadata);
     if (options.debug) {
       debug.push({
         chunkId: row.id,
         relPath: row.item.rel_path,
         headingPath: JSON.parse(row.heading_path),
+        metadata,
         kind: row.item.kind,
         status: row.item.status,
         vecRank: rankIn(vec, row.id),
@@ -11011,9 +11319,7 @@ async function retrieve(store, embedder, query, options = {}) {
     if (why !== "kept")
       continue;
     const t = estimateTokens(row.text);
-    perItem.set(row.item_id, (perItem.get(row.item_id) ?? 0) + 1);
     tokens += t;
-    kept++;
     chunks.push({
       chunkId: row.id,
       score,
@@ -11023,31 +11329,123 @@ async function retrieve(store, embedder, query, options = {}) {
       relPath: row.item.rel_path,
       headingPath: JSON.parse(row.heading_path),
       text: row.text,
-      tokens: t
+      tokens: t,
+      ...metadata ? { metadata } : {}
     });
-    if (tokens >= neighbourBudget)
-      cut = true;
   }
   const durationMs = Date.now() - started;
   store.logContext({
-    source: options.source ?? "unknown",
+    // A keyword-only delivery is logged under its own source. The week-4
+    // gate is read from this table, and a run with half the retriever
+    // missing is not a sample of how the ranking performs — it should show
+    // up as its own bucket in a `group by source`, not quietly average in.
+    source: (options.source ?? "unknown") + (degraded ? ":degraded" : ""),
     query,
     delivered: chunks.map((c) => ({ rel_path: c.relPath, heading_path: c.headingPath, tokens: c.tokens })),
     tokensEst: tokens,
+    // The ceiling, not the spend: two rows are only comparable when this
+    // matches, and retrieval stops at the relevance cliff well before it.
+    tokensBudget: maxTokens,
     durationMs
   });
-  return { query, chunks, tokensEst: tokens, durationMs, ...options.debug ? { debug } : {} };
+  return {
+    query,
+    searchText,
+    chunks,
+    tokensEst: tokens,
+    durationMs,
+    ...degraded ? { degraded } : {},
+    ...options.debug ? { debug } : {}
+  };
+}
+var PER_ITEM_CAP = 2;
+var DOCUMENT_PER_ITEM_CAP = 6;
+var DEFAULT_PER_ITEM_CAP = {
+  instruction: PER_ITEM_CAP,
+  doc: PER_ITEM_CAP,
+  runbook: PER_ITEM_CAP,
+  ticket: PER_ITEM_CAP,
+  plan: PER_ITEM_CAP,
+  decision: PER_ITEM_CAP,
+  wiki: PER_ITEM_CAP,
+  commit: PER_ITEM_CAP,
+  document: DOCUMENT_PER_ITEM_CAP,
+  // An outline has no chunks; the number is here because the map is total.
+  outline: PER_ITEM_CAP
+};
+function keep(candidates, rules, start = { tokens: 0, chunks: 0, perItem: /* @__PURE__ */ new Map() }) {
+  const best = candidates[0]?.score ?? 0;
+  const perItem = new Map(start.perItem);
+  let tokens = start.tokens;
+  let chunks = start.chunks;
+  let kept = 0;
+  let end = tokens >= rules.budget ? "budget" : void 0;
+  return candidates.map((c) => {
+    if (end)
+      return end;
+    if (kept > 0 && c.score < best * rules.minRelativeScore)
+      return end = "cutoff";
+    const taken = perItem.get(c.itemId) ?? 0;
+    if (taken >= (rules.perItemCap[c.kind] ?? PER_ITEM_CAP))
+      return "per-item cap";
+    if (chunks > 0 && tokens + c.tokens > rules.budget)
+      return end = "budget";
+    perItem.set(c.itemId, taken + 1);
+    tokens += c.tokens;
+    chunks++;
+    kept++;
+    if (tokens >= rules.budget)
+      end = "budget";
+    return "kept";
+  });
+}
+function neighbourQuery(query, pinned) {
+  if (pinned.length === 0)
+    return query;
+  return pinned.map((i) => i.title).join("; ");
+}
+var ROOT_INSTRUCTION_FILES = /* @__PURE__ */ new Set(["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]);
+function isRootInstruction(relPath) {
+  return ROOT_INSTRUCTION_FILES.has(relPath);
 }
 function rankIn(list, id) {
   const i = list.indexOf(id);
   return i === -1 ? null : i + 1;
 }
+function parseMetadata(json2) {
+  if (!json2)
+    return void 0;
+  try {
+    const parsed = JSON.parse(json2);
+    return parsed && typeof parsed === "object" ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function whereOf(c) {
+  const book = text(c.metadata?.["book"]);
+  if (c.kind !== "document" || !book)
+    return [c.relPath, ...c.headingPath].join(" \u203A ");
+  const title = text(c.metadata?.["title"]);
+  const chapter = text(c.metadata?.["chapter"]);
+  const head = [chapter ? `Ch. ${chapter}` : "", title].filter(Boolean).join(" ");
+  const first = c.headingPath[0];
+  const rest = title && first && first.toLowerCase().includes(title.toLowerCase()) ? c.headingPath.slice(1) : c.headingPath;
+  return [book, head, ...rest].filter(Boolean).join(" \u203A ");
+}
+function text(value) {
+  return value === void 0 || value === null ? "" : String(value);
+}
 function formatDebug(result) {
   if (!result.debug)
     return "";
-  const lines = ["  vec  fts  factor  score    keep         where"];
+  const lines = [
+    `stage 2 searched: ${JSON.stringify(result.searchText)}${result.searchText === result.query ? "" : " (from the pinned titles)"}`,
+    "",
+    "  vec  fts  factor  score    keep         where"
+  ];
   for (const d of result.debug) {
-    const where = [d.relPath, ...d.headingPath].join(" \u203A ").slice(0, 70);
+    const where = whereOf(d).slice(0, 100);
     lines.push([
       String(d.vecRank ?? "-").padStart(5),
       String(d.ftsRank ?? "-").padStart(4),
@@ -11063,14 +11461,32 @@ function formatContext(result) {
   if (result.chunks.length === 0)
     return "(no relevant project knowledge found)";
   return result.chunks.map((c) => {
-    const where = [c.relPath, ...c.headingPath].join(" \u203A ");
-    const meta3 = [c.kind, c.status, c.updatedAt?.slice(0, 10)].filter(Boolean).join(", ");
-    return `### ${where}
+    const meta3 = citation(c) ?? [c.kind, c.status, c.updatedAt?.slice(0, 10)].filter(Boolean).join(", ");
+    return `### ${whereOf(c)}
 _${meta3}_
 
 ${c.text.trim()}`;
   }).join("\n\n");
 }
+function citation(c) {
+  const book = text(c.metadata?.["book"]);
+  if (c.kind !== "document" || !book)
+    return void 0;
+  const title = text(c.metadata?.["title"]);
+  const chapter = text(c.metadata?.["chapter"]);
+  const head = [chapter ? `Ch. ${chapter}` : "", title ? `"${title}"` : ""].filter(Boolean).join(" ");
+  const pp = pageRange(c.metadata?.["printed_pages"]);
+  return [book, text(c.metadata?.["author"]), head, pp ? `pp. ${pp}` : ""].filter(Boolean).join(", ");
+}
+function pageRange(value) {
+  if (!Array.isArray(value) || value.length === 0)
+    return void 0;
+  const from = text(value[0]);
+  const to = text(value[value.length - 1]);
+  if (!from)
+    return void 0;
+  return !to || to === from ? from : `${from}\u2013${to}`;
+}
 
 // ../index/dist/state.js
 function projectState(store) {
@@ -11081,7 +11497,8 @@ function projectState(store) {
   const live = (i) => (i.kind === "ticket" || i.kind === "plan") && (i.status === "open" || i.status === "in-progress");
   const rank = (i) => i.status === "in-progress" ? 0 : 1;
   const open2 = items.filter(live).sort((a, b) => rank(a) - rank(b) || a.rel_path.localeCompare(b.rel_path)).map((i) => ({ relPath: i.rel_path, name: i.name, status: i.status ?? "unknown", updatedAt: i.updated_at }));
-  const recentlyChanged = items.filter((i) => i.kind !== "commit").sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? "")).slice(0, 10).map((i) => ({ relPath: i.rel_path, kind: i.kind, updatedAt: i.updated_at }));
+  const STILL = /* @__PURE__ */ new Set(["commit", "document", "outline"]);
+  const recentlyChanged = items.filter((i) => !STILL.has(i.kind)).sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? "")).slice(0, 10).map((i) => ({ relPath: i.rel_path, kind: i.kind, updatedAt: i.updated_at }));
   const decisions = store.db.prepare("SELECT id, created_at, title FROM decisions ORDER BY id DESC LIMIT 10").all().map((d) => ({ id: d.id, createdAt: d.created_at, title: d.title }));
   return { counts, open: open2, recentlyChanged, decisions };
 }
@@ -16673,7 +17090,7 @@ __export(regexes_exports, {
   nanoid: () => nanoid,
   nanoidOfLength: () => nanoidOfLength,
   null: () => _null,
-  number: () => number,
+  number: () => number2,
   rfc5322Email: () => rfc5322Email,
   sha1_base64: () => sha1_base64,
   sha1_base64url: () => sha1_base64url,
@@ -16774,7 +17191,7 @@ var string = (params) => {
 };
 var bigint = /^-?\d+n?$/;
 var integer = /^-?\d+$/;
-var number = /^-?\d+(?:\.\d+)?$/;
+var number2 = /^-?\d+(?:\.\d+)?$/;
 var boolean = /^(?:true|false)$/i;
 var _null = /^null$/i;
 var _undefined = /^undefined$/i;
@@ -17901,7 +18318,7 @@ var $ZodCustomStringFormat = /* @__PURE__ */ $constructor("$ZodCustomStringForma
 });
 var $ZodNumber = /* @__PURE__ */ $constructor("$ZodNumber", (inst, def) => {
   $ZodType.init(inst, def);
-  inst._zod.pattern = number;
+  inst._zod.pattern = number2;
   inst._zod.parse = (payload, _ctx) => {
     if (def.coerce)
       try {
@@ -18978,7 +19395,7 @@ var $ZodRecord = /* @__PURE__ */ $constructor("$ZodRecord", (inst, def) => {
         if (keyResult instanceof Promise) {
           throw new Error("Async schemas not supported in object keys currently");
         }
-        const checkNumericKey = typeof key === "string" && number.test(key) && keyResult.issues.length;
+        const checkNumericKey = typeof key === "string" && number2.test(key) && keyResult.issues.length;
         if (checkNumericKey) {
           const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
           if (retryResult instanceof Promise) {
@@ -19545,7 +19962,7 @@ function leafPattern(schema) {
   if (minimum !== void 0 || maximum !== void 0)
     return string({ minimum, maximum }).source;
   const own2 = schema._zod.pattern;
-  return (isInt && own2 === number ? integer : own2)?.source;
+  return (isInt && own2 === number2 ? integer : own2)?.source;
 }
 function partPattern(schema) {
   const def = schema._zod.def;
@@ -24043,11 +24460,11 @@ function ko_default() {
 }
 
 // ../../node_modules/.bun/zod@4.6.5/node_modules/zod/v4/locales/lt.js
-var capitalizeFirstCharacter = (text) => {
-  return text.charAt(0).toUpperCase() + text.slice(1);
+var capitalizeFirstCharacter = (text2) => {
+  return text2.charAt(0).toUpperCase() + text2.slice(1);
 };
-function getUnitTypeFromNumber(number4) {
-  const abs = Math.abs(number4);
+function getUnitTypeFromNumber(number5) {
+  const abs = Math.abs(number5);
   const last = abs % 10;
   const last2 = abs % 100;
   if (last2 >= 11 && last2 <= 19 || last === 0)
@@ -29019,7 +29436,7 @@ function generateRecordCheck(doc, ctx, schema, accessor) {
     if (keyFn.definite === false)
       ctx.definite = false;
     const keyFast = addConstant(ctx, keyFn);
-    const numericConst = addConstant(ctx, number);
+    const numericConst = addConstant(ctx, number2);
     const outKeyVar = newVar(ctx);
     emitOwnKeys(doc, ctx, accessor, kVar, (d) => {
       d.write(`let ${outKeyVar} = ${keyFast}(${kVar});`);
@@ -31327,7 +31744,7 @@ function stringifyKeyNames(bySchema, json2, visited) {
     return rest;
   rest.type = "string";
   if (!values)
-    rest.pattern = (types.includes("number") ? number : integer).source;
+    rest.pattern = (types.includes("number") ? number2 : integer).source;
   return rest;
 }
 var pendingRecords = /* @__PURE__ */ new WeakMap();
@@ -32229,7 +32646,7 @@ __export(external_exports, {
   null: () => _null3,
   nullable: () => nullable,
   nullish: () => nullish2,
-  number: () => number2,
+  number: () => number3,
   object: () => object2,
   optional: () => optional,
   output: () => output,
@@ -32442,7 +32859,7 @@ __export(schemas_exports2, {
   null: () => _null3,
   nullable: () => nullable,
   nullish: () => nullish2,
-  number: () => number2,
+  number: () => number3,
   object: () => object2,
   optional: () => optional,
   partialRecord: () => partialRecord,
@@ -33188,7 +33605,7 @@ var ZodNumber2 = /* @__PURE__ */ $constructor(
     }
   })
 );
-function number2(params) {
+function number3(params) {
   return _number(ZodNumber2, params);
 }
 var ZodNumberFormat = /* @__PURE__ */ $constructor("ZodNumberFormat", (inst, def) => {
@@ -34028,7 +34445,7 @@ var stringbool = (...args) => _stringbool({
 }, ...args);
 function json(params) {
   const jsonSchema = lazy(() => {
-    return union([string2(params), number2(), boolean2(), _null3(), array(jsonSchema), record(string2(), jsonSchema)]);
+    return union([string2(params), number3(), boolean2(), _null3(), array(jsonSchema), record(string2(), jsonSchema)]);
   });
   return jsonSchema;
 }
@@ -34872,13 +35289,13 @@ __export(coerce_exports2, {
   bigint: () => bigint3,
   boolean: () => boolean3,
   date: () => date4,
-  number: () => number3,
+  number: () => number4,
   string: () => string3
 });
 function string3(params) {
   return _coercedString(ZodString2, params);
 }
-function number3(params) {
+function number4(params) {
   return _coercedNumber(ZodNumber2, params);
 }
 function boolean3(params) {
@@ -34897,20 +35314,20 @@ var SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, "2025-06-18", "2025-
 var RELATED_TASK_META_KEY = "io.modelcontextprotocol/related-task";
 var JSONRPC_VERSION = "2.0";
 var AssertObjectSchema = custom((v) => v !== null && (typeof v === "object" || typeof v === "function"));
-var ProgressTokenSchema = union([string2(), number2().int()]);
+var ProgressTokenSchema = union([string2(), number3().int()]);
 var CursorSchema = string2();
 var TaskCreationParamsSchema = looseObject({
   /**
    * Requested duration in milliseconds to retain task from creation.
    */
-  ttl: number2().optional(),
+  ttl: number3().optional(),
   /**
    * Time in milliseconds to wait between task status requests.
    */
-  pollInterval: number2().optional()
+  pollInterval: number3().optional()
 });
 var TaskMetadataSchema = object2({
-  ttl: number2().optional()
+  ttl: number3().optional()
 });
 var RelatedTaskMetadataSchema = object2({
   taskId: string2()
@@ -34965,7 +35382,7 @@ var ResultSchema = looseObject({
    */
   _meta: RequestMetaSchema.optional()
 });
-var RequestIdSchema = union([string2(), number2().int()]);
+var RequestIdSchema = union([string2(), number3().int()]);
 var JSONRPCRequestSchema = object2({
   jsonrpc: literal(JSONRPC_VERSION),
   id: RequestIdSchema,
@@ -35001,7 +35418,7 @@ var JSONRPCErrorResponseSchema = object2({
     /**
      * The error type that occurred.
      */
-    code: number2().int(),
+    code: number3().int(),
     /**
      * A short description of the error. The message SHOULD be limited to a concise single sentence.
      */
@@ -35300,11 +35717,11 @@ var ProgressSchema = object2({
   /**
    * The progress thus far. This should increase every time progress is made, even if the total is unknown.
    */
-  progress: number2(),
+  progress: number3(),
   /**
    * Total number of items to process (or total progress required), if known.
    */
-  total: optional(number2()),
+  total: optional(number3()),
   /**
    * An optional message describing the current progress.
    */
@@ -35347,7 +35764,7 @@ var TaskSchema = object2({
    * Time in milliseconds to keep task results available after completion.
    * If null, the task has unlimited lifetime until manually cleaned up.
    */
-  ttl: union([number2(), _null3()]),
+  ttl: union([number3(), _null3()]),
   /**
    * ISO 8601 timestamp when the task was created.
    */
@@ -35356,7 +35773,7 @@ var TaskSchema = object2({
    * ISO 8601 timestamp when the task was last updated.
    */
   lastUpdatedAt: string2(),
-  pollInterval: optional(number2()),
+  pollInterval: optional(number3()),
   /**
    * Optional diagnostic message for failed tasks or other status information.
    */
@@ -35441,7 +35858,7 @@ var AnnotationsSchema = object2({
   /**
    * Importance hint for the resource, from 0 (least) to 1 (most).
    */
-  priority: number2().min(0).max(1).optional(),
+  priority: number3().min(0).max(1).optional(),
   /**
    * ISO 8601 timestamp for the most recent modification.
    */
@@ -35469,7 +35886,7 @@ var ResourceSchema = object2({
    *
    * This can be used by Hosts to display file sizes and estimate context window usage.
    */
-  size: optional(number2()),
+  size: optional(number3()),
   /**
    * Optional annotations for the client.
    */
@@ -35892,7 +36309,7 @@ var ListChangedOptionsBaseSchema = object2({
    *
    * @default 300
    */
-  debounceMs: number2().int().nonnegative().default(300)
+  debounceMs: number3().int().nonnegative().default(300)
 });
 var LoggingLevelSchema = _enum2(["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]);
 var SetLevelRequestParamsSchema = BaseRequestParamsSchema.extend({
@@ -35937,15 +36354,15 @@ var ModelPreferencesSchema = object2({
   /**
    * How much to prioritize cost when selecting a model.
    */
-  costPriority: number2().min(0).max(1).optional(),
+  costPriority: number3().min(0).max(1).optional(),
   /**
    * How much to prioritize sampling speed (latency) when selecting a model.
    */
-  speedPriority: number2().min(0).max(1).optional(),
+  speedPriority: number3().min(0).max(1).optional(),
   /**
    * How much to prioritize intelligence and capabilities when selecting a model.
    */
-  intelligencePriority: number2().min(0).max(1).optional()
+  intelligencePriority: number3().min(0).max(1).optional()
 });
 var ToolChoiceSchema = object2({
   /**
@@ -36003,13 +36420,13 @@ var CreateMessageRequestParamsSchema = TaskAugmentedRequestParamsSchema.extend({
    * declares ClientCapabilities.sampling.context. These values may be removed in future spec releases.
    */
   includeContext: _enum2(["none", "thisServer", "allServers"]).optional(),
-  temperature: number2().optional(),
+  temperature: number3().optional(),
   /**
    * The requested maximum number of tokens to sample (to prevent runaway completions).
    *
    * The client MAY choose to sample fewer tokens than the requested maximum.
    */
-  maxTokens: number2().int(),
+  maxTokens: number3().int(),
   stopSequences: array(string2()).optional(),
   /**
    * Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.
@@ -36086,8 +36503,8 @@ var StringSchemaSchema = object2({
   type: literal("string"),
   title: string2().optional(),
   description: string2().optional(),
-  minLength: number2().optional(),
-  maxLength: number2().optional(),
+  minLength: number3().optional(),
+  maxLength: number3().optional(),
   format: _enum2(["email", "uri", "date", "date-time"]).optional(),
   default: string2().optional()
 });
@@ -36095,9 +36512,9 @@ var NumberSchemaSchema = object2({
   type: _enum2(["number", "integer"]),
   title: string2().optional(),
   description: string2().optional(),
-  minimum: number2().optional(),
-  maximum: number2().optional(),
-  default: number2().optional()
+  minimum: number3().optional(),
+  maximum: number3().optional(),
+  default: number3().optional()
 });
 var UntitledSingleSelectEnumSchemaSchema = object2({
   type: literal("string"),
@@ -36129,8 +36546,8 @@ var UntitledMultiSelectEnumSchemaSchema = object2({
   type: literal("array"),
   title: string2().optional(),
   description: string2().optional(),
-  minItems: number2().optional(),
-  maxItems: number2().optional(),
+  minItems: number3().optional(),
+  maxItems: number3().optional(),
   items: object2({
     type: literal("string"),
     enum: array(string2())
@@ -36141,8 +36558,8 @@ var TitledMultiSelectEnumSchemaSchema = object2({
   type: literal("array"),
   title: string2().optional(),
   description: string2().optional(),
-  minItems: number2().optional(),
-  maxItems: number2().optional(),
+  minItems: number3().optional(),
+  maxItems: number3().optional(),
   items: object2({
     anyOf: array(object2({
       const: string2(),
@@ -36223,7 +36640,7 @@ var ElicitResultSchema = ResultSchema.extend({
    * Per MCP spec, content is "typically omitted" for decline/cancel actions.
    * We normalize null to undefined for leniency while maintaining type compatibility.
    */
-  content: preprocess((val) => val === null ? void 0 : val, record(string2(), union([string2(), number2(), boolean2(), array(string2())])).optional())
+  content: preprocess((val) => val === null ? void 0 : val, record(string2(), union([string2(), number3(), boolean2(), array(string2())])).optional())
 });
 var ResourceTemplateReferenceSchema = object2({
   type: literal("ref/resource"),
@@ -36286,7 +36703,7 @@ var CompleteResultSchema = ResultSchema.extend({
     /**
      * The total number of completion options available. This can exceed the number of values actually sent in the response.
      */
-    total: optional(number2().int()),
+    total: optional(number3().int()),
     /**
      * Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.
      */
@@ -40384,21 +40801,31 @@ var StdioServerTransport = class {
 function createCapsaServer(options) {
   const embedder = options.embedder ?? ollamaEmbedder();
   const server = new McpServer({ name: "capsa", version: "0.0.1" });
+  const ensureFresh = freshener(options, embedder);
   server.registerTool("get_context", {
     title: "Get project context",
-    description: "Return the smallest set of project knowledge (runbooks, tickets, plans, decisions, instruction files) relevant to a task. Call this before starting work on a task; pass the task as you understand it.",
+    description: 'Return the smallest set of project knowledge (runbooks, tickets, plans, decisions, instruction files) relevant to a task. Call this before starting work on a task; pass the task as you understand it. Answers are markdown: each passage has a `###` heading saying where it is from and an italic line under it. For a chapter of an indexed book that line is its citation \u2014 `_<book>, <author>, Ch. <n> "<title>", pp. <from>\u2013<to>_` \u2014 so quote the book, the chapter and the printed pages when you use the passage, rather than the file it was read from.',
     inputSchema: {
       task: external_exports.string().describe("The task or question, in one or two sentences"),
-      maxTokens: external_exports.number().int().min(200).max(6e3).optional().describe("Token budget, default 1500")
+      // 3000 is a ceiling on a ceiling: retrieval stops at the relevance
+      // cliff long before it fills a budget, so a larger number only ever
+      // buys a longer tail of near-misses.
+      maxTokens: external_exports.number().int().min(200).max(3e3).optional().describe("Token budget, default 1500. Raise it when this project is a library of reference documents rather than a codebase: a book section runs several hundred tokens, so 1500 is a handful of them.")
     }
   }, async ({ task, maxTokens }) => {
+    const freshness = await ensureFresh();
     const store = openStore(options.projectRoot, embedder);
     try {
-      const result = await retrieve(store, embedder, task, { maxTokens, source: "mcp:get_context" });
+      const result = await retrieve(store, embedder, task, {
+        maxTokens,
+        source: "mcp:get_context",
+        excludeRootInstructions: true
+      });
+      const caveat = caveats(freshness, result.degraded);
       const footer = `
 
 ---
-_capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.durationMs} ms_`;
+_capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.durationMs} ms${caveat ? ` \xB7 ${caveat}` : ""}_`;
       return { content: [{ type: "text", text: formatContext(result) + footer }] };
     } finally {
       store.close();
@@ -40409,9 +40836,14 @@ _capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.du
     description: "Where the project stands: open tickets and plans, recent decisions, recently changed knowledge.",
     inputSchema: {}
   }, async () => {
+    const freshness = await ensureFresh();
     const store = openStore(options.projectRoot, embedder);
     try {
-      return { content: [{ type: "text", text: formatState(projectState(store)) }] };
+      const caveat = caveats(freshness);
+      const text2 = formatState(projectState(store)) + (caveat ? `
+
+_${caveat}_` : "");
+      return { content: [{ type: "text", text: text2 }] };
     } finally {
       store.close();
     }
@@ -40440,6 +40872,41 @@ _capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.du
   });
   return server;
 }
+function freshener(options, embedder) {
+  const maxAgeMs = options.maxIndexAgeMs ?? DEFAULT_MAX_INDEX_AGE_MS;
+  let inFlight = null;
+  return () => {
+    if (!inFlight) {
+      const run = (async () => {
+        let store;
+        try {
+          store = openStore(options.projectRoot, embedder);
+          return await freshenIndex(store, options.projectRoot, embedder, { maxAgeMs });
+        } catch (err) {
+          return { refreshed: false, stale: true, reason: err instanceof Error ? err.message : String(err) };
+        } finally {
+          store?.close();
+        }
+      })();
+      inFlight = run;
+      void run.finally(() => {
+        if (inFlight === run)
+          inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
+function caveats(freshness, degraded) {
+  const parts = [];
+  if (freshness.stale) {
+    parts.push(`index may be out of date \u2014 ${freshness.reason ?? "the last index run did not finish"}`);
+  }
+  if (degraded) {
+    parts.push(freshness.stale ? "keyword-only search (no embeddings)" : `keyword-only search \u2014 ${degraded}`);
+  }
+  return parts.join(" \xB7 ");
+}
 async function serveStdio(options) {
   const server = createCapsaServer(options);
   await server.connect(new StdioServerTransport());
@@ -40516,6 +40983,8 @@ async function runSearchCommand(args) {
     } else {
       console.log(formatContext(res));
     }
+    if (res.degraded) console.error(`
+capsa: keyword-only search \u2014 ${res.degraded}`);
     console.error(`
 ${res.chunks.length} chunks, ~${res.tokensEst} tokens, ${res.durationMs} ms`);
   } finally {
@@ -40569,8 +41038,8 @@ agent explicitly records.
 `;
 async function readVersion() {
   try {
-    const pkgPath = resolve4(dirname9(fileURLToPath2(import.meta.url)), "../package.json");
-    const pkg = JSON.parse(await readFile7(pkgPath, "utf8"));
+    const pkgPath = resolve4(dirname10(fileURLToPath2(import.meta.url)), "../package.json");
+    const pkg = JSON.parse(await readFile8(pkgPath, "utf8"));
     const version2 = pkg.version;
     return typeof version2 === "string" ? version2 : "unknown";
   } catch {