knit-mcp 0.11.2 → 0.12.0

package/README.md

@@ -3,7 +3,7 @@
   <a href="https://github.com/PDgit12/knit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/PDgit12/knit/ci.yml?style=for-the-badge&label=CI&color=10b981" alt="CI" /></a>
   <img src="https://img.shields.io/badge/license-MIT-3b82f6?style=for-the-badge" alt="license" />
   <img src="https://img.shields.io/badge/node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" />
-  <img src="https://img.shields.io/badge/tests-664%20passing-22c55e?style=for-the-badge" alt="tests" />
+  <img src="https://img.shields.io/badge/tests-665%20passing-22c55e?style=for-the-badge" alt="tests" />
   <img src="https://img.shields.io/badge/MCP%20tools-53-7c3aed?style=for-the-badge" alt="tools" />
 </p>
 
@@ -452,6 +452,9 @@ LongMemEval-S R@5/R@10 + LOCOMO LLM-as-Judge runs are on the roadmap (v0.13+). U
 
 | Version | Headline |
 |---|---|
+| **v0.12.0** | **Picture Perfect: Structural Enforcement.** Diagnostic → enforcing. Budget verdict surfaces in the MCP `instructions` field at handshake (before any tool description is read). `knit_load_session` carries `budget_health` + `learnings_health` nudges. `engram doctor` exits non-zero on over-budget; `engram setup` runs doctor as final step. New PostToolUse hook warns immediately on over-budget CLAUDE.md edits (HOOKS_VERSION 11→12; auto-rolls to existing users). This repo dogfoods: hand-curated 16KB CLAUDE.md migrated to lean 3.8KB + `.claude/MARKETING.md` sidecar. New `npm run bench:tokens` measures real MCP-on vs MCP-off cost: 93% smaller per-recall call, 50% smaller per-classify, payback at 3 recall calls. 53 tools, 705 tests. |
+| **v0.11.4** | Dogfood audit · ran a full audit of Knit's own codebase using its own `knit_spawn_team_worktree` primitive (4 parallel teams: Core Logic, Infrastructure, UI, Quality Assurance). Fixes: HIGH `engram refresh` no longer clobbers user-curated CLAUDE.md (now uses `spliceKnitBlock` like `cache.ts`); `saveSource`/`loadSource` validate `sourceId`; `appendGlobalLearning` propagates write failures; `redactSecrets` applied to `label`/`tags`/`domains` across all persistence boundaries; 100KB response ceiling on `knit_generate_test_cases`; full v0.11 tool surface now documented in `workflow-protocol.ts` generator (was frozen at the v0.4 surface). Plus: 16 key tools reclassified with `[PROTOCOL]`/`[REVIEW]`/`[MEMORY]`/`[GRAPH]` prefixes so the LLM picks the right tool reliably. 53 tools, 687 tests. |
+| **v0.11.3** | Propagation patch · `update_available` flag now surfaces in `knit_load_session` response (≈100% session reach vs. brain_status' low reach) + startup stderr nag on stale versions. Helps FUTURE upgrades land faster; doesn't retroactively reach v0.10.x users. 53 tools, 665 tests. |
 | **v0.11.2** | Pre-publish polish · chunk cap (2000) + `errorResponse` envelope across handlers + CLAUDE.md generator surfaces v0.11 tools · new `engram doctor` install health-check CLI · upgrade-path smoke test caught + fixed a data-loss bug in cache.ts (Case B was wiping user permissions on upgrade) · 11 real exploit-payload integration tests prove C1/C2/H1 fixes hold · `npm run bench` ships a synthetic retrieval harness (50 Q&A) measuring 86% top-1 / 96% R@5. 53 tools, 664 tests. |
 | **v0.11.1** | Audit-driven hardening · 3 CRITICAL (source_id path traversal, post-edit tsc shell injection, live calibration bug) + 10 HIGH fixes from a 5-agent audit, implemented in 3 parallel `knit_spawn_team_worktree` teams. HOOKS_VERSION 11 (auto-upgrades existing users). New `knit_delete_requirements` tool. Honest comparison vs mem0/Letta added. 53 tools, 636 tests. |
 | **v0.11.0** | Verify Layer + auto-config foundation · mandatory `knit_verify_claim` REVIEW gate · post-edit diff verify + universal `tsc` check · drift detector · self-healing classifier (per-project calibration) · `knit_index_requirements` + `knit_generate_test_cases` (BM25 over long specs) · `knit_get_fingerprint` + `knit_infer_domains` + `knit_compose_template` (zero-config CLAUDE.md). 52 tools, 625 tests. |

package/dist/{cache-3LPETDUT.js → cache-46OKHDRR.js}

@@ -2,15 +2,16 @@ import {
   detectProjectRoot,
   getBrain,
   refreshBrain
-} from "./chunk-TWHNYJAJ.js";
-import "./chunk-HROSQ5MS.js";
-import "./chunk-RZOVZYTF.js";
+} from "./chunk-KKLAJLPO.js";
+import "./chunk-GATMQQK5.js";
+import "./chunk-WADRF26Z.js";
+import "./chunk-WKQHCLLO.js";
 import "./chunk-MOOVNMIN.js";
 import "./chunk-ST4X7LZT.js";
 import "./chunk-M3YZOJNW.js";
+import "./chunk-POXT5OYN.js";
 import "./chunk-VB2TIR6L.js";
 import "./chunk-7UFS67HP.js";
-import "./chunk-WKQHCLLO.js";
 import "./chunk-27TA2ZQZ.js";
 export {
   detectProjectRoot,

package/dist/{chunk-RZOVZYTF.js → chunk-GATMQQK5.js}

@@ -62,7 +62,7 @@ async function fetchAgent(name, opts = {}) {
     throw new AgentFetchError(`Unknown agent: "${name}". Not in engram's registry.`);
   }
   const cachePath = agentsCacheFile(ref, cat, bare);
-  if (existsSync(cachePath)) {
+  if (!opts.refresh && existsSync(cachePath)) {
     return readFileSync(cachePath, "utf-8");
   }
   if (process.env.KNIT_OFFLINE === "1" || process.env.ENGRAM_OFFLINE === "1") {
@@ -250,7 +250,7 @@ async function installAgentsForProject(rootPath, config, knowledge, knowledgeBas
       }
     }
     try {
-      const baseMd = await fetchAgent(name, opts.refresh ? { ref: void 0 } : {});
+      const baseMd = await fetchAgent(name, opts.refresh ? { ref: void 0, refresh: true } : {});
       const relevant = knowledgeBase ? selectRelevantLearnings(knowledgeBase.entries, name) : [];
       const personalized = personalizeAgent(baseMd, {
         config,
@@ -285,55 +285,6 @@ function agentsNeededByProject(config) {
   return Array.from(names);
 }
 
-// src/mcp/update-check.ts
-var REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/knit-mcp/dist-tags";
-var FETCH_TIMEOUT_MS = 2e3;
-var CACHE_TTL_MS = 60 * 60 * 1e3;
-var cachedLatest = null;
-var lastCheckedAt = 0;
-var inFlight = null;
-function getCachedLatestVersion() {
-  if (Date.now() - lastCheckedAt > CACHE_TTL_MS) {
-    prewarmLatestVersion();
-  }
-  return cachedLatest;
-}
-function prewarmLatestVersion() {
-  if (inFlight) return;
-  if (Date.now() - lastCheckedAt < CACHE_TTL_MS && cachedLatest !== null) return;
-  inFlight = doFetch().finally(() => {
-    inFlight = null;
-  });
-}
-async function doFetch() {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  try {
-    const res = await fetch(REGISTRY_DIST_TAGS_URL, { signal: controller.signal });
-    if (!res.ok) return;
-    const data = await res.json();
-    if (typeof data.latest === "string" && data.latest.length > 0) {
-      cachedLatest = data.latest;
-      lastCheckedAt = Date.now();
-    }
-  } catch {
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-function isNewerVersion(latest, current) {
-  const parse = (v) => {
-    const stripped = v.replace(/[-+].*$/, "");
-    const parts = stripped.split(".").map((n) => parseInt(n, 10) || 0);
-    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
-  };
-  const [a1, a2, a3] = parse(latest);
-  const [b1, b2, b3] = parse(current);
-  if (a1 !== b1) return a1 > b1;
-  if (a2 !== b2) return a2 > b2;
-  return a3 > b3;
-}
-
 // src/engine/sessions.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, appendFileSync, readFileSync as readFileSync3, statSync, writeFileSync as writeFileSync3, renameSync } from "fs";
 import { dirname as dirname2 } from "path";
@@ -466,9 +417,6 @@ function parseLine(line) {
 
 export {
   installAgentsForProject,
-  getCachedLatestVersion,
-  prewarmLatestVersion,
-  isNewerVersion,
   appendSession,
   searchSessions,
   getRecentSessions,

package/dist/{chunk-TWHNYJAJ.js → chunk-KKLAJLPO.js}

@@ -1,12 +1,16 @@
+import {
+  installAgentsForProject,
+  pruneSessionsByAge
+} from "./chunk-GATMQQK5.js";
 import {
   HOOKS_VERSION,
   generateSettings
-} from "./chunk-HROSQ5MS.js";
+} from "./chunk-WADRF26Z.js";
 import {
-  installAgentsForProject,
-  prewarmLatestVersion,
-  pruneSessionsByAge
-} from "./chunk-RZOVZYTF.js";
+  importFromMarkdown,
+  loadKnowledgeBaseSafe,
+  saveKnowledgeBase
+} from "./chunk-WKQHCLLO.js";
 import {
   buildKnowledge,
   buildReverseDependencies
@@ -17,6 +21,9 @@ import {
 import {
   readLearnings
 } from "./chunk-M3YZOJNW.js";
+import {
+  prewarmLatestVersion
+} from "./chunk-POXT5OYN.js";
 import {
   persistScanResult,
   scanIntegrations
@@ -26,11 +33,6 @@ import {
   generateClaudeMd,
   spliceKnitBlock
 } from "./chunk-7UFS67HP.js";
-import {
-  importFromMarkdown,
-  loadKnowledgeBaseSafe,
-  saveKnowledgeBase
-} from "./chunk-WKQHCLLO.js";
 import {
   knowledgePath,
   knowledgebasePath,

package/dist/{chunk-ORKWLA33.js → chunk-OINYMLOV.js}

@@ -9,8 +9,16 @@ import { existsSync, mkdirSync, appendFileSync, readFileSync, statSync } from "f
 import { dirname, basename } from "path";
 function appendGlobalLearning(entry) {
   const path = globalLearningsPath();
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+  } catch (err) {
+    process.stderr.write(
+      `[knit] global learning append failed at ${path}: ${err.message}
+`
+    );
+    throw err;
+  }
 }
 function searchGlobalLearnings(query, limit = 10) {
   const lines = readAllLines();

package/dist/chunk-POXT5OYN.js

@@ -0,0 +1,66 @@
+// src/mcp/update-check.ts
+var REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/knit-mcp/dist-tags";
+var FETCH_TIMEOUT_MS = 2e3;
+var CACHE_TTL_MS = 60 * 60 * 1e3;
+var cachedLatest = null;
+var lastCheckedAt = 0;
+var inFlight = null;
+function getCachedLatestVersion() {
+  if (Date.now() - lastCheckedAt > CACHE_TTL_MS) {
+    prewarmLatestVersion();
+  }
+  return cachedLatest;
+}
+function prewarmLatestVersion() {
+  if (inFlight) return;
+  if (Date.now() - lastCheckedAt < CACHE_TTL_MS && cachedLatest !== null) return;
+  inFlight = doFetch().finally(() => {
+    inFlight = null;
+  });
+}
+async function doFetch() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_DIST_TAGS_URL, { signal: controller.signal });
+    if (!res.ok) return;
+    const data = await res.json();
+    if (typeof data.latest === "string" && data.latest.length > 0) {
+      cachedLatest = data.latest;
+      lastCheckedAt = Date.now();
+    }
+  } catch {
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function isNewerVersion(latest, current) {
+  const parse = (v) => {
+    const stripped = v.replace(/[-+].*$/, "");
+    const parts = stripped.split(".").map((n) => parseInt(n, 10) || 0);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+  };
+  const [a1, a2, a3] = parse(latest);
+  const [b1, b2, b3] = parse(current);
+  if (a1 !== b1) return a1 > b1;
+  if (a2 !== b2) return a2 > b2;
+  return a3 > b3;
+}
+function __setCachedLatestForTests(version, checkedAtMs = Date.now()) {
+  cachedLatest = version;
+  lastCheckedAt = checkedAtMs;
+  inFlight = null;
+}
+function __resetUpdateCheckForTests() {
+  cachedLatest = null;
+  lastCheckedAt = 0;
+  inFlight = null;
+}
+
+export {
+  getCachedLatestVersion,
+  prewarmLatestVersion,
+  isNewerVersion,
+  __setCachedLatestForTests,
+  __resetUpdateCheckForTests
+};

package/dist/{chunk-LV73YTVN.js → chunk-QQNHF4XY.js}

@@ -1,4 +1,6 @@
 // src/mcp/instructions.ts
+import { statSync } from "fs";
+import { join } from "path";
 var KNIT_INSTRUCTIONS_BASE = `Knit is a memory + workflow layer for this project. It provides per-project memory across sessions, a knowledge graph (imports/exports/tests), and a tier-routed workflow protocol.
 
 ALWAYS at session start:
@@ -32,8 +34,28 @@ Knit provides inputs; you make the calls. When in doubt, under-classify \u2014 e
 
 Citation rule: when you state a fact about this codebase ("file X imports Y", "function Z is defined in W", "tests for A live in B"), cite the Knit tool result that verified it \u2014 e.g. "(per knit_query_imports)". If you can't cite a tool result, mark the claim as 'unverified' explicitly. This makes hallucinations visible at the claim level instead of letting them ship as confident-sounding prose. The verifier exists; use it.`;
 var KNIT_INSTRUCTIONS = KNIT_INSTRUCTIONS_BASE;
-function buildInstructions(scan) {
-  if (!scan) return KNIT_INSTRUCTIONS_BASE;
+var CLAUDE_MD_BUDGET_BYTES = 6500;
+function buildBudgetVerdict(rootPath) {
+  let bytes = 0;
+  try {
+    bytes = statSync(join(rootPath, "CLAUDE.md")).size;
+  } catch {
+    return "";
+  }
+  if (bytes <= CLAUDE_MD_BUDGET_BYTES) return "";
+  const verdict = bytes > CLAUDE_MD_BUDGET_BYTES * 1.25 ? "over-budget" : "warn";
+  const kb = Math.round(bytes / 1024 * 10) / 10;
+  const targetKb = Math.round(CLAUDE_MD_BUDGET_BYTES / 1024 * 10) / 10;
+  return `BUDGET ${verdict}: CLAUDE.md is ${kb}KB / ${targetKb}KB target. Run \`engram doctor\` to see the full per-surface report and \`engram refresh\` to regenerate the marker block.`;
+}
+function buildInstructions(scan, rootPath) {
+  const budgetLine = rootPath ? buildBudgetVerdict(rootPath) : "";
+  const budgetSuffix = budgetLine ? `
+
+\u2014 Budget check \u2014
+
+${budgetLine}` : "";
+  if (!scan) return KNIT_INSTRUCTIONS_BASE + budgetSuffix;
   const addenda = [];
   if (scan.detected.ruflo.present) {
     addenda.push(
@@ -60,12 +82,14 @@ function buildInstructions(scan) {
       `DETECTED: this project's CLAUDE.md has user-curated workflow sections (${scan.detected.custom_workflow_sections.join("; ")}). Treat that as the canonical workflow doc for project-specific phases; Knit's tier protocol applies underneath as the routing layer.`
     );
   }
-  if (addenda.length === 0) return KNIT_INSTRUCTIONS_BASE;
-  return KNIT_INSTRUCTIONS_BASE + "\n\n\u2014 Per-project integrations \u2014\n\n" + addenda.join("\n\n") + "\n\nGeneral rule: when an integration above provides a higher-level routing primitive (slash command, swarm orchestrator, methodology framework), use it. Knit handles the substrate it doesn't cover: memory, classification, and the workflow protocol for tasks the integration doesn't route.";
+  if (addenda.length === 0) return KNIT_INSTRUCTIONS_BASE + budgetSuffix;
+  return KNIT_INSTRUCTIONS_BASE + "\n\n\u2014 Per-project integrations \u2014\n\n" + addenda.join("\n\n") + "\n\nGeneral rule: when an integration above provides a higher-level routing primitive (slash command, swarm orchestrator, methodology framework), use it. Knit handles the substrate it doesn't cover: memory, classification, and the workflow protocol for tasks the integration doesn't route." + budgetSuffix;
 }
 
 export {
   KNIT_INSTRUCTIONS_BASE,
   KNIT_INSTRUCTIONS,
+  CLAUDE_MD_BUDGET_BYTES,
+  buildBudgetVerdict,
   buildInstructions
 };

package/dist/{doctor-4DN2P2JR.js → chunk-TE6NP6BZ.js}

@@ -1,9 +1,12 @@
+import {
+  HOOKS_VERSION
+} from "./chunk-WADRF26Z.js";
 import {
   VERSION
 } from "./chunk-UTVFELXS.js";
 import {
-  HOOKS_VERSION
-} from "./chunk-HROSQ5MS.js";
+  CLAUDE_MD_BUDGET_BYTES
+} from "./chunk-QQNHF4XY.js";
 import {
   knowledgebasePath,
   projectDataDir
@@ -125,6 +128,45 @@ function runDoctor(rootPath) {
     } catch {
     }
   }
+  const claudeMdPath = join(rootPath, "CLAUDE.md");
+  if (existsSync(claudeMdPath)) {
+    try {
+      const bytes = statSync(claudeMdPath).size;
+      const kb = Math.round(bytes / 1024 * 10) / 10;
+      const targetKb = Math.round(CLAUDE_MD_BUDGET_BYTES / 1024 * 10) / 10;
+      if (bytes <= CLAUDE_MD_BUDGET_BYTES) {
+        checks.push({
+          name: "Token budget",
+          status: "ok",
+          detail: `CLAUDE.md ${kb}KB / ${targetKb}KB target \u2014 healthy`
+        });
+      } else if (bytes <= CLAUDE_MD_BUDGET_BYTES * 1.25) {
+        checks.push({
+          name: "Token budget",
+          status: "warn",
+          detail: `CLAUDE.md ${kb}KB / ${targetKb}KB target \u2014 over budget, within 25% slack. Run \`engram refresh\` or trim the file.`
+        });
+      } else {
+        checks.push({
+          name: "Token budget",
+          status: "error",
+          detail: `CLAUDE.md ${kb}KB / ${targetKb}KB target \u2014 over budget by >25%. Move long-form content to .claude/MARKETING.md or run \`engram refresh\`.`
+        });
+      }
+    } catch (err) {
+      checks.push({
+        name: "Token budget",
+        status: "warn",
+        detail: `CLAUDE.md unreadable: ${err.message}`
+      });
+    }
+  } else {
+    checks.push({
+      name: "Token budget",
+      status: "info",
+      detail: "no CLAUDE.md yet \u2014 created on first MCP call"
+    });
+  }
   const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
   if (Number.isFinite(nodeMajor) && nodeMajor < 18) {
     checks.push({
@@ -173,7 +215,8 @@ async function doctorCommand(directory) {
     console.log(chalk.green("  All checks passed \u2014 install is healthy."));
   }
 }
+
 export {
-  doctorCommand,
-  runDoctor
+  runDoctor,
+  doctorCommand
 };

package/dist/{chunk-HROSQ5MS.js → chunk-WADRF26Z.js}

@@ -15,7 +15,7 @@ import {
 } from "./chunk-27TA2ZQZ.js";
 
 // src/generators/settings.ts
-var HOOKS_VERSION = 11;
+var HOOKS_VERSION = 12;
 function generateSettings(config, rootPath) {
   return {
     mcpServers: {
@@ -288,6 +288,39 @@ function generateHooks(config, rootPath) {
       }
     ]
   });
+  hooks.PostToolUse.push({
+    _knitOwned: true,
+    matcher: "Write|Edit|MultiEdit",
+    hooks: [
+      {
+        type: "command",
+        command: nodeHook(`
+          let d = "";
+          process.stdin.on("data", (c) => d += c);
+          process.stdin.on("end", () => {
+            try {
+              const fs = require("fs");
+              const path = require("path");
+              const i = JSON.parse(d);
+              const ti = i.tool_input || {};
+              const f = ti.file_path || (i.tool_response && i.tool_response.filePath) || "";
+              if (!f) return;
+              if (path.basename(f) !== "CLAUDE.md") return;
+              const TARGET = 6500;
+              const SLACK = 6500 * 1.25;
+              let size = 0;
+              try { size = fs.statSync(f).size; } catch { return; }
+              if (size <= TARGET) return;
+              const kb = Math.round(size/1024*10)/10;
+              const verdict = size > SLACK ? "over-budget" : "warn";
+              process.stderr.write("[knit] BUDGET " + verdict + ": " + f + " is now " + kb + "KB (target 6.5KB). Move long-form content to .claude/MARKETING.md or run \\\`engram refresh\\\`.\\n");
+            } catch (e) { try { process.stderr.write('[knit] claude-md size watch hook failed: ' + (e && e.message ? e.message : e) + '\\n'); } catch {} }
+          });
+        `),
+        timeout: 5
+      }
+    ]
+  });
   hooks.PostToolUse.push({
     _knitOwned: true,
     matcher: "Write|Edit|MultiEdit",

package/dist/cli.js

@@ -19,12 +19,12 @@ if (hasSubcommand) {
 async function runCLI() {
   const gradient = (await import("gradient-string")).default;
   const chalk = (await import("chalk")).default;
-  const { setupCommand } = await import("./setup-5TUUWLIJ.js");
-  const { statusCommand } = await import("./status-VJDB75X2.js");
-  const { refreshCommand } = await import("./refresh-SMJ2NGIW.js");
-  const { installAgentsCommand } = await import("./install-agents-OBDCWCPB.js");
-  const { exportCommand } = await import("./export-CGSEUYZA.js");
-  const { doctorCommand } = await import("./doctor-4DN2P2JR.js");
+  const { setupCommand } = await import("./setup-62ZH7GEI.js");
+  const { statusCommand } = await import("./status-2SEITNIE.js");
+  const { refreshCommand } = await import("./refresh-S62AZ3QA.js");
+  const { installAgentsCommand } = await import("./install-agents-AH7EBB4J.js");
+  const { exportCommand } = await import("./export-4BO6HCXP.js");
+  const { doctorCommand } = await import("./doctor-NI22FPXV.js");
   const ENGRAM_GRADIENT = gradient(["#7c3aed", "#2563eb", "#06b6d4"]);
   const banner = `
   \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
@@ -98,13 +98,24 @@ async function runMCP() {
   const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
   const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
   const { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
-  const { getBrain, detectProjectRoot, refreshBrain } = await import("./cache-3LPETDUT.js");
-  const { getActiveToolDefinitionsForBrain, handleToolCall } = await import("./tools-MIROTK2A.js");
-  const { buildInstructions } = await import("./instructions-JARSXQPO.js");
+  const { getBrain, detectProjectRoot, refreshBrain } = await import("./cache-46OKHDRR.js");
+  const { getActiveToolDefinitionsForBrain, handleToolCall } = await import("./tools-ZQHRWMVK.js");
+  const { buildInstructions } = await import("./instructions-CF6K57Z2.js");
   const { registerToolsListChangedNotifier } = await import("./notifier-4L27HKHI.js");
   const { loadScanResult } = await import("./integration-scanner-LBD2PIZ3.js");
+  const { prewarmLatestVersion, getCachedLatestVersion, isNewerVersion } = await import("./update-check-GQVDVT2N.js");
   const ROOT_PATH = detectProjectRoot();
   const PER_PROJECT_INSTRUCTIONS = buildInstructions(loadScanResult(ROOT_PATH));
+  prewarmLatestVersion();
+  setTimeout(() => {
+    const latest = getCachedLatestVersion();
+    if (latest && isNewerVersion(latest, VERSION)) {
+      process.stderr.write(
+        `[knit] update available: v${VERSION} installed, v${latest} on npm \u2014 restart Claude Code to upgrade (clear npx cache if needed: \`rm -rf ~/.npm/_npx/\`). Changelog: https://github.com/PDgit12/knit/blob/main/CHANGELOG.md
+`
+      );
+    }
+  }, 250);
   const server = new Server(
     { name: "knit-brain", version: VERSION },
     {

package/dist/doctor-NI22FPXV.js

@@ -0,0 +1,12 @@
+import {
+  doctorCommand,
+  runDoctor
+} from "./chunk-TE6NP6BZ.js";
+import "./chunk-WADRF26Z.js";
+import "./chunk-UTVFELXS.js";
+import "./chunk-QQNHF4XY.js";
+import "./chunk-27TA2ZQZ.js";
+export {
+  doctorCommand,
+  runDoctor
+};

package/dist/{export-CGSEUYZA.js → export-4BO6HCXP.js}

@@ -1,6 +1,6 @@
 import {
   getRecentGlobalLearnings
-} from "./chunk-ORKWLA33.js";
+} from "./chunk-OINYMLOV.js";
 import {
   loadKnowledgeBase
 } from "./chunk-WKQHCLLO.js";

package/dist/{install-agents-OBDCWCPB.js → install-agents-AH7EBB4J.js}

@@ -1,16 +1,17 @@
 import {
   getBrain
-} from "./chunk-TWHNYJAJ.js";
-import "./chunk-HROSQ5MS.js";
+} from "./chunk-KKLAJLPO.js";
 import {
   installAgentsForProject
-} from "./chunk-RZOVZYTF.js";
+} from "./chunk-GATMQQK5.js";
+import "./chunk-WADRF26Z.js";
+import "./chunk-WKQHCLLO.js";
 import "./chunk-MOOVNMIN.js";
 import "./chunk-ST4X7LZT.js";
 import "./chunk-M3YZOJNW.js";
+import "./chunk-POXT5OYN.js";
 import "./chunk-VB2TIR6L.js";
 import "./chunk-7UFS67HP.js";
-import "./chunk-WKQHCLLO.js";
 import "./chunk-27TA2ZQZ.js";
 
 // src/commands/install-agents.ts

package/dist/{instructions-JARSXQPO.js → instructions-CF6K57Z2.js}

@@ -1,10 +1,14 @@
 import {
+  CLAUDE_MD_BUDGET_BYTES,
   KNIT_INSTRUCTIONS,
   KNIT_INSTRUCTIONS_BASE,
+  buildBudgetVerdict,
   buildInstructions
-} from "./chunk-LV73YTVN.js";
+} from "./chunk-QQNHF4XY.js";
 export {
+  CLAUDE_MD_BUDGET_BYTES,
   KNIT_INSTRUCTIONS,
   KNIT_INSTRUCTIONS_BASE,
+  buildBudgetVerdict,
   buildInstructions
 };

package/dist/{refresh-SMJ2NGIW.js → refresh-S62AZ3QA.js}

@@ -8,7 +8,9 @@ import {
   findFalsePositives
 } from "./chunk-M3YZOJNW.js";
 import {
-  generateClaudeMd
+  KNIT_MARKER_START,
+  generateClaudeMd,
+  spliceKnitBlock
 } from "./chunk-7UFS67HP.js";
 import {
   knowledgePath,
@@ -57,9 +59,19 @@ async function refreshCommand(targetDir) {
     tokenOptimization: "standard"
   };
   const genSpinner = ora({ text: chalk.dim("Regenerating CLAUDE.md..."), spinner: "dots" }).start();
-  writeFileSync(join(rootPath, "CLAUDE.md"), generateClaudeMd(config, knowledge, falsePositives), "utf-8");
+  const claudeMdPath = join(rootPath, "CLAUDE.md");
+  const newBlock = generateClaudeMd(config, knowledge, falsePositives);
+  const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, "utf-8") : "";
+  if (existing && existing.includes(KNIT_MARKER_START)) {
+    const { content } = spliceKnitBlock(existing, newBlock);
+    writeFileSync(claudeMdPath, content, "utf-8");
+  } else if (!existing) {
+    writeFileSync(claudeMdPath, newBlock, "utf-8");
+  } else {
+    genSpinner.warn(chalk.yellow("CLAUDE.md is user-curated (no Knit markers). Skipping write to avoid clobber."));
+  }
   writeFileSync(knowledgePath(rootPath), JSON.stringify(knowledge, null, 2), "utf-8");
-  genSpinner.succeed(chalk.dim("CLAUDE.md + knowledge.json updated"));
+  if (genSpinner.isSpinning) genSpinner.succeed(chalk.dim("CLAUDE.md + knowledge.json updated"));
   console.log();
   console.log(chalk.bold("  Refresh complete"));
   if (falsePositives.length > 0) {

package/dist/{setup-5TUUWLIJ.js → setup-62ZH7GEI.js}

@@ -1,3 +1,11 @@
+import {
+  runDoctor
+} from "./chunk-TE6NP6BZ.js";
+import "./chunk-WADRF26Z.js";
+import "./chunk-UTVFELXS.js";
+import "./chunk-QQNHF4XY.js";
+import "./chunk-27TA2ZQZ.js";
+
 // src/commands/setup.ts
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
@@ -89,7 +97,7 @@ For new projects, call \`knit_brain_status\` first \u2014 triggers auto-initiali
   console.log(chalk.bold("  How it works"));
   console.log(`  ${chalk.cyan("1.")} Open ${chalk.bold("any project")} in Claude Code`);
   console.log(`  ${chalk.cyan("2.")} Agent calls \`knit_classify_task\` \u2192 brain auto-initializes`);
-  console.log(`  ${chalk.cyan("3.")} Agent gets 35 tools: imports, exports, tests, learnings, teams`);
+  console.log(`  ${chalk.cyan("3.")} Agent gets 53+ tools: imports, exports, tests, learnings, teams, requirements`);
   console.log(`  ${chalk.cyan("4.")} Brain compounds with every session \u2014 gets smarter over time`);
   console.log();
   console.log(chalk.dim("  No CLI needed after this. The MCP server handles everything."));
@@ -98,6 +106,28 @@ For new projects, call \`knit_brain_status\` first \u2014 triggers auto-initiali
     console.log(chalk.dim(`  Config written to: ${settingsPath}`));
   }
   console.log();
+  console.log(chalk.bold("  Install health check"));
+  console.log();
+  try {
+    const report = runDoctor(process.cwd());
+    for (const c of report.checks) {
+      const icon = c.status === "ok" ? chalk.green("\u2713") : c.status === "warn" ? chalk.yellow("\u26A0") : c.status === "error" ? chalk.red("\u2717") : chalk.gray("\xB7");
+      console.log(`  ${icon} ${c.name.padEnd(22)} ${chalk.dim(c.detail)}`);
+    }
+    const errors = report.checks.filter((c) => c.status === "error").length;
+    const warnings = report.checks.filter((c) => c.status === "warn").length;
+    console.log();
+    if (errors > 0) {
+      console.log(chalk.red(`  ${errors} error(s) \u2014 run \`engram doctor\` for full details + fix commands.`));
+    } else if (warnings > 0) {
+      console.log(chalk.yellow(`  ${warnings} warning(s) \u2014 setup complete, but check items above.`));
+    } else {
+      console.log(chalk.green("  All checks passed \u2014 install is healthy."));
+    }
+  } catch (err) {
+    console.log(chalk.dim(`  (doctor skipped: ${err.message})`));
+  }
+  console.log();
 }
 export {
   setupCommand

package/dist/{tools-MIROTK2A.js → tools-ZQHRWMVK.js}

@@ -1,40 +1,28 @@
-import {
-  notifyToolsListChanged
-} from "./chunk-WMESQUZU.js";
-import {
-  KNIT_INSTRUCTIONS
-} from "./chunk-LV73YTVN.js";
-import {
-  VERSION
-} from "./chunk-UTVFELXS.js";
 import {
   appendSession,
-  getCachedLatestVersion,
   getRecentSessions,
   installAgentsForProject,
-  isNewerVersion,
   loadAllSessions,
   pruneSessionsByAge,
   searchSessions,
   sessionCount
-} from "./chunk-RZOVZYTF.js";
-import {
-  scanProject,
-  scanProjectFingerprint
-} from "./chunk-ST4X7LZT.js";
-import {
-  loadScanResult,
-  persistScanResult,
-  scanIntegrations
-} from "./chunk-VB2TIR6L.js";
-import "./chunk-7UFS67HP.js";
+} from "./chunk-GATMQQK5.js";
 import {
   appendGlobalLearning,
   buildGlobalLearning,
   getRecentGlobalLearnings,
   loadAllGlobalLearnings,
   searchGlobalLearnings
-} from "./chunk-ORKWLA33.js";
+} from "./chunk-OINYMLOV.js";
+import {
+  notifyToolsListChanged
+} from "./chunk-WMESQUZU.js";
+import {
+  VERSION
+} from "./chunk-UTVFELXS.js";
+import {
+  KNIT_INSTRUCTIONS
+} from "./chunk-QQNHF4XY.js";
 import {
   addEntry,
   bumpClassificationTier,
@@ -45,6 +33,20 @@ import {
   recordCacheHit,
   saveKnowledgeBase
 } from "./chunk-WKQHCLLO.js";
+import {
+  scanProject,
+  scanProjectFingerprint
+} from "./chunk-ST4X7LZT.js";
+import {
+  getCachedLatestVersion,
+  isNewerVersion
+} from "./chunk-POXT5OYN.js";
+import {
+  loadScanResult,
+  persistScanResult,
+  scanIntegrations
+} from "./chunk-VB2TIR6L.js";
+import "./chunk-7UFS67HP.js";
 import {
   calibrationPath,
   canonicalRepoRoot,
@@ -395,7 +397,48 @@ function tools(_) {
 | \`knit_define_team\` | Create a custom team. |
 | \`knit_start_team_review\` | Start a parallel review board. |
 | \`knit_post_team_findings\` | Each team posts to the shared board. |
-| \`knit_get_board_summary\` | Cross-team findings, severity-gated. |`;
+| \`knit_get_board_summary\` | Cross-team findings, severity-gated. |
+| \`knit_spawn_team_worktree\` | Spawn a git worktree for a team to do isolated parallel writes. |
+| \`knit_list_team_worktrees\` | List active team worktrees. |
+| \`knit_finalize_team_worktree\` | Merge or discard a team worktree branch. |
+
+**Cross-project memory** (v0.4+):
+| Tool | Use when |
+|------|----------|
+| \`knit_record_global_learning\` | Cross-project insight (applies beyond current repo). |
+| \`knit_search_global_learnings\` | Search learnings across all your projects. |
+| \`knit_reflect\` | Surface candidate patterns from session history. |
+| \`knit_get_suggestions\` | Adaptive warnings derived from past patterns for given domains. |
+| \`knit_install_agent\` | Fetch a specialized VoltAgent on demand. |
+| \`knit_prune_sessions\` | Garbage-collect old session log entries. |
+| \`knit_consolidate_learnings\` | Promote stable patterns to consolidated tier. |
+| \`knit_get_learning\` | Fetch a single learning by id. |
+
+**Feature gating + protocol guard** (v0.5+):
+| Tool | Use when |
+|------|----------|
+| \`knit_list_features\` | See which tools are hidden behind tier gates and how to enable them. |
+| \`knit_enable_feature\` / \`knit_disable_feature\` | Toggle a feature on/off for this project. |
+| \`knit_set_protocol_strictness\` / \`knit_get_protocol_strictness\` | off / warn / block \u2014 controls Protocol Guard hook. |
+| \`knit_scan_integrations\` | Detect external integrations the project uses. |
+| \`knit_compounding_metrics\` | Per-session token + hit-rate metrics. |
+| \`knit_get_metrics_history\` | History of compounding metrics for trend lines. |
+| \`knit_verify_claim\` | Cheap fact-check against the knowledge graph before quoting code. |
+
+**Self-healing classifier** (v0.11):
+| Tool | Use when |
+|------|----------|
+| \`knit_get_calibration\` / \`knit_reset_calibration\` | Inspect or reset per-project classifier tuning. |
+| \`knit_get_fingerprint\` | Project fingerprint used for shape-aware tier gating. |
+| \`knit_infer_domains\` | Auto-derive domain tags from files. |
+| \`knit_compose_template\` | Compose a generated artifact from a template. |
+
+**Requirements ingestion** (v0.11):
+| Tool | Use when |
+|------|----------|
+| \`knit_index_requirements\` | Chunk + BM25-index a long spec for retrieval. |
+| \`knit_generate_test_cases\` | Retrieve relevant chunks for a feature query (token-bounded). |
+| \`knit_list_requirements\` / \`knit_delete_requirements\` | Manage indexed sources. |`;
 }
 
 // src/engine/worktrees.ts
@@ -639,7 +682,6 @@ function classifyOrigin(supporting) {
     else global = true;
     if (local && global) return "mixed";
   }
-  if (local && global) return "mixed";
   return local ? "local" : "global";
 }
 function getAdaptiveSuggestions(kb, taskDomains) {
@@ -1487,6 +1529,9 @@ function chunkRequirements(content, minChars = 50) {
   return chunks;
 }
 function saveSource(rootPath, source) {
+  if (typeof source.sourceId !== "string" || !/^[A-Za-z0-9._-]{1,80}$/.test(source.sourceId)) {
+    throw new Error(`[knit] saveSource: invalid sourceId "${source.sourceId}"`);
+  }
   const path = requirementSourcePath(rootPath, source.sourceId);
   mkdirSync5(dirname5(path), { recursive: true });
   const tmp = `${path}.tmp`;
@@ -1494,6 +1539,7 @@ function saveSource(rootPath, source) {
   renameSync3(tmp, path);
 }
 function loadSource(rootPath, sourceId) {
+  if (typeof sourceId !== "string" || !/^[A-Za-z0-9._-]{1,80}$/.test(sourceId)) return null;
   const path = requirementSourcePath(rootPath, sourceId);
   if (!existsSync5(path)) return null;
   try {
@@ -1883,8 +1929,8 @@ function handleSearchLearnings(params, brain) {
   const limit = Math.max(1, Math.min(50, parseInt(params.limit || "10", 10) || 10));
   if (!query && domains.length === 0) {
     return JSON.stringify({
+      status: "error",
       error: "Provide either query (BM25 free-text) or domains (tag filter), or both. query=auth domains=#api filters BM25 results to entries tagged #api.",
-      query: [],
       results: [],
       count: 0
     });
@@ -1966,20 +2012,23 @@ var TOKEN_BUDGETS = {
   /** Generated CLAUDE.md block. v0.7 trim landed at ~2KB on typical projects;
    *  6.5KB target allows for projects with many domains / large project map. */
   claude_md_bytes: 6500,
-  /** Tier-gated tools/list response. v0.12 typical: 38 Tier-1 active × ~280
-   *  bytes ≈ 10.6KB. 11KB target allows headroom for the v0.12 + v0.13
-   *  growth without immediately warning; full 51-tool exposure
-   *  (everything enabled) sits in warn range, surfacing the bloat. */
-  tool_registry_bytes: 11e3,
+  /** Tier-gated tools/list response. v0.12 typical: 40 Tier-1 active × ~280
+   *  bytes ≈ 11.2KB. 12KB target gives Tier-1 healthy headroom; full
+   *  51-tool exposure (everything enabled) sits in warn range, surfacing
+   *  the bloat. Bumped from 11000 in v0.12 to reflect actual Tier-1 size. */
+  tool_registry_bytes: 12e3,
   /** MCP server `instructions` field — sent at handshake. v0.11.1 surfaces
    *  9 new tools (verify_claim, calibration, requirements ingestion,
-   *  fingerprint, infer_domains, compose_template) → ~3.5KB. The
-   *  discoverability-vs-budget trade-off favors surfacing real tools. */
+   *  fingerprint, infer_domains, compose_template) → ~3.5KB. v0.12 may
+   *  append a one-line budget verdict (~200B) when CLAUDE.md is over
+   *  budget. The discoverability-vs-budget trade-off favors surfacing
+   *  real tools. */
   instructions_bytes: 4e3,
   /** Sum of the three above — the per-session fixed cost Knit imposes.
-   *  v0.12 typical: ~14KB (CLAUDE.md ~2KB + tools ~10.6KB + instructions ~2KB);
-   *  20KB target covers the union with slack as more tools come online. */
-  per_session_overhead_bytes: 2e4
+   *  v0.12 typical: ~15KB (CLAUDE.md ~2KB + tools ~11.2KB + instructions
+   *  ~2.6KB); 22KB target covers the union with slack as more tools
+   *  come online. Bumped from 20000 alongside tool_registry. */
+  per_session_overhead_bytes: 22e3
 };
 function verdict(actual, target) {
   if (actual <= target) return "healthy";
@@ -2889,9 +2938,7 @@ function handleGetLearning(params, brain) {
   if (!id) return errorResponse("id parameter is required");
   const entry = brain.knowledgeBase.entries.find((e) => e.id === id);
   if (!entry) {
-    return JSON.stringify({
-      error: `No learning with id="${id}". List active ones via knit_search_learnings (default returns id + summary).`
-    });
+    return errorResponse(`No learning with id="${id}". List active ones via knit_search_learnings (default returns id + summary).`);
   }
   recordCacheHit(brain.knowledgeBase);
   return JSON.stringify({
@@ -2914,11 +2961,11 @@ function handleRecordLearning(params, brain) {
   const entry = {
     date,
     summary: redactSecrets(params.summary || "Untitled learning"),
-    domains: (params.domains || "general").split(",").map((d) => d.trim()),
+    domains: (params.domains || "general").split(",").map((d) => redactSecrets(d.trim())),
     approach: redactSecrets(params.approach || ""),
     outcome: ["success", "partial", "failure"].includes(params.outcome) ? params.outcome : "success",
     lesson: redactSecrets(params.lesson || ""),
-    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#"))
+    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")).map((t) => redactSecrets(t))
   };
   addEntry(brain.knowledgeBase, entry);
   saveKnowledgeBase(knowledgebasePath(brain.rootPath), brain.knowledgeBase);
@@ -2946,7 +2993,7 @@ function handleRecordLearning(params, brain) {
 }
 function handleRecordFalsePositive(params, brain) {
   const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const tags = [...(params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")), "#false-positive"];
+  const tags = [...(params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")).map((t) => redactSecrets(t)), "#false-positive"];
   const entry = {
     date,
     summary: redactSecrets(params.summary || "Untitled FP"),
@@ -3085,7 +3132,8 @@ function handleIndexRequirements(params, brain) {
     return JSON.stringify({ status: "error", error: "Invalid source_id \u2014 must be 1-80 chars, alphanumeric + . _ - only" });
   }
   const sourceId = userSourceId || slugifySourceId(filePath);
-  const label = (params.label || "").trim() || void 0;
+  const rawLabel = (params.label || "").trim();
+  const label = rawLabel ? redactSecrets(rawLabel) : void 0;
   const source = {
     sourceId,
     sourcePath: filePath,
@@ -3142,8 +3190,13 @@ function handleGenerateTestCases(params, brain) {
       if (s) sourcesToSearch.push(s);
     }
   }
+  const MAX_RESPONSE_BYTES = 100 * 1024;
   const hits = retrieveTopChunks(sourcesToSearch, feature, topN);
-  const contextBytes = hits.reduce((s, h) => s + Buffer.byteLength(h.chunk.text, "utf-8"), 0);
+  let contextBytes = hits.reduce((s, h) => s + Buffer.byteLength(h.chunk.text, "utf-8"), 0);
+  while (contextBytes > MAX_RESPONSE_BYTES && hits.length > 1) {
+    const dropped = hits.pop();
+    contextBytes -= Buffer.byteLength(dropped.chunk.text, "utf-8");
+  }
   const totalBytes = sourcesToSearch.reduce((s, src) => s + src.sourceBytes, 0);
   const reductionPct = totalBytes > 0 ? Math.round(100 - contextBytes / totalBytes * 100) : 0;
   return JSON.stringify({
@@ -3510,6 +3563,57 @@ function parseLoadSessionInclude(raw) {
     raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
   );
 }
+function computeBudgetHealth(brain) {
+  let claudeMdBytes = 0;
+  try {
+    claudeMdBytes = statSync3(join3(brain.rootPath, "CLAUDE.md")).size;
+  } catch {
+  }
+  const shape = detectProjectShape(brain);
+  const listing = computeFeatureListing(shape);
+  const toolRegistryBytes = listing.totals.active * 280;
+  const instructionsBytes = KNIT_INSTRUCTIONS.length;
+  const perSessionOverheadBytes = claudeMdBytes + toolRegistryBytes + instructionsBytes;
+  const cv = verdict(claudeMdBytes, TOKEN_BUDGETS.claude_md_bytes);
+  const tv = verdict(toolRegistryBytes, TOKEN_BUDGETS.tool_registry_bytes);
+  const iv = verdict(instructionsBytes, TOKEN_BUDGETS.instructions_bytes);
+  const ov = verdict(perSessionOverheadBytes, TOKEN_BUDGETS.per_session_overhead_bytes);
+  const verdicts = [cv, tv, iv, ov];
+  const overall = verdicts.includes("over-budget") ? "over-budget" : verdicts.includes("warn") ? "warn" : "healthy";
+  if (overall === "healthy") return void 0;
+  const rank = (v) => v === "over-budget" ? 2 : v === "warn" ? 1 : 0;
+  const surfaces = [
+    ["claude_md", cv],
+    ["tool_registry", tv],
+    ["instructions", iv]
+  ];
+  surfaces.sort((a, b) => rank(b[1]) - rank(a[1]));
+  const worst = surfaces[0][0];
+  const suggestions = {
+    claude_md: "CLAUDE.md is over the 6.5KB target \u2014 run `engram refresh` to splice the lean marker-block, or check that the file is using the generator (not hand-curated).",
+    tool_registry: "Tool registry over budget \u2014 call knit_list_features to see which Tier-2/3 tools are active and disable any you do not need.",
+    instructions: "Instructions block over budget \u2014 likely a v0.x \u2192 v0.y growth. Restart Claude Code to pick up the trimmed instructions."
+  };
+  return {
+    verdict: overall,
+    per_session_kb: Math.round(perSessionOverheadBytes / 1024 * 10) / 10,
+    worst_surface: worst,
+    suggestion: suggestions[worst]
+  };
+}
+function computeLearningsHealth(brain) {
+  const total = brain.knowledgeBase.entries.length;
+  if (total < 5) return void 0;
+  const accessed = brain.knowledgeBase.entries.filter((e) => e.accessCount > 0).length;
+  const pct = total > 0 ? Math.round(accessed / total * 100) : 0;
+  if (pct >= 30) return { total, accessed_pct: pct, verdict: "healthy" };
+  return {
+    total,
+    accessed_pct: pct,
+    verdict: "low-utilization",
+    suggestion: `${total} learnings recorded but only ${pct}% have been recalled. Either call knit_search_learnings before re-investigating, or prune stale entries with knit_consolidate_learnings.`
+  };
+}
 function handleLoadSession(params, brain) {
   const include = parseLoadSessionInclude(params.include);
   const wantAll = include.has("all");
@@ -3581,6 +3685,18 @@ function handleLoadSession(params, brain) {
   if (wantAll || include.has("patterns")) {
     patterns = reflect(brain.knowledgeBase).slice(0, 3).map((p) => ({ type: p.type, description: p.description, confidence: p.confidence }));
   }
+  let updateAvailable;
+  const cachedLatest = getCachedLatestVersion();
+  if (cachedLatest && isNewerVersion(cachedLatest, VERSION)) {
+    updateAvailable = {
+      current: VERSION,
+      latest: cachedLatest,
+      upgrade: "Restart Claude Code (quit fully + reopen) to spawn a fresh MCP. If npx serves cache, run: rm -rf ~/.npm/_npx/$(ls ~/.npm/_npx | head -1) then reopen.",
+      changelog: "https://github.com/PDgit12/knit/blob/main/CHANGELOG.md"
+    };
+  }
+  const budgetHealth = computeBudgetHealth(brain);
+  const learningsHealth = computeLearningsHealth(brain);
   const response = {
     session_context: {
       last_session: lastSession,
@@ -3598,6 +3714,9 @@ function handleLoadSession(params, brain) {
       ...metrics !== void 0 ? { metrics } : {},
       ...recentSessions !== void 0 ? { recent_sessions: recentSessions } : {}
     },
+    ...updateAvailable ? { update_available: updateAvailable } : {},
+    ...budgetHealth ? { budget_health: budgetHealth } : {},
+    ...learningsHealth && learningsHealth.verdict === "low-utilization" ? { learnings_health: learningsHealth } : {},
     instruction: handoff2 ? "UNFINISHED WORK DETECTED. Read the handoff above \u2014 pick up where the last session left off. Do NOT start fresh." : topLearnings.length > 0 ? `Session loaded. ${topLearnings.length} key learnings, ${fps.length} false positives. Call knit_classify_task to begin. Use include=patterns,teams,metrics,recent_sessions,full_learnings,full_knowledge for more.` : "Fresh brain \u2014 no past learnings yet. Call knit_classify_task to begin."
   };
   return JSON.stringify(response);
@@ -3611,7 +3730,7 @@ function handleSaveSessionSummary(params, brain) {
     date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     summary: redactSecrets((params.summary || "").slice(0, 500)),
-    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")),
+    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")).map((t) => redactSecrets(t)),
     outcome,
     filesTouched: params.files_touched ? params.files_touched.split(",").map((f) => f.trim()).filter(Boolean) : void 0,
     domainsTouched: params.domains ? params.domains.split(",").map((d) => d.trim()).filter(Boolean) : void 0
@@ -3813,32 +3932,32 @@ function getToolDefinitions() {
     // ── Query (read the brain) ───────────────────────────────────
     {
       name: "knit_query_imports",
-      description: "Reverse deps for a file \u2014 who imports it.",
+      description: "[GRAPH] Reverse deps \u2014 WHO IMPORTS this file. Use to find blast radius before editing.",
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path." } }, required: ["file_path"] }
     },
     {
       name: "knit_query_dependents",
-      description: "Forward deps for a file \u2014 what it imports.",
+      description: "[GRAPH] Forward deps \u2014 WHAT THIS FILE IMPORTS. Opposite of knit_query_imports (who imports it).",
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path." } }, required: ["file_path"] }
     },
     {
       name: "knit_query_exports",
-      description: "Exports from a file: functions, classes, types, constants.",
+      description: "[GRAPH] Exports from a file: functions, classes, types, constants. Use when verifying a claim or finding the canonical definition.",
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path." } }, required: ["file_path"] }
     },
     {
       name: "knit_query_tests",
-      description: 'Tests for a file, or list all untested files with filter="untested".',
+      description: '[GRAPH] Tests covering a file, OR list all untested files with filter="untested". Use before declaring "tested" on changed code.',
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path (optional)." }, filter: { type: "string", description: '"untested" to list all untested files.' } } }
     },
     {
       name: "knit_find_fanout",
-      description: "High-fanout files \u2014 imported by many others.",
+      description: "[GRAPH] High-fanout files \u2014 imported by many others. Editing these is high-risk; surfaces in classify_task risk_tier.",
       inputSchema: { type: "object", properties: { min_importers: { type: "string", description: "Minimum importers to qualify (default: 3)." } } }
     },
     {
       name: "knit_search_learnings",
-      description: 'BM25 + import-graph hybrid. Pass query="text" for BM25, domains="#tag" filter, files="src/a.ts,src/b.ts" for graph boost on learnings about neighbors. All combinable.',
+      description: "[MEMORY] Search THIS PROJECT's learnings. Use BEFORE re-investigating. Companions: knit_search_global_learnings (cross-project), knit_search_sessions (past tasks). BM25 + graph boost via files=.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3862,7 +3981,7 @@ function getToolDefinitions() {
     // ── Update (write to the brain) ──────────────────────────────
     {
       name: "knit_classify_task",
-      description: "Call first. Returns risk_tier (drives plan mode), scope_tier (drives phases), change_kind, phases, auto_plan_mode, tier. Optional context_budget_remaining (0-100) downgrades gracefully.",
+      description: "[PROTOCOL] BEFORE any Edit/Write. Returns risk_tier (drives plan mode), scope_tier (drives phases), change_kind, auto_plan_mode. Optional context_budget_remaining (0-100) downgrades gracefully.",
       inputSchema: { type: "object", properties: { files_to_touch: { type: "string", description: 'Comma-separated files, or "unknown" for new projects.' }, description: { type: "string", description: "Brief task description." }, verbose: { type: "string", description: '"true" to include reasoning + cross_domain_ripple + files_count (debug fields).' }, context_budget_remaining: { type: "string", description: "Integer 0\u2013100 \u2014 percent of host agent context window remaining. <30 triggers scope downgrade + skips OPTIMIZE phase. Defaults to 100." } }, required: ["files_to_touch"] }
     },
     {
@@ -3872,7 +3991,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_record_learning",
-      description: "Record a non-obvious, reusable insight. Skip if a future search wouldn't be glad it exists.",
+      description: "[MEMORY-WRITE] Record a non-obvious THIS-PROJECT insight. Skip substring repeats. For cross-project: knit_record_global_learning. For FPs: knit_record_false_positive.",
       inputSchema: { type: "object", properties: { summary: { type: "string", description: "One-line summary." }, domains: { type: "string", description: "Comma-separated domains." }, approach: { type: "string", description: "What approach was taken." }, outcome: { type: "string", description: "success | partial | failure." }, lesson: { type: "string", description: "What to repeat or avoid." }, tags: { type: "string", description: 'Space-separated tags (e.g. "#api #auth").' } }, required: ["summary", "lesson", "tags"] }
     },
     {
@@ -3927,7 +4046,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_save_handoff",
-      description: "Save state for the next session. failed_attempts is the load-bearing field.",
+      description: "[END OF SESSION \u2014 UNFINISHED] Save state when work is incomplete or context degraded. failed_attempts is the load-bearing field. For finished work use knit_save_session_summary.",
       inputSchema: { type: "object", properties: { goal: { type: "string", description: "What we're trying to accomplish." }, current_state: { type: "string", description: "Where we are now." }, files_in_flight: { type: "string", description: "Files being modified." }, what_changed: { type: "string", description: "Commits and edits." }, failed_attempts: { type: "string", description: "What was tried and why it failed." }, decisions_made: { type: "string", description: "Important choices." }, next_step: { type: "string", description: "ONE most important next thing." } }, required: ["goal", "current_state", "failed_attempts", "next_step"] }
     },
     {
@@ -3978,12 +4097,12 @@ function getToolDefinitions() {
     // ── Session memory ───────────────────────────────────────────
     {
       name: "knit_load_session",
-      description: "Call at session start. Returns handoff, top learnings, false positives by default. Opt in to more via include=patterns,teams,metrics,recent_sessions,full_learnings,full_knowledge,all.",
+      description: "[PROTOCOL FIRST] Call once at session start. Returns handoff, top learnings, FPs, update_available. Opt in via include=patterns,teams,metrics,recent_sessions,full_learnings,all.",
       inputSchema: { type: "object", properties: { include: { type: "string", description: "Comma-separated optional sections." } } }
     },
     {
       name: "knit_save_session_summary",
-      description: "Opt-in. Record a session summary a future search would want to find.",
+      description: "[END OF SESSION] Record a session summary so future knit_search_sessions can find this work. Pair with knit_save_handoff when work is unfinished.",
       inputSchema: {
         type: "object",
         properties: {
@@ -4008,7 +4127,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_search_sessions",
-      description: 'Search past sessions by free text. "Have I done this before?"',
+      description: '[MEMORY] "Have I done this task before?" \u2014 search past SESSION summaries. Different from knit_search_learnings (lessons) and knit_search_global_learnings (cross-project).',
       inputSchema: {
         type: "object",
         properties: {
@@ -4055,7 +4174,7 @@ function getToolDefinitions() {
     // ── Cross-project learnings (Model C — global pool) ─────────
     {
       name: "knit_record_global_learning",
-      description: "Opt-in. Record a learning to the cross-project pool when it generalizes beyond this project.",
+      description: "[MEMORY-WRITE] Record a learning that generalizes across MULTIPLE projects. Sparingly \u2014 most learnings are project-specific. Companion: knit_record_learning (this project only).",
       inputSchema: {
         type: "object",
         properties: {
@@ -4069,7 +4188,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_search_global_learnings",
-      description: "Search the cross-project learnings pool across all projects on this machine.",
+      description: "[MEMORY] Search learnings ACROSS ALL projects on this machine. Use when starting a new domain. Companion: knit_search_learnings (this project only).",
       inputSchema: {
         type: "object",
         properties: {
@@ -4166,12 +4285,12 @@ function getToolDefinitions() {
     },
     {
       name: "knit_verify_claim",
-      description: 'Fact-check one claim against the knowledge graph. Patterns: "A imports B", "X exports Y", "A is tested by B", "X exists". Verdict: verified | contradicted | unparseable.',
+      description: '[REVIEW] Fact-check one claim before LEARN on standard/complex scope. Patterns: "A imports B", "X exports Y", "A is tested by B", "X exists". Verdict: verified | contradicted | unparseable.',
       inputSchema: { type: "object", properties: { claim: { type: "string", description: "One claim about the codebase to verify." } }, required: ["claim"] }
     },
     {
       name: "knit_get_learning",
-      description: "Fetch one full learning by id. Pair with knit_search_learnings (default returns headlines) for hierarchical retrieval \u2014 expand only what you need.",
+      description: "[MEMORY] Expand ONE learning by id (from a prior knit_search_learnings hit). Hierarchical retrieval \u2014 search returns headlines, this fetches details. Saves tokens vs. dumping full bodies.",
       inputSchema: { type: "object", properties: { id: { type: "string", description: "Learning id from a prior knit_search_learnings result." } }, required: ["id"] }
     },
     {
@@ -4260,7 +4379,7 @@ function handleToolCall(toolName, params, brain) {
     const allowAbsolute = toolName === "knit_index_requirements";
     const bad = decoded.includes("..") || decoded.includes("\0") || !allowAbsolute && (decoded.startsWith("/") || /^[A-Za-z]:\//.test(decoded));
     if (bad) {
-      return JSON.stringify({ error: "Invalid file path \u2014 no traversal or absolute paths allowed" });
+      return JSON.stringify({ status: "error", error: "Invalid file path \u2014 no traversal or absolute paths allowed" });
     }
     params.file_path = decoded;
   }
@@ -4271,7 +4390,7 @@ function handleToolCall(toolName, params, brain) {
   }
   const handler = handlers[toolName];
   if (!handler) {
-    return JSON.stringify({ error: `Unknown tool: ${toolName}` });
+    return JSON.stringify({ status: "error", error: `Unknown tool: ${toolName}` });
   }
   return handler(params, brain);
 }

package/dist/update-check-GQVDVT2N.js

@@ -0,0 +1,14 @@
+import {
+  __resetUpdateCheckForTests,
+  __setCachedLatestForTests,
+  getCachedLatestVersion,
+  isNewerVersion,
+  prewarmLatestVersion
+} from "./chunk-POXT5OYN.js";
+export {
+  __resetUpdateCheckForTests,
+  __setCachedLatestForTests,
+  getCachedLatestVersion,
+  isNewerVersion,
+  prewarmLatestVersion
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knit-mcp",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Knit — second brain for Claude Code. MCP server giving any AI agent project-scoped memory, tiered workflow protocol, and parallel team worktrees.",
   "type": "module",
   "bin": {
@@ -14,7 +14,10 @@
     "lint": "eslint src/ tests/ --ext .ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "bench": "tsx benchmarks/retrieval-synthetic.ts",
+    "bench": "npm run bench:retrieval",
+    "bench:retrieval": "tsx benchmarks/retrieval-synthetic.ts",
+    "bench:tokens": "tsx benchmarks/token-economy.ts",
+    "bench:all": "npm run bench:retrieval && npm run bench:tokens",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
   },
   "keywords": [

package/dist/{status-VJDB75X2.js → status-2SEITNIE.js}

@@ -1,12 +1,12 @@
-import {
-  readLearnings
-} from "./chunk-M3YZOJNW.js";
 import {
   getKBSummary,
   getStaleEntries,
   getTopEntries,
   loadKnowledgeBase
 } from "./chunk-WKQHCLLO.js";
+import {
+  readLearnings
+} from "./chunk-M3YZOJNW.js";
 import {
   knowledgePath,
   knowledgebasePath,