@drewpayment/mink 0.12.0-beta.4 → 0.12.0-beta.5

package/dist/cli.node.js

@@ -2681,15 +2681,8 @@ function addBacklink(targetNotePath, sourceTitle) {
   }
 }
 function updateMasterIndex(vaultRootPath) {
-  const now = new Date().toISOString().split("T")[0];
   const sections = [
-    `---`,
-    `updated: "${new Date().toISOString()}"`,
-    `---`,
-    ``,
     `# Knowledge Base`,
-    ``,
-    `> Last updated: ${now}`,
     ``
   ];
   const categories = [
@@ -2722,6 +2715,13 @@ function updateMasterIndex(vaultRootPath) {
     }
     sections.push("");
   }
+  const nowIso = new Date().toISOString();
+  const nowDate = nowIso.split("T")[0];
+  sections.push(`---`);
+  sections.push(``);
+  sections.push(`<!-- mink:footer (volatile — keep at end of file) -->`);
+  sections.push(`> Last updated: ${nowDate} (${nowIso})`);
+  sections.push(``);
   const indexPath = vaultMasterIndexPath();
   atomicWriteText(indexPath, sections.join(`
 `));
@@ -7098,20 +7098,46 @@ var init_pre_read = __esm(() => {
 var exports_post_read = {};
 __export(exports_post_read, {
   postRead: () => postRead,
+  extractContent: () => extractContent,
   analyzePostRead: () => analyzePostRead
 });
 import { relative as relative5 } from "path";
+import { readFileSync as readFileSync19 } from "fs";
 function analyzePostRead(filePath, content, index) {
   if (isBinaryFile(filePath, content ?? undefined)) {
     const entry = index ? index.lookupEntry(filePath) : null;
-    return { estimatedTokens: 0, indexHit: !!entry, source: "none" };
+    return {
+      estimatedTokens: 0,
+      indexHit: !!entry,
+      source: "none",
+      indexEntry: null
+    };
   }
   if (content !== null && content.length > 0) {
     const entry = index ? index.lookupEntry(filePath) : null;
+    const tokens = estimateTokens2(content, filePath);
+    let indexEntry = null;
+    if (!entry) {
+      let description = "";
+      try {
+        description = extractDescription(filePath, content);
+      } catch {
+        description = "";
+      }
+      const now = new Date().toISOString();
+      indexEntry = {
+        filePath,
+        description,
+        estimatedTokens: tokens,
+        lastModified: now,
+        lastIndexed: now
+      };
+    }
     return {
-      estimatedTokens: estimateTokens2(content, filePath),
+      estimatedTokens: tokens,
       indexHit: !!entry,
-      source: "content"
+      source: "content",
+      indexEntry
     };
   }
   if (index) {
@@ -7120,11 +7146,17 @@ function analyzePostRead(filePath, content, index) {
       return {
         estimatedTokens: entry.estimatedTokens,
         indexHit: true,
-        source: "index-fallback"
+        source: "index-fallback",
+        indexEntry: null
       };
     }
   }
-  return { estimatedTokens: 0, indexHit: false, source: "none" };
+  return {
+    estimatedTokens: 0,
+    indexHit: false,
+    source: "none",
+    indexEntry: null
+  };
 }
 function isPostToolUseInput(value) {
   if (value === null || typeof value !== "object")
@@ -7137,9 +7169,22 @@ function isPostToolUseInput(value) {
   return true;
 }
 function extractContent(input) {
-  if (!input.tool_output)
-    return null;
-  if (typeof input.tool_output.content === "string") {
+  const tr = input.tool_response;
+  if (tr) {
+    if (typeof tr.content === "string")
+      return tr.content;
+    if (Array.isArray(tr.content)) {
+      const parts = tr.content.map((p) => p && typeof p.text === "string" ? p.text : "").filter((s) => s.length > 0);
+      if (parts.length > 0)
+        return parts.join("");
+    }
+    if (tr.file && typeof tr.file.content === "string") {
+      return tr.file.content;
+    }
+    if (typeof tr.text === "string")
+      return tr.text;
+  }
+  if (input.tool_output && typeof input.tool_output.content === "string") {
     return input.tool_output.content;
   }
   return null;
@@ -7159,8 +7204,19 @@ async function postRead(cwd) {
     const rawState = safeReadJson(sessionPath(cwd));
     const state = isSessionState(rawState) ? rawState : createSessionState();
     const repo = FileIndexRepo.for(cwd);
-    const content = extractContent(input);
+    let content = null;
+    try {
+      content = readFileSync19(absolutePath, "utf-8");
+    } catch {}
+    if (content === null) {
+      content = extractContent(input);
+    }
     const result = analyzePostRead(filePath, content, repo);
+    if (result.indexEntry) {
+      try {
+        repo.upsert(result.indexEntry);
+      } catch {}
+    }
     recordRead(state, filePath, result.estimatedTokens, result.indexHit);
     try {
       const logWriter = createActionLogWriter(actionLogShardPath(cwd, getOrCreateDeviceId()));
@@ -7177,6 +7233,7 @@ var init_post_read = __esm(() => {
   init_session();
   init_file_index_repo();
   init_token_estimate();
+  init_description();
   init_action_log();
   init_device();
 });
@@ -7377,7 +7434,7 @@ __export(exports_post_write, {
   analyzePostWrite: () => analyzePostWrite
 });
 import { relative as relative7 } from "path";
-import { readFileSync as readFileSync19 } from "fs";
+import { readFileSync as readFileSync20 } from "fs";
 function analyzePostWrite(filePath, fileContent, index) {
   if (isWriteExcluded(filePath)) {
     return {
@@ -7441,7 +7498,7 @@ async function postWrite(cwd) {
     const filePath = relative7(cwd, absolutePath);
     let fileContent = null;
     try {
-      fileContent = readFileSync19(absolutePath, "utf-8");
+      fileContent = readFileSync20(absolutePath, "utf-8");
     } catch {}
     const rawState = safeReadJson(sessionPath(cwd));
     const state = isSessionState(rawState) ? rawState : createSessionState();
@@ -7794,7 +7851,7 @@ __export(exports_self_update, {
   PACKAGE_NAME: () => PACKAGE_NAME
 });
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync26, readFileSync as readFileSync20 } from "fs";
+import { existsSync as existsSync26, readFileSync as readFileSync21 } from "fs";
 import { dirname as dirname11 } from "path";
 import { join as join23 } from "path";
 function parseSemver(input) {
@@ -7861,7 +7918,7 @@ function getInstallInfo() {
   }
   let currentVersion = "0.0.0";
   try {
-    const pkg = JSON.parse(readFileSync20(packageJsonPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync21(packageJsonPath, "utf-8"));
     if (typeof pkg.version === "string")
       currentVersion = pkg.version;
   } catch {}
@@ -7934,7 +7991,7 @@ function appendLogEntry(entry) {
 }
 function rotateLogIfNeeded(path) {
   try {
-    const content = readFileSync20(path, "utf-8");
+    const content = readFileSync21(path, "utf-8");
     const lines = content.split(`
 `);
     if (lines.length <= LOG_MAX_LINES + 1)
@@ -8037,7 +8094,7 @@ async function runSelfUpgradeInner(opts) {
   }
   let verifiedVersion = latest;
   try {
-    const pkg = JSON.parse(readFileSync20(info.packageJsonPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync21(info.packageJsonPath, "utf-8"));
     if (typeof pkg.version === "string")
       verifiedVersion = pkg.version;
   } catch {}
@@ -8143,10 +8200,10 @@ async function executeTask(taskId, projectCwd) {
       if (task.actionType === "ai-cli") {
         try {
           const { learningMemoryPath: learningMemoryPath5 } = await Promise.resolve().then(() => (init_paths(), exports_paths));
-          const { readFileSync: readFileSync21 } = await import("fs");
+          const { readFileSync: readFileSync22 } = await import("fs");
           let memoryContent;
           try {
-            memoryContent = readFileSync21(learningMemoryPath5(projectCwd), "utf-8");
+            memoryContent = readFileSync22(learningMemoryPath5(projectCwd), "utf-8");
           } catch {
             console.log("[mink] no learning memory found, skipping reflection");
             return;
@@ -8711,7 +8768,7 @@ var init_cron = __esm(() => {
 
 // src/core/vault-templates.ts
 import { join as join24 } from "path";
-import { existsSync as existsSync27, writeFileSync as writeFileSync9, readFileSync as readFileSync21, mkdirSync as mkdirSync13 } from "fs";
+import { existsSync as existsSync27, writeFileSync as writeFileSync9, readFileSync as readFileSync22, mkdirSync as mkdirSync13 } from "fs";
 function seedTemplates(templatesDir) {
   mkdirSync13(templatesDir, { recursive: true });
   for (const [name, content] of Object.entries(DEFAULT_TEMPLATES)) {
@@ -8725,7 +8782,7 @@ function loadTemplate(templatesDir, templateName, vars) {
   const filePath = join24(templatesDir, `${templateName}.md`);
   let content;
   if (existsSync27(filePath)) {
-    content = readFileSync21(filePath, "utf-8");
+    content = readFileSync22(filePath, "utf-8");
   } else if (DEFAULT_TEMPLATES[templateName]) {
     content = DEFAULT_TEMPLATES[templateName];
   } else {
@@ -8879,7 +8936,7 @@ category: resources
 
 // src/core/note-writer.ts
 import { join as join25 } from "path";
-import { existsSync as existsSync28, readFileSync as readFileSync22 } from "fs";
+import { existsSync as existsSync28, readFileSync as readFileSync23 } from "fs";
 import { createHash as createHash4 } from "crypto";
 function sha256(content) {
   return createHash4("sha256").update(content).digest("hex");
@@ -8904,7 +8961,7 @@ function resolveUniqueNotePath(dir, baseSlug, content) {
 }
 function sameContent(filePath, expectedHash) {
   try {
-    return sha256(readFileSync22(filePath, "utf-8")) === expectedHash;
+    return sha256(readFileSync23(filePath, "utf-8")) === expectedHash;
   } catch {
     return false;
   }
@@ -9013,7 +9070,7 @@ ${content}
   return filePath;
 }
 function ingestFile(sourcePath, meta) {
-  const raw = readFileSync22(sourcePath, "utf-8");
+  const raw = readFileSync23(sourcePath, "utf-8");
   const now = new Date().toISOString();
   const headingMatch = raw.match(/^#\s+(.+)$/m);
   const title = headingMatch?.[1] ?? sourcePath.split("/").pop().replace(/\.md$/, "");
@@ -9085,7 +9142,7 @@ var init_design_eval = __esm(() => {
 });
 
 // src/core/dashboard-api.ts
-import { existsSync as existsSync29, readFileSync as readFileSync23 } from "fs";
+import { existsSync as existsSync29, readFileSync as readFileSync24 } from "fs";
 import { readdirSync as readdirSync9, readFileSync as readFileSyncFS, existsSync as fsExistsSync } from "fs";
 import { join as join26, resolve as resolve5, normalize, sep } from "path";
 import { execSync as execSync6 } from "child_process";
@@ -9113,7 +9170,7 @@ function checkTextFile2(name, filePath) {
   if (!existsSync29(filePath))
     return { name, status: "missing" };
   try {
-    readFileSync23(filePath, "utf-8");
+    readFileSync24(filePath, "utf-8");
     return { name, status: "ok" };
   } catch {
     return { name, status: "corrupt" };
@@ -9123,7 +9180,7 @@ function checkDbFile2(name, filePath) {
   if (!existsSync29(filePath))
     return { name, status: "missing" };
   try {
-    const header = readFileSync23(filePath).slice(0, 16).toString("utf-8");
+    const header = readFileSync24(filePath).slice(0, 16).toString("utf-8");
     return header.startsWith("SQLite format 3") ? { name, status: "ok" } : { name, status: "corrupt" };
   } catch {
     return { name, status: "corrupt" };
@@ -10785,7 +10842,7 @@ var exports_daemon = {};
 __export(exports_daemon, {
   daemon: () => daemon
 });
-import { readFileSync as readFileSync24, existsSync as existsSync34 } from "fs";
+import { readFileSync as readFileSync25, existsSync as existsSync34 } from "fs";
 async function daemon(cwd, args) {
   const subcommand = args[0];
   switch (subcommand) {
@@ -10806,7 +10863,7 @@ async function daemon(cwd, args) {
         return;
       }
       try {
-        const content = readFileSync24(logPath, "utf-8");
+        const content = readFileSync25(logPath, "utf-8");
         const lines = content.split(`
 `);
         const tail = lines.slice(-50).join(`
@@ -11387,7 +11444,7 @@ var init_restore = __esm(() => {
 });
 
 // src/core/design-eval/server-detect.ts
-import { readFileSync as readFileSync25 } from "fs";
+import { readFileSync as readFileSync26 } from "fs";
 import { join as join30 } from "path";
 async function probePort(port) {
   try {
@@ -11410,7 +11467,7 @@ async function findRunningServer(ports = DEFAULT_PROBE_PORTS) {
 }
 function detectDevCommand(cwd) {
   try {
-    const raw = readFileSync25(join30(cwd, "package.json"), "utf-8");
+    const raw = readFileSync26(join30(cwd, "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
     const scripts = pkg.scripts;
     if (!scripts || typeof scripts !== "object")
@@ -83779,7 +83836,7 @@ var init_fileUtil = __esm(() => {
 // node_modules/@puppeteer/browsers/lib/esm/install.js
 import assert2 from "node:assert";
 import { spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync36, readFileSync as readFileSync26 } from "node:fs";
+import { existsSync as existsSync36, readFileSync as readFileSync27 } from "node:fs";
 import { mkdir as mkdir2, unlink } from "node:fs/promises";
 import os5 from "node:os";
 import path8 from "node:path";
@@ -83869,7 +83926,7 @@ async function installDeps(installedBrowser) {
     debugInstall(`deb.deps file was not found at ${depsPath}`);
     return;
   }
-  const data = readFileSync26(depsPath, "utf-8").split(`
+  const data = readFileSync27(depsPath, "utf-8").split(`
 `).join(",");
   if (process.getuid?.() !== 0) {
     throw new Error("Installing system dependencies requires root privileges");
@@ -85394,14 +85451,14 @@ var init_yerror = __esm(() => {
 });
 
 // node_modules/y18n/build/lib/platform-shims/node.js
-import { readFileSync as readFileSync27, statSync as statSync14, writeFile } from "fs";
+import { readFileSync as readFileSync28, statSync as statSync14, writeFile } from "fs";
 import { format as format2 } from "util";
 import { resolve as resolve12 } from "path";
 var node_default;
 var init_node = __esm(() => {
   node_default = {
     fs: {
-      readFileSync: readFileSync27,
+      readFileSync: readFileSync28,
       writeFile
     },
     format: format2,
@@ -85586,7 +85643,7 @@ var init_y18n = __esm(() => {
 // node_modules/yargs/lib/platform-shims/esm.mjs
 import { notStrictEqual, strictEqual } from "assert";
 import { inspect } from "util";
-import { readFileSync as readFileSync28 } from "fs";
+import { readFileSync as readFileSync29 } from "fs";
 import { fileURLToPath } from "url";
 import { basename as basename9, dirname as dirname16, extname as extname3, relative as relative9, resolve as resolve13 } from "path";
 var REQUIRE_ERROR = "require is not supported by ESM", REQUIRE_DIRECTORY_ERROR = "loading a directory of commands is not supported yet for ESM", __dirname2, mainFilename, esm_default;
@@ -85635,7 +85692,7 @@ var init_esm = __esm(() => {
       nextTick: process.nextTick,
       stdColumns: typeof process.stdout.columns !== "undefined" ? process.stdout.columns : null
     },
-    readFileSync: readFileSync28,
+    readFileSync: readFileSync29,
     require: () => {
       throw new YError(REQUIRE_ERROR);
     },
@@ -91894,7 +91951,7 @@ function generateKnowledgeMarkdown(k) {
   const parts = [];
   parts.push(`# Framework Advisor Knowledge Base`);
   parts.push("");
-  parts.push(`> Generated: ${k.generatedAt} | Version: ${k.version} | Frameworks: ${k.frameworks.length}`);
+  parts.push(`> Version: ${k.version} | Frameworks: ${k.frameworks.length}`);
   parts.push("");
   parts.push("## Comparison Matrix");
   parts.push("");
@@ -91950,6 +92007,11 @@ function generateKnowledgeMarkdown(k) {
       parts.push("");
     }
   }
+  parts.push(`---`);
+  parts.push(``);
+  parts.push(`<!-- mink:footer (volatile — keep at end of file) -->`);
+  parts.push(`> Generated: ${k.generatedAt}`);
+  parts.push(``);
   return parts.join(`
 `);
 }
@@ -92425,7 +92487,7 @@ __export(exports_note, {
   note: () => note
 });
 import { resolve as resolve15 } from "path";
-import { existsSync as existsSync40, readFileSync as readFileSync29 } from "fs";
+import { existsSync as existsSync40, readFileSync as readFileSync30 } from "fs";
 async function note(cwd, args) {
   if (!isWikiEnabled()) {
     console.error("[mink] wiki feature is disabled");
@@ -92450,7 +92512,7 @@ async function note(cwd, args) {
     const date = new Date().toISOString().split("T")[0];
     const content = parsed.positional || parsed.body || "";
     const filePath = appendToDaily(date, content);
-    updateVaultIndexForFile(filePath, readFileSync29(filePath, "utf-8"));
+    updateVaultIndexForFile(filePath, readFileSync30(filePath, "utf-8"));
     console.log(`[mink] daily note: ${filePath}`);
     return;
   }
@@ -92783,7 +92845,7 @@ import { homedir as homedir7 } from "os";
 import {
   existsSync as existsSync42,
   mkdirSync as mkdirSync18,
-  readFileSync as readFileSync30,
+  readFileSync as readFileSync31,
   writeFileSync as writeFileSync11
 } from "fs";
 import { createHash as createHash5 } from "crypto";
@@ -92807,7 +92869,7 @@ function getMinkVersion() {
     const pkgPath = join36(dir, "package.json");
     if (existsSync42(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync30(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync31(pkgPath, "utf-8"));
         if (pkg.name && pkg.version)
           return pkg.version;
       } catch {}
@@ -92845,7 +92907,7 @@ function installAgentDefinition(opts) {
   if (opts.skip && existsSync42(installed)) {
     return { action: "skipped", path: installed };
   }
-  const template = readFileSync30(templatePath, "utf-8");
+  const template = readFileSync31(templatePath, "utf-8");
   const rendered = renderTemplate(template, {
     MINK_ROOT: minkRoot(),
     VAULT_PATH: resolveVaultPath(),
@@ -92853,7 +92915,7 @@ function installAgentDefinition(opts) {
   });
   const exists = existsSync42(installed);
   if (!opts.force && exists) {
-    const current = readFileSync30(installed, "utf-8");
+    const current = readFileSync31(installed, "utf-8");
     if (sha2562(current) === sha2562(rendered)) {
       return { action: "unchanged", path: installed };
     }
@@ -92981,7 +93043,7 @@ var init_agent = __esm(() => {
 });
 
 // src/core/sync-merge-drivers.ts
-import { readFileSync as readFileSync31, writeFileSync as writeFileSync12, appendFileSync as appendFileSync2, copyFileSync as copyFileSync2, unlinkSync as unlinkSync7 } from "fs";
+import { readFileSync as readFileSync32, writeFileSync as writeFileSync12, appendFileSync as appendFileSync2, copyFileSync as copyFileSync2, unlinkSync as unlinkSync7 } from "fs";
 import { join as join37 } from "path";
 function logWarning(driver, args, err) {
   try {
@@ -92992,14 +93054,14 @@ function logWarning(driver, args, err) {
 }
 function readJsonOrNull(path12) {
   try {
-    return JSON.parse(readFileSync31(path12, "utf-8"));
+    return JSON.parse(readFileSync32(path12, "utf-8"));
   } catch {
     return null;
   }
 }
 function readTextOrEmpty(path12) {
   try {
-    return readFileSync31(path12, "utf-8");
+    return readFileSync32(path12, "utf-8");
   } catch {
     return "";
   }
@@ -93889,9 +93951,9 @@ switch (command2) {
     const { resolve: resolve18, dirname: dirname20, basename: basename10 } = await import("path");
     const bundlePath = new URL(import.meta.url).pathname;
     const cliPath = resolve18(dirname20(bundlePath));
-    const { readFileSync: readFileSync32 } = await import("fs");
+    const { readFileSync: readFileSync33 } = await import("fs");
     try {
-      const pkg = JSON.parse(readFileSync32(resolve18(cliPath, "../package.json"), "utf-8"));
+      const pkg = JSON.parse(readFileSync33(resolve18(cliPath, "../package.json"), "utf-8"));
       console.log(`mink ${pkg.version}`);
     } catch {
       console.log("mink (unknown version)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.12.0-beta.4",
+  "version": "0.12.0-beta.5",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {

package/src/commands/post-read.ts

@@ -1,20 +1,26 @@
 import { relative } from "path";
+import { readFileSync } from "fs";
 import { readStdinJson } from "../core/stdin";
 import { sessionPath, actionLogShardPath } from "../core/paths";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState, recordRead } from "../core/session";
 import { FileIndexRepo } from "../repositories/file-index-repo";
 import { estimateTokens, isBinaryFile } from "../core/token-estimate";
+import { extractDescription } from "../core/description";
 import { createActionLogWriter } from "../core/action-log";
 import { getOrCreateDeviceId } from "../core/device";
 import type { SessionState } from "../types/session";
-import type { IndexLookup } from "../types/file-index";
+import type { FileIndexEntry, IndexLookup } from "../types/file-index";
 import type { PostToolUseInput } from "../types/hook-input";
 
 export interface PostReadResult {
   estimatedTokens: number;
   indexHit: boolean;
   source: "content" | "index-fallback" | "none";
+  // Populated when content was available and the file was not already in
+  // the index — lets the caller seed the index lazily so that read-only
+  // browsing sessions don't accumulate zero index hits.
+  indexEntry: FileIndexEntry | null;
 }
 
 export function analyzePostRead(
@@ -25,16 +31,42 @@ export function analyzePostRead(
   // Binary file — skip token estimation
   if (isBinaryFile(filePath, content ?? undefined)) {
     const entry = index ? index.lookupEntry(filePath) : null;
-    return { estimatedTokens: 0, indexHit: !!entry, source: "none" };
+    return {
+      estimatedTokens: 0,
+      indexHit: !!entry,
+      source: "none",
+      indexEntry: null,
+    };
   }
 
   // Content available — estimate from actual content
   if (content !== null && content.length > 0) {
     const entry = index ? index.lookupEntry(filePath) : null;
+    const tokens = estimateTokens(content, filePath);
+    // On miss, build a seed entry so the index grows from reads, not just
+    // writes and scans. Description failures must never throw out the read.
+    let indexEntry: FileIndexEntry | null = null;
+    if (!entry) {
+      let description = "";
+      try {
+        description = extractDescription(filePath, content);
+      } catch {
+        description = "";
+      }
+      const now = new Date().toISOString();
+      indexEntry = {
+        filePath,
+        description,
+        estimatedTokens: tokens,
+        lastModified: now,
+        lastIndexed: now,
+      };
+    }
     return {
-      estimatedTokens: estimateTokens(content, filePath),
+      estimatedTokens: tokens,
       indexHit: !!entry,
       source: "content",
+      indexEntry,
     };
   }
 
@@ -46,11 +78,17 @@ export function analyzePostRead(
         estimatedTokens: entry.estimatedTokens,
         indexHit: true,
         source: "index-fallback",
+        indexEntry: null,
       };
     }
   }
 
-  return { estimatedTokens: 0, indexHit: false, source: "none" };
+  return {
+    estimatedTokens: 0,
+    indexHit: false,
+    source: "none",
+    indexEntry: null,
+  };
 }
 
 function isPostToolUseInput(value: unknown): value is PostToolUseInput {
@@ -61,9 +99,32 @@ function isPostToolUseInput(value: unknown): value is PostToolUseInput {
   return true;
 }
 
-function extractContent(input: PostToolUseInput): string | null {
-  if (!input.tool_output) return null;
-  if (typeof input.tool_output.content === "string") {
+// Pull file content out of the PostToolUse payload. Claude Code has shipped
+// at least two payload shapes for the Read tool:
+//   • legacy: `tool_output.content` is a plain string
+//   • current: `tool_response` carries the content — either as a string, as
+//     a Content[]-style array (`{ type: "text", text: "..." }`), or nested
+//     under `tool_response.file.content`
+// We accept any of them so a hook contract drift can't silently zero out
+// token estimation again.
+export function extractContent(input: PostToolUseInput): string | null {
+  // Current shape — tool_response
+  const tr = input.tool_response;
+  if (tr) {
+    if (typeof tr.content === "string") return tr.content;
+    if (Array.isArray(tr.content)) {
+      const parts = tr.content
+        .map((p) => (p && typeof p.text === "string" ? p.text : ""))
+        .filter((s) => s.length > 0);
+      if (parts.length > 0) return parts.join("");
+    }
+    if (tr.file && typeof tr.file.content === "string") {
+      return tr.file.content;
+    }
+    if (typeof tr.text === "string") return tr.text;
+  }
+  // Legacy shape — tool_output
+  if (input.tool_output && typeof input.tool_output.content === "string") {
     return input.tool_output.content;
   }
   return null;
@@ -92,11 +153,35 @@ export async function postRead(cwd: string): Promise<void> {
     // File index repository — one-key lookup, no whole-index load.
     const repo = FileIndexRepo.for(cwd);
 
-    // Extract content from tool output
-    const content = extractContent(input);
+    // Primary path: read content from disk by file path. This is the
+    // cleanest source because it doesn't depend on Claude Code's evolving
+    // hook payload schema (which has silently dropped `tool_output.content`
+    // in favor of nested `tool_response` shapes, breaking token
+    // measurement). Mirrors post-write.ts's approach.
+    let content: string | null = null;
+    try {
+      content = readFileSync(absolutePath, "utf-8");
+    } catch {
+      // File unreadable (permissions, deleted between read and hook) —
+      // fall back to whatever the payload carries.
+    }
+    if (content === null) {
+      content = extractContent(input);
+    }
 
     const result = analyzePostRead(filePath, content, repo);
 
+    // Seed the file index on a miss. Read-only browsing sessions otherwise
+    // accumulate zero index hits because the index only grows via
+    // `mink scan` (capped) or post-write.
+    if (result.indexEntry) {
+      try {
+        repo.upsert(result.indexEntry);
+      } catch {
+        // Never crash the hook over an index upsert failure.
+      }
+    }
+
     // Record the read in session state
     recordRead(state, filePath, result.estimatedTokens, result.indexHit);
 

package/src/core/framework-advisor/generate.ts

@@ -24,10 +24,13 @@ export function generateKnowledgeMarkdown(
 ): string {
   const parts: string[] = [];
 
+  // Prompt-cache stability: keep the title and stable summary line (counts
+  // only — no timestamps) at the top. The volatile `generatedAt` timestamp
+  // lives in the footer so regeneration doesn't bust LLM prefix caches.
   parts.push(`# Framework Advisor Knowledge Base`);
   parts.push("");
   parts.push(
-    `> Generated: ${k.generatedAt} | Version: ${k.version} | Frameworks: ${k.frameworks.length}`
+    `> Version: ${k.version} | Frameworks: ${k.frameworks.length}`
   );
   parts.push("");
 
@@ -111,6 +114,13 @@ export function generateKnowledgeMarkdown(
     }
   }
 
+  // ── Footer (volatile — must stay at end for prompt-cache stability) ──
+  parts.push(`---`);
+  parts.push(``);
+  parts.push(`<!-- mink:footer (volatile — keep at end of file) -->`);
+  parts.push(`> Generated: ${k.generatedAt}`);
+  parts.push(``);
+
   return parts.join("\n");
 }