@yurtsever/capsa 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/index.js

@@ -7415,6 +7415,7 @@ function findProjectRoot(startDir, homeDir) {
 // ../core/dist/chunk.js
 var DEFAULT_MAX_CHARS = 2e3;
 function chunkMarkdown(markdown, maxChars = DEFAULT_MAX_CHARS) {
+  const body = parseFrontmatter(markdown).body;
   const chunks = [];
   const trail = [];
   let buffer = [];
@@ -7424,11 +7425,12 @@ function chunkMarkdown(markdown, maxChars = DEFAULT_MAX_CHARS) {
     buffer = [];
     if (!text)
       return;
+    const headingPath = trail.filter((s) => Boolean(s));
     for (const part of splitLong(text, maxChars)) {
-      chunks.push({ index: chunks.length, headingPath: [...trail], text: part });
+      chunks.push({ index: chunks.length, headingPath, text: part });
     }
   };
-  for (const line of markdown.split(/\r?\n/)) {
+  for (const line of body.split(/\r?\n/)) {
     if (/^```/.test(line.trim()))
       inFence = !inFence;
     const heading = !inFence && /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
@@ -10072,7 +10074,32 @@ function loadSqlite() {
 }
 var DB_DIR = ".capsa";
 var DB_FILE = "index.db";
-var SCHEMA_VERSION = 3;
+var SCHEMA_VERSION = 7;
+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
+      -- tables its rows are never dropped, so a row has to stand on its own:
+      -- it records what was delivered (path, heading trail, tokens per chunk)
+      -- rather than chunk ids, which a rebuild hands to different text.
+      CREATE TABLE IF NOT EXISTS context_log (
+        id           INTEGER PRIMARY KEY,
+        created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+        source       TEXT NOT NULL,
+        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
+      );
+`;
 function dbPath(projectRoot) {
   return join6(projectRoot, DB_DIR, DB_FILE);
 }
@@ -10091,24 +10118,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(`
@@ -10119,6 +10166,7 @@ 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,
@@ -10158,19 +10206,44 @@ var Store = class {
         related    TEXT
       );
 
-      -- Every context delivery. This is the measurement for the MVP gate and
-      -- the seed of the organisation tier's audit log.
-      CREATE TABLE IF NOT EXISTS context_log (
-        id           INTEGER PRIMARY KEY,
-        created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-        source       TEXT NOT NULL,
-        query        TEXT NOT NULL,
-        chunk_ids    TEXT NOT NULL,
-        tokens_est   INTEGER NOT NULL,
-        duration_ms  INTEGER NOT NULL
-      );
+      ${CONTEXT_LOG_DDL}
+    `);
+    this.migrateContextLog();
+    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 — 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();
+    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_old;
+      ${CONTEXT_LOG_DDL}
+      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;
     `);
-    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES ('dimensions', ?)").run(String(this.dimensions));
   }
   getItem(path) {
     return this.db.prepare("SELECT * FROM items WHERE path = ?").get(path);
@@ -10187,13 +10260,14 @@ 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)
+         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);
+           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);
   }
   /**
    * `text` is what the user sees; `searchText` (chunk + provenance header)
@@ -10224,7 +10298,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
          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"],
@@ -10237,6 +10311,7 @@ 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"],
@@ -10254,11 +10329,22 @@ 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, chunk_ids, tokens_est, duration_ms) VALUES (?, ?, ?, ?, ?)").run(entry.source, entry.query, JSON.stringify(entry.chunkIds), 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,
+   * and the indexed item dates itself from it.
+   */
   recordDecision(title, body, related) {
     const res = this.db.prepare("INSERT INTO decisions (title, body, related) VALUES (?, ?, ?)").run(title, body, related ? JSON.stringify(related) : null);
-    return Number(res.lastInsertRowid);
+    return this.decision(Number(res.lastInsertRowid));
+  }
+  decision(id) {
+    return this.db.prepare("SELECT * FROM decisions WHERE id = ?").get(id);
+  }
+  /** Every decision, oldest first. The rows survive `reset()`; the items do not. */
+  listDecisions() {
+    return this.db.prepare("SELECT * FROM decisions ORDER BY id").all();
   }
   close() {
     this.db.close();
@@ -10604,6 +10690,66 @@ function firstHeading2(raw2) {
   return void 0;
 }
 
+// ../index/dist/decision.js
+import { join as join8 } from "path";
+var ITEM_DIR2 = join8(".capsa", "decisions");
+function decisionPath(projectRoot, id) {
+  return join8(projectRoot, ITEM_DIR2, `decision-${id}.md`);
+}
+function decisionItem(projectRoot, row) {
+  const path = decisionPath(projectRoot, row.id);
+  const related = parseRelated(row.related);
+  return {
+    id: stableId(path),
+    format: "decision",
+    formatLabel: "Decision",
+    name: row.title,
+    // The description becomes the provenance line of every embedded chunk.
+    description: row.title,
+    path,
+    scope: "project",
+    projectRoot,
+    content: renderDecision(row, related),
+    metadata: { decisionId: row.id, author: row.author, createdAt: row.created_at, related },
+    knowledge: {
+      kind: "decision",
+      // Written once, never edited: the day it was made is the day it last
+      // changed, so recency ranks it from `created_at`.
+      updatedAt: row.created_at,
+      // No lifecycle to report. "unknown" is the neutral weight (1.0) and
+      // says so out loud instead of leaving the column blank.
+      status: "unknown",
+      relatedPaths: related.length ? related : void 0
+    }
+  };
+}
+function renderDecision(row, related) {
+  const lines = [
+    `# ${row.title}`,
+    "",
+    `decision \`#${row.id}\` \xB7 ${row.author} \xB7 ${row.created_at.slice(0, 10)}`,
+    "",
+    row.body.trim()
+  ];
+  if (related.length) {
+    lines.push("", "## Related", "");
+    for (const p of related)
+      lines.push(`- ${p}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function parseRelated(json2) {
+  if (!json2)
+    return [];
+  try {
+    const parsed = JSON.parse(json2);
+    return Array.isArray(parsed) ? parsed.filter((p) => typeof p === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
 // ../index/dist/indexer.js
 function knowledgeAdapters() {
   return [
@@ -10619,70 +10765,152 @@ 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);
-      const chunks = chunkMarkdown(item.content);
-      const searchTexts = chunks.map((c) => withContext(item, c.headingPath, c.text));
-      const vectors = searchTexts.length ? await embedder.embed(searchTexts) : [];
-      const k = item.knowledge;
-      store.upsertItem({
-        id: item.id,
-        format: item.format,
-        kind: k?.kind ?? "instruction",
-        name: item.name,
-        path: item.path,
-        rel_path: relative5(projectRoot, item.path),
-        content_hash: hash2,
-        status: k?.status ?? null,
-        updated_at: k?.updatedAt ?? null,
-        tags: k?.tags ? JSON.stringify(k.tags) : null
-      });
-      chunks.forEach((c, i) => store.insertChunk(item.id, c.index, c.headingPath, c.text, vectors[i], searchTexts[i]));
-      indexed++;
-      onProgress?.({ phase: "embed", scanned: items.length, indexed, 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,
-      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();
   }
 }
+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) {
+      skipped++;
+      continue;
+    }
+    changed.push({ item, hash: hash2, previousId: existing?.id });
+  }
+  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);
+  const item = decisionItem(projectRoot, row);
+  try {
+    await indexItem(store, embedder, item, projectRoot, sha1(item.content));
+    return { id: row.id, indexed: true };
+  } catch (err) {
+    return { id: row.id, indexed: false, reason: err.message };
+  }
+}
+async function indexItem(store, embedder, item, projectRoot, hash2, previousId) {
+  const 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),
+    content_hash: hash2,
+    status: k?.status ?? null,
+    updated_at: k?.updatedAt ?? null,
+    tags: k?.tags ? JSON.stringify(k.tags) : null
+  });
+  chunks.forEach((c, i) => store.insertChunk(item.id, c.index, c.headingPath, c.text, vectors[i], searchTexts[i]));
+}
 function withContext(item, headingPath, text) {
   const kind = item.knowledge?.kind ?? "instruction";
   const head = [kind, item.description ?? item.name, ...headingPath].filter(Boolean).join(" \u203A ");
@@ -10831,9 +11059,17 @@ async function retrieve(store, embedder, query, options = {}) {
   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();
@@ -10842,10 +11078,33 @@ 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;
+  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),
+          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 best = neighbourhood[0]?.score ?? 0;
   let cut = tokens >= maxTokens;
   let kept = 0;
-  for (const { row, fusedScore, factor, score } of scored) {
+  for (const { row, fusedScore, factor, score } of neighbourhood) {
     let why = "kept";
     if (cut || kept > 0 && score < best * neighbourCutoff) {
       cut = true;
@@ -10893,13 +11152,37 @@ async function retrieve(store, embedder, query, options = {}) {
   }
   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,
-    chunkIds: chunks.map((c) => c.chunkId),
+    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 } : {}
+  };
+}
+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);
@@ -10908,7 +11191,11 @@ function rankIn(list, id) {
 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);
     lines.push([
@@ -40247,21 +40534,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.",
     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")
     }
   }, 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();
@@ -40272,9 +40569,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 text = formatState(projectState(store)) + (caveat ? `
+
+_${caveat}_` : "");
+      return { content: [{ type: "text", text }] };
     } finally {
       store.close();
     }
@@ -40290,14 +40592,54 @@ _capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.du
   }, async ({ title, body, related }) => {
     const store = openStore(options.projectRoot, embedder);
     try {
-      const id = store.recordDecision(title, body, related);
-      return { content: [{ type: "text", text: `Recorded decision #${id}: ${title}` }] };
+      const { id, indexed, reason } = await recordDecision(store, embedder, options.projectRoot, {
+        title,
+        body,
+        related
+      });
+      const note = indexed ? "" : ` \u2014 not searchable yet (${reason}); run \`capsa index\` once that is fixed`;
+      return { content: [{ type: "text", text: `Recorded decision #${id}: ${title}${note}` }] };
     } finally {
       store.close();
     }
   });
   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());
@@ -40374,6 +40716,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yurtsever/capsa",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "Your project's knowledge in one capsule. Local-first project memory and cockpit for AI coding agents: indexes runbooks, tickets, plans and instruction files, serves the smallest relevant context over MCP.",
   "type": "module",
   "license": "MIT",