@theglitchking/semantic-memory 1.0.0 → 1.1.0

package/dist/mcp/server.js

@@ -1,14 +1,19 @@
 import {
   FrontmatterManager,
   NoteCrud,
+  SessionManager,
   TagManager,
   Watcher,
   applyPatch,
   buildIngestChangeSet,
+  buildPromoteChangeSet,
   buildSynthesizeChangeSet,
+  deriveSessionDir,
+  inspectAgentsContract,
   regenDirectoryIndex,
-  regenIndexesForPaths
-} from "../chunk-CXTRTCIK.js";
+  regenIndexesForPaths,
+  regenerateAgentsContract
+} from "../chunk-XBAN7GRT.js";
 import {
   Embedder,
   GraphBuilder,
@@ -36,6 +41,217 @@ import {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/mcp/context.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { existsSync } from "fs";
+async function buildContext(notesPath, options = {}) {
+  const indexPath = join(notesPath, ".semantic-sidekick-index");
+  await mkdir(indexPath, { recursive: true });
+  const indexer = new Indexer(notesPath);
+  const embedder = new Embedder(options.model, options.workers, options.batchSize, options.quantized);
+  const graph = new GraphBuilder();
+  const textSearch = new TextSearch();
+  const crud = new NoteCrud(notesPath);
+  const frontmatterManager = new FrontmatterManager(notesPath);
+  const tagManager = new TagManager(notesPath);
+  const sessions = new SessionManager(deriveSessionDir(notesPath));
+  let documents = [];
+  let docByPath = /* @__PURE__ */ new Map();
+  let vectorIndex = null;
+  let indexState = "empty";
+  let indexProgress = { embedded: 0, total: 0 };
+  let indexingPromise = null;
+  async function tryLoadCachedIndex() {
+    try {
+      indexState = "loading";
+      await embedder.init();
+      const metaPath = join(indexPath, "meta.json");
+      let meta = null;
+      if (existsSync(metaPath)) {
+        try {
+          meta = JSON.parse(await readFile(metaPath, "utf-8"));
+          if (meta?.model && meta.model !== embedder.getModel()) {
+            process.stderr.write(`Model changed (${meta.model} \u2192 ${embedder.getModel()}), forcing reindex
+`);
+            return false;
+          }
+        } catch {
+          meta = null;
+        }
+      }
+      const tempVector = new VectorIndex(embedder.getDimensions());
+      const vectorLoaded = await tempVector.load(indexPath);
+      if (!vectorLoaded) return false;
+      const savedEmbeddings = await embedder.loadEmbeddings(indexPath);
+      if (savedEmbeddings.size === 0) return false;
+      const graphLoaded = await graph.load(indexPath);
+      if (!graphLoaded) return false;
+      documents = await indexer.indexAll();
+      docByPath = new Map(documents.map((d) => [d.path, d]));
+      textSearch.setDocuments(documents);
+      vectorIndex = tempVector;
+      const currentChunks = documents.reduce((n, d) => n + d.chunks.length, 0);
+      const fresh = meta?.totalChunks !== void 0 && meta.totalChunks === currentChunks;
+      indexState = fresh ? "ready" : "stale";
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async function fullIndex() {
+    indexState = "indexing";
+    indexProgress = { embedded: 0, total: 0 };
+    await embedder.init();
+    const newDocs = await indexer.indexAll();
+    const totalChunks = newDocs.reduce((n, d) => n + d.chunks.length, 0);
+    indexProgress = { embedded: 0, total: totalChunks };
+    const newTextSearch = new TextSearch();
+    newTextSearch.setDocuments(newDocs);
+    const newGraph = new GraphBuilder();
+    newGraph.buildFromDocuments(newDocs);
+    const savedEmbeddings = await embedder.loadEmbeddings(indexPath);
+    const SAVE_INTERVAL = 100;
+    const allChunks = [];
+    const cumulativeEmbeddings = new Map(savedEmbeddings);
+    const pendingChunks = [];
+    for (const doc of newDocs) {
+      for (let i = 0; i < doc.chunks.length; i++) {
+        const key = `${doc.path}:${i}`;
+        const existing = cumulativeEmbeddings.get(key);
+        if (existing) {
+          allChunks.push({ embedding: existing, docPath: doc.path, chunkIndex: i, text: doc.chunks[i] });
+        } else {
+          pendingChunks.push({ text: doc.chunks[i], docPath: doc.path, chunkIndex: i });
+        }
+      }
+    }
+    indexProgress = { embedded: allChunks.length, total: totalChunks };
+    if (pendingChunks.length > 0) {
+      let chunksSinceLastSave = 0;
+      const alreadyEmbedded = allChunks.length;
+      await embedder.embedBatch(
+        pendingChunks.map((c) => c.text),
+        async (done, _total, embeddings) => {
+          if (!embeddings) return;
+          const batchStart = done - embeddings.length;
+          for (let i = 0; i < embeddings.length; i++) {
+            const { docPath, chunkIndex, text } = pendingChunks[batchStart + i];
+            const key = `${docPath}:${chunkIndex}`;
+            cumulativeEmbeddings.set(key, embeddings[i]);
+            allChunks.push({ embedding: embeddings[i], docPath, chunkIndex, text });
+            chunksSinceLastSave++;
+          }
+          const current = alreadyEmbedded + done;
+          indexProgress = { embedded: current, total: totalChunks };
+          options.onProgress?.(current, totalChunks);
+          if (chunksSinceLastSave >= SAVE_INTERVAL) {
+            await embedder.saveEmbeddings(cumulativeEmbeddings, indexPath);
+            chunksSinceLastSave = 0;
+          }
+        }
+      );
+    }
+    const newVector = new VectorIndex(embedder.getDimensions());
+    newVector.build(
+      allChunks.map((c) => c.embedding),
+      allChunks.map((c) => ({ docPath: c.docPath, chunkIndex: c.chunkIndex, text: c.text }))
+    );
+    documents = newDocs;
+    docByPath = new Map(documents.map((d) => [d.path, d]));
+    textSearch.setDocuments(newDocs);
+    graph.buildFromDocuments(newDocs);
+    vectorIndex = newVector;
+    indexState = "ready";
+    await Promise.all([
+      graph.save(indexPath),
+      newVector.save(indexPath),
+      embedder.saveEmbeddings(cumulativeEmbeddings, indexPath),
+      indexer.saveDocsCache(indexPath, newDocs),
+      writeFile(join(indexPath, "meta.json"), JSON.stringify({
+        model: embedder.getModel(),
+        dimensions: embedder.getDimensions(),
+        totalChunks: allChunks.length,
+        indexedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }))
+    ]);
+  }
+  function backgroundIndex() {
+    if (indexingPromise) return;
+    indexingPromise = fullIndex().catch((err) => {
+      process.stderr.write(`Index error: ${err?.message ?? err}
+`);
+      if (indexState === "indexing") indexState = documents.length > 0 ? "stale" : "empty";
+    }).finally(() => {
+      indexingPromise = null;
+    });
+  }
+  function textResponse(text) {
+    return { content: [{ type: "text", text }] };
+  }
+  function indexingMessage() {
+    if (indexProgress.total > 0) {
+      return `Indexing in progress (${indexProgress.embedded}/${indexProgress.total} chunks)... Try again shortly.`;
+    }
+    return "Indexing in progress... Try again shortly.";
+  }
+  function enrichResult(result) {
+    const doc = docByPath.get(result.path);
+    if (!doc) return result;
+    return {
+      ...result,
+      mtime: doc.mtime,
+      ...doc.loadPriority !== void 0 && { loadPriority: doc.loadPriority },
+      ...doc.status !== void 0 && { status: doc.status },
+      ...doc.tier !== void 0 && { tier: doc.tier },
+      ...doc.domains !== void 0 && { domains: doc.domains }
+    };
+  }
+  function applyPriorityBoost(score, path) {
+    const doc = docByPath.get(path);
+    if (doc?.loadPriority === void 0) return score;
+    return score * (1 + (doc.loadPriority - 5) * 0.04);
+  }
+  function applyDateFilter(results, modifiedAfter, modifiedBefore) {
+    if (!modifiedAfter && !modifiedBefore) return results;
+    const after = modifiedAfter ? new Date(modifiedAfter).getTime() : -Infinity;
+    const before = modifiedBefore ? new Date(modifiedBefore).getTime() : Infinity;
+    return results.filter((r) => {
+      const doc = docByPath.get(r.path);
+      if (!doc) return true;
+      const t = new Date(doc.mtime).getTime();
+      return t >= after && t <= before;
+    });
+  }
+  return {
+    notesPath,
+    indexPath,
+    options,
+    indexer,
+    embedder,
+    graph,
+    textSearch,
+    crud,
+    frontmatterManager,
+    tagManager,
+    sessions,
+    getDocuments: () => documents,
+    getDocByPath: () => docByPath,
+    getVectorIndex: () => vectorIndex,
+    getIndexState: () => indexState,
+    getIndexProgress: () => indexProgress,
+    tryLoadCachedIndex,
+    fullIndex,
+    backgroundIndex,
+    isIndexingInFlight: () => indexingPromise !== null,
+    textResponse,
+    indexingMessage,
+    enrichResult,
+    applyPriorityBoost,
+    applyDateFilter
+  };
+}
+
 // node_modules/zod/v3/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -4077,215 +4293,38 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// src/mcp/server.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { join } from "path";
-import { existsSync } from "fs";
-async function createServer(notesPath, options = {}) {
-  const indexPath = join(notesPath, ".semantic-sidekick-index");
-  await mkdir(indexPath, { recursive: true });
-  const indexer = new Indexer(notesPath);
-  const embedder = new Embedder(options.model, options.workers, options.batchSize, options.quantized);
-  const graph = new GraphBuilder();
-  const textSearch = new TextSearch();
-  const crud = new NoteCrud(notesPath);
-  const frontmatterManager = new FrontmatterManager(notesPath);
-  const tagManager = new TagManager(notesPath);
-  let documents = [];
-  let docByPath = /* @__PURE__ */ new Map();
-  let vectorIndex = null;
-  let indexState = "empty";
-  let indexProgress = { embedded: 0, total: 0 };
-  let indexingPromise = null;
-  async function tryLoadCachedIndex() {
-    try {
-      indexState = "loading";
-      await embedder.init();
-      const metaPath = join(indexPath, "meta.json");
-      let meta = null;
-      if (existsSync(metaPath)) {
-        try {
-          meta = JSON.parse(await readFile(metaPath, "utf-8"));
-          if (meta?.model && meta.model !== embedder.getModel()) {
-            process.stderr.write(`Model changed (${meta.model} \u2192 ${embedder.getModel()}), forcing reindex
-`);
-            return false;
-          }
-        } catch {
-          meta = null;
-        }
+// src/mcp/tools/search.ts
+function registerSearchTools(server, ctx) {
+  server.tool(
+    "search_semantic",
+    "Vector similarity search \u2014 find notes similar to a query by meaning. Scores are boosted by load_priority when present.",
+    {
+      query: external_exports.string(),
+      limit: external_exports.coerce.number().optional().default(10),
+      modifiedAfter: external_exports.string().optional().describe("ISO date \u2014 only return notes modified after this date (e.g. '2026-01-01')"),
+      modifiedBefore: external_exports.string().optional().describe("ISO date \u2014 only return notes modified before this date"),
+      status: external_exports.string().optional().describe("Filter by frontmatter status (e.g. 'active', 'draft')"),
+      tier: external_exports.string().optional().describe("Filter by frontmatter tier (e.g. 'guide', 'reference')"),
+      domain: external_exports.string().optional().describe("Filter by frontmatter domain (e.g. 'api', 'security')")
+    },
+    async ({ query, limit, modifiedAfter, modifiedBefore, status, tier, domain }) => {
+      const vectorIndex = ctx.getVectorIndex();
+      if (!vectorIndex) {
+        return ctx.textResponse(
+          ctx.getIndexState() === "empty" ? ctx.indexingMessage() : "Index not built. Run reindex first."
+        );
       }
-      const tempVector = new VectorIndex(embedder.getDimensions());
-      const vectorLoaded = await tempVector.load(indexPath);
-      if (!vectorLoaded) return false;
-      const savedEmbeddings = await embedder.loadEmbeddings(indexPath);
-      if (savedEmbeddings.size === 0) return false;
-      const graphLoaded = await graph.load(indexPath);
-      if (!graphLoaded) return false;
-      documents = await indexer.indexAll();
-      docByPath = new Map(documents.map((d) => [d.path, d]));
-      textSearch.setDocuments(documents);
-      vectorIndex = tempVector;
-      const currentChunks = documents.reduce((n, d) => n + d.chunks.length, 0);
-      const fresh = meta?.totalChunks !== void 0 && meta.totalChunks === currentChunks;
-      indexState = fresh ? "ready" : "stale";
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  async function fullIndex() {
-    indexState = "indexing";
-    indexProgress = { embedded: 0, total: 0 };
-    await embedder.init();
-    const newDocs = await indexer.indexAll();
-    const totalChunks = newDocs.reduce((n, d) => n + d.chunks.length, 0);
-    indexProgress = { embedded: 0, total: totalChunks };
-    const newTextSearch = new TextSearch();
-    newTextSearch.setDocuments(newDocs);
-    const newGraph = new GraphBuilder();
-    newGraph.buildFromDocuments(newDocs);
-    const savedEmbeddings = await embedder.loadEmbeddings(indexPath);
-    const SAVE_INTERVAL = 100;
-    const allChunks = [];
-    const cumulativeEmbeddings = new Map(savedEmbeddings);
-    const pendingChunks = [];
-    for (const doc of newDocs) {
-      for (let i = 0; i < doc.chunks.length; i++) {
-        const key = `${doc.path}:${i}`;
-        const existing = cumulativeEmbeddings.get(key);
-        if (existing) {
-          allChunks.push({ embedding: existing, docPath: doc.path, chunkIndex: i, text: doc.chunks[i] });
-        } else {
-          pendingChunks.push({ text: doc.chunks[i], docPath: doc.path, chunkIndex: i });
-        }
-      }
-    }
-    indexProgress = { embedded: allChunks.length, total: totalChunks };
-    if (pendingChunks.length > 0) {
-      let chunksSinceLastSave = 0;
-      const alreadyEmbedded = allChunks.length;
-      await embedder.embedBatch(
-        pendingChunks.map((c) => c.text),
-        async (done, _total, embeddings) => {
-          if (!embeddings) return;
-          const batchStart = done - embeddings.length;
-          for (let i = 0; i < embeddings.length; i++) {
-            const { docPath, chunkIndex, text } = pendingChunks[batchStart + i];
-            const key = `${docPath}:${chunkIndex}`;
-            cumulativeEmbeddings.set(key, embeddings[i]);
-            allChunks.push({ embedding: embeddings[i], docPath, chunkIndex, text });
-            chunksSinceLastSave++;
-          }
-          const current = alreadyEmbedded + done;
-          indexProgress = { embedded: current, total: totalChunks };
-          options.onProgress?.(current, totalChunks);
-          if (chunksSinceLastSave >= SAVE_INTERVAL) {
-            await embedder.saveEmbeddings(cumulativeEmbeddings, indexPath);
-            chunksSinceLastSave = 0;
-          }
-        }
-      );
-    }
-    const newVector = new VectorIndex(embedder.getDimensions());
-    newVector.build(
-      allChunks.map((c) => c.embedding),
-      allChunks.map((c) => ({ docPath: c.docPath, chunkIndex: c.chunkIndex, text: c.text }))
-    );
-    documents = newDocs;
-    docByPath = new Map(documents.map((d) => [d.path, d]));
-    textSearch.setDocuments(newDocs);
-    graph.buildFromDocuments(newDocs);
-    vectorIndex = newVector;
-    indexState = "ready";
-    await Promise.all([
-      graph.save(indexPath),
-      newVector.save(indexPath),
-      embedder.saveEmbeddings(cumulativeEmbeddings, indexPath),
-      indexer.saveDocsCache(indexPath, newDocs),
-      writeFile(join(indexPath, "meta.json"), JSON.stringify({
-        model: embedder.getModel(),
-        dimensions: embedder.getDimensions(),
-        totalChunks: allChunks.length,
-        indexedAt: (/* @__PURE__ */ new Date()).toISOString()
-      }))
-    ]);
-  }
-  function backgroundIndex() {
-    if (indexingPromise) return;
-    indexingPromise = fullIndex().catch((err) => {
-      process.stderr.write(`Index error: ${err?.message ?? err}
-`);
-      if (indexState === "indexing") indexState = documents.length > 0 ? "stale" : "empty";
-    }).finally(() => {
-      indexingPromise = null;
-    });
-  }
-  function textResponse(text) {
-    return { content: [{ type: "text", text }] };
-  }
-  function indexingMessage() {
-    if (indexProgress.total > 0) {
-      return `Indexing in progress (${indexProgress.embedded}/${indexProgress.total} chunks)... Try again shortly.`;
-    }
-    return "Indexing in progress... Try again shortly.";
-  }
-  function enrichResult(result) {
-    const doc = docByPath.get(result.path);
-    if (!doc) return result;
-    return {
-      ...result,
-      mtime: doc.mtime,
-      ...doc.loadPriority !== void 0 && { loadPriority: doc.loadPriority },
-      ...doc.status !== void 0 && { status: doc.status },
-      ...doc.tier !== void 0 && { tier: doc.tier },
-      ...doc.domains !== void 0 && { domains: doc.domains }
-    };
-  }
-  function applyPriorityBoost(score, path) {
-    const doc = docByPath.get(path);
-    if (doc?.loadPriority === void 0) return score;
-    return score * (1 + (doc.loadPriority - 5) * 0.04);
-  }
-  function applyDateFilter(results, modifiedAfter, modifiedBefore) {
-    if (!modifiedAfter && !modifiedBefore) return results;
-    const after = modifiedAfter ? new Date(modifiedAfter).getTime() : -Infinity;
-    const before = modifiedBefore ? new Date(modifiedBefore).getTime() : Infinity;
-    return results.filter((r) => {
-      const doc = docByPath.get(r.path);
-      if (!doc) return true;
-      const t = new Date(doc.mtime).getTime();
-      return t >= after && t <= before;
-    });
-  }
-  const server = new McpServer({
-    name: "semantic-memory",
-    version: "1.0.0"
-  });
-  server.tool(
-    "search_semantic",
-    "Vector similarity search \u2014 find notes similar to a query by meaning. Scores are boosted by load_priority when present.",
-    {
-      query: external_exports.string(),
-      limit: external_exports.coerce.number().optional().default(10),
-      modifiedAfter: external_exports.string().optional().describe("ISO date \u2014 only return notes modified after this date (e.g. '2026-01-01')"),
-      modifiedBefore: external_exports.string().optional().describe("ISO date \u2014 only return notes modified before this date"),
-      status: external_exports.string().optional().describe("Filter by frontmatter status (e.g. 'active', 'draft')"),
-      tier: external_exports.string().optional().describe("Filter by frontmatter tier (e.g. 'guide', 'reference')"),
-      domain: external_exports.string().optional().describe("Filter by frontmatter domain (e.g. 'api', 'security')")
-    },
-    async ({ query, limit, modifiedAfter, modifiedBefore, status, tier, domain }) => {
-      if (!vectorIndex) return textResponse(indexState === "empty" ? indexingMessage() : "Index not built. Run reindex first.");
-      const queryEmbed = await embedder.embed(query);
-      let results = vectorIndex.search(queryEmbed, limit * 3);
-      results = results.map((r) => ({ ...r, score: applyPriorityBoost(r.score, r.path) }));
-      results.sort((a, b) => b.score - a.score);
-      results = applyDateFilter(results, modifiedAfter, modifiedBefore);
-      if (status) results = results.filter((r) => docByPath.get(r.path)?.status === status);
-      if (tier) results = results.filter((r) => docByPath.get(r.path)?.tier === tier);
-      if (domain) results = results.filter((r) => docByPath.get(r.path)?.domains?.includes(domain));
-      const enriched = results.slice(0, limit).map(enrichResult);
-      return textResponse(JSON.stringify(enriched, null, 2));
+      const queryEmbed = await ctx.embedder.embed(query);
+      let results = vectorIndex.search(queryEmbed, limit * 3);
+      results = results.map((r) => ({ ...r, score: ctx.applyPriorityBoost(r.score, r.path) }));
+      results.sort((a, b) => b.score - a.score);
+      results = ctx.applyDateFilter(results, modifiedAfter, modifiedBefore);
+      const docByPath = ctx.getDocByPath();
+      if (status) results = results.filter((r) => docByPath.get(r.path)?.status === status);
+      if (tier) results = results.filter((r) => docByPath.get(r.path)?.tier === tier);
+      if (domain) results = results.filter((r) => docByPath.get(r.path)?.domains?.includes(domain));
+      const enriched = results.slice(0, limit).map((r) => ctx.enrichResult(r));
+      return ctx.textResponse(JSON.stringify(enriched, null, 2));
     }
   );
   server.tool(
@@ -4305,14 +4344,16 @@ async function createServer(notesPath, options = {}) {
       domain: external_exports.string().optional().describe("Filter by frontmatter domain")
     },
     async ({ modifiedAfter, modifiedBefore, status, tier, domain, ...opts }) => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
-      let results = textSearch.search(opts);
-      results = applyDateFilter(results, modifiedAfter, modifiedBefore);
+      const documents = ctx.getDocuments();
+      if (documents.length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
+      let results = ctx.textSearch.search(opts);
+      results = ctx.applyDateFilter(results, modifiedAfter, modifiedBefore);
+      const docByPath = ctx.getDocByPath();
       if (status) results = results.filter((r) => docByPath.get(r.path)?.status === status);
       if (tier) results = results.filter((r) => docByPath.get(r.path)?.tier === tier);
       if (domain) results = results.filter((r) => docByPath.get(r.path)?.domains?.includes(domain));
-      const enriched = results.map(enrichResult);
-      return textResponse(JSON.stringify(enriched, null, 2));
+      const enriched = results.map((r) => ctx.enrichResult(r));
+      return ctx.textResponse(JSON.stringify(enriched, null, 2));
     }
   );
   server.tool(
@@ -4324,9 +4365,10 @@ async function createServer(notesPath, options = {}) {
       limit: external_exports.coerce.number().optional().default(20)
     },
     async ({ concept, maxDepth, limit }) => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
-      const results = graph.searchGraph(concept, maxDepth, limit);
-      return textResponse(JSON.stringify(results, null, 2));
+      const documents = ctx.getDocuments();
+      if (documents.length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
+      const results = ctx.graph.searchGraph(concept, maxDepth, limit);
+      return ctx.textResponse(JSON.stringify(results, null, 2));
     }
   );
   server.tool(
@@ -4342,45 +4384,55 @@ async function createServer(notesPath, options = {}) {
       domain: external_exports.string().optional().describe("Filter by frontmatter domain")
     },
     async ({ query, limit, modifiedAfter, modifiedBefore, status, tier, domain }) => {
-      if (!vectorIndex) return textResponse(indexState === "empty" ? indexingMessage() : "Index not built. Run reindex first.");
-      const queryEmbed = await embedder.embed(query);
+      const vectorIndex = ctx.getVectorIndex();
+      if (!vectorIndex) {
+        return ctx.textResponse(
+          ctx.getIndexState() === "empty" ? ctx.indexingMessage() : "Index not built. Run reindex first."
+        );
+      }
+      const queryEmbed = await ctx.embedder.embed(query);
       const semanticResults = vectorIndex.search(queryEmbed, limit * 3);
-      const graphResults = graph.searchGraph(query, 2);
+      const graphResults = ctx.graph.searchGraph(query, 2);
       const graphPaths = new Set(graphResults.map((r) => r.path));
       let hybrid = semanticResults.map((r) => ({
         ...r,
-        score: applyPriorityBoost(
+        score: ctx.applyPriorityBoost(
           graphPaths.has(r.path) ? r.score * 1.3 : r.score,
           r.path
         )
       }));
       hybrid.sort((a, b) => b.score - a.score);
-      hybrid = applyDateFilter(hybrid, modifiedAfter, modifiedBefore);
+      hybrid = ctx.applyDateFilter(hybrid, modifiedAfter, modifiedBefore);
+      const docByPath = ctx.getDocByPath();
       if (status) hybrid = hybrid.filter((r) => docByPath.get(r.path)?.status === status);
       if (tier) hybrid = hybrid.filter((r) => docByPath.get(r.path)?.tier === tier);
       if (domain) hybrid = hybrid.filter((r) => docByPath.get(r.path)?.domains?.includes(domain));
-      const enriched = hybrid.slice(0, limit).map(enrichResult);
-      return textResponse(JSON.stringify(enriched, null, 2));
+      const enriched = hybrid.slice(0, limit).map((r) => ctx.enrichResult(r));
+      return ctx.textResponse(JSON.stringify(enriched, null, 2));
     }
   );
+}
+
+// src/mcp/tools/read.ts
+function registerReadTools(server, ctx) {
   server.tool(
     "read_note",
     "Read the full content of a specific note by path",
     { path: external_exports.string() },
     async ({ path }) => {
-      const content = await crud.read(path);
-      return textResponse(content);
+      const content = await ctx.crud.read(path);
+      return ctx.textResponse(content);
     }
   );
   server.tool(
     "read_multiple_notes",
-    "Batch read multiple notes in one call",
+    "[DEPRECATED \u2014 removed in v2.0.0; use read_note in a loop or via batched MCP calls] Batch read multiple notes in one call",
     { paths: external_exports.array(external_exports.string()) },
     async ({ paths }) => {
-      const results = await crud.readMultiple(paths);
+      const results = await ctx.crud.readMultiple(paths);
       const output = {};
       for (const [k, v] of results) output[k] = v;
-      return textResponse(JSON.stringify(output, null, 2));
+      return ctx.textResponse(JSON.stringify(output, null, 2));
     }
   );
   server.tool(
@@ -4394,10 +4446,11 @@ async function createServer(notesPath, options = {}) {
       domain: external_exports.string().optional().describe("Filter by frontmatter domain (e.g. 'api', 'security')")
     },
     async ({ modifiedAfter, modifiedBefore, status, tier, domain }) => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
+      const documents = ctx.getDocuments();
+      if (documents.length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
       const after = modifiedAfter ? new Date(modifiedAfter).getTime() : -Infinity;
       const before = modifiedBefore ? new Date(modifiedBefore).getTime() : Infinity;
-      let list = documents.filter((d) => {
+      const list = documents.filter((d) => {
         const t = new Date(d.mtime).getTime();
         if (t < after || t > before) return false;
         if (status && d.status !== status) return false;
@@ -4417,288 +4470,447 @@ async function createServer(notesPath, options = {}) {
         ...d.domains !== void 0 && { domains: d.domains },
         ...d.purpose !== void 0 && { purpose: d.purpose }
       }));
-      return textResponse(JSON.stringify(list, null, 2));
+      return ctx.textResponse(JSON.stringify(list, null, 2));
     }
   );
-  if (!options.readOnly) {
-    server.tool(
-      "create_note",
-      "Create a new markdown note",
-      {
-        path: external_exports.string(),
-        content: external_exports.string(),
-        frontmatter: external_exports.record(external_exports.unknown()).optional()
-      },
-      async ({ path, content, frontmatter }) => {
-        await crud.create(path, content, frontmatter);
-        return textResponse(`Created: ${path}`);
+}
+
+// src/mcp/tools/write.ts
+function registerWriteTools(server, ctx) {
+  if (ctx.options.readOnly) return;
+  server.tool(
+    "create_note",
+    "Create a new markdown note",
+    {
+      path: external_exports.string(),
+      content: external_exports.string(),
+      frontmatter: external_exports.record(external_exports.unknown()).optional()
+    },
+    async ({ path, content, frontmatter }) => {
+      await ctx.crud.create(path, content, frontmatter);
+      return ctx.textResponse(`Created: ${path}`);
+    }
+  );
+  server.tool(
+    "update_note",
+    "Edit note content \u2014 overwrite, append, prepend, or patch by heading",
+    {
+      path: external_exports.string(),
+      content: external_exports.string(),
+      mode: external_exports.enum(["overwrite", "append", "prepend", "patch-by-heading"]),
+      heading: external_exports.string().optional()
+    },
+    async ({ path, content, mode, heading }) => {
+      await ctx.crud.update(path, content, { mode, heading });
+      return ctx.textResponse(`Updated: ${path} (${mode})`);
+    }
+  );
+  server.tool(
+    "delete_note",
+    "Delete a note permanently",
+    { path: external_exports.string(), confirm: external_exports.boolean().default(false) },
+    async ({ path, confirm }) => {
+      if (!confirm) return ctx.textResponse(`Set confirm=true to delete ${path}`);
+      await ctx.crud.delete(path);
+      return ctx.textResponse(`Deleted: ${path}`);
+    }
+  );
+  server.tool(
+    "move_note",
+    "Move or rename a note \u2014 updates wikilinks across the vault",
+    { from: external_exports.string(), to: external_exports.string() },
+    async ({ from, to }) => {
+      await ctx.crud.move(from, to);
+      return ctx.textResponse(`Moved: ${from} \u2192 ${to}`);
+    }
+  );
+}
+
+// src/mcp/tools/patch.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join2 } from "path";
+import matter from "gray-matter";
+function registerPatchTools(server, ctx) {
+  if (ctx.options.readOnly) return;
+  server.tool(
+    "apply_patch",
+    "Atomic multi-note patch with rollback \u2014 apply a ChangeSet of creates/updates/deletes/moves. If any op fails, earlier ops are reverted. In dry-run, nothing is written; result describes the proposed state + schema findings.",
+    {
+      creates: external_exports.array(
+        external_exports.object({
+          path: external_exports.string(),
+          content: external_exports.string(),
+          frontmatter: external_exports.record(external_exports.unknown()).optional()
+        })
+      ).optional(),
+      updates: external_exports.array(
+        external_exports.object({
+          path: external_exports.string(),
+          content: external_exports.string(),
+          mode: external_exports.enum(["overwrite", "append", "prepend", "patch-by-heading"]),
+          heading: external_exports.string().optional()
+        })
+      ).optional(),
+      deletes: external_exports.array(external_exports.object({ path: external_exports.string() })).optional(),
+      moves: external_exports.array(external_exports.object({ from: external_exports.string(), to: external_exports.string() })).optional(),
+      dry_run: external_exports.boolean().optional().default(false),
+      validate: external_exports.boolean().optional().default(true),
+      allow_lint_warnings: external_exports.boolean().optional().default(true)
+    },
+    async (args) => {
+      const cs = {
+        creates: args.creates,
+        updates: args.updates,
+        deletes: args.deletes,
+        moves: args.moves
+      };
+      const result = await applyPatch(ctx.notesPath, cs, {
+        dryRun: args.dry_run,
+        validate: args.validate,
+        allowLintWarnings: args.allow_lint_warnings
+      });
+      if (!result.ok && !args.dry_run) {
+        await logEvent(ctx.notesPath, {
+          kind: "error",
+          summary: `apply_patch failed: ${result.errors[0] ?? "unknown"}`,
+          payload: { tool: "apply_patch", errors: result.errors, rolled_back: result.rolledBack.length }
+        }).catch(() => {
+        });
       }
-    );
-    server.tool(
-      "update_note",
-      "Edit note content \u2014 overwrite, append, prepend, or patch by heading",
-      {
-        path: external_exports.string(),
-        content: external_exports.string(),
-        mode: external_exports.enum(["overwrite", "append", "prepend", "patch-by-heading"]),
-        heading: external_exports.string().optional()
-      },
-      async ({ path, content, mode, heading }) => {
-        await crud.update(path, content, { mode, heading });
-        return textResponse(`Updated: ${path} (${mode})`);
+      if (result.ok && !args.dry_run) {
+        const touched = result.applied.map((o) => o.path);
+        await ctx.sessions.recordNotesTouched(touched).catch(() => {
+        });
       }
-    );
-    server.tool(
-      "delete_note",
-      "Delete a note permanently",
-      { path: external_exports.string(), confirm: external_exports.boolean().default(false) },
-      async ({ path, confirm }) => {
-        if (!confirm) return textResponse(`Set confirm=true to delete ${path}`);
-        await crud.delete(path);
-        return textResponse(`Deleted: ${path}`);
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+  server.tool(
+    "synthesize_note",
+    "Turn a researched answer + sources into a new filed note with provenance frontmatter and auto-wikilinks. Builds a ChangeSet and applies it (dry-run supported). The primary path from query-answer to durable vault artifact. Pass `proposal: true` to file the result under `proposals/<date>-<slug>.md` with `status: proposal` for review-first workflows; `synthesize_promote` then moves it to the canonical destination.",
+    {
+      topic: external_exports.string(),
+      answer: external_exports.string(),
+      suggested_path: external_exports.string().describe("Target path relative to vault root, e.g. 'decisions/auth-migration.md'. In proposal mode, this is recorded as proposed_target frontmatter and the actual write goes to proposals/."),
+      type: external_exports.string().optional().default("note").describe("One of the schema types: note, decision, gotcha, source"),
+      sources: external_exports.array(external_exports.string()).optional().describe("External URLs or paths \u2014 populate provenance.sources"),
+      derived_from: external_exports.array(external_exports.string()).optional().describe("Wikilinks to other vault notes \u2014 populate provenance.derived_from"),
+      related_notes: external_exports.array(external_exports.string()).optional().describe("Note names or paths to auto-link in the body + list under Related"),
+      status: external_exports.string().optional().default("active"),
+      confidence: external_exports.string().optional().default("medium"),
+      decision_maker: external_exports.string().optional(),
+      decided_on: external_exports.string().optional(),
+      severity: external_exports.string().optional(),
+      dry_run: external_exports.boolean().optional().default(false),
+      proposal: external_exports.boolean().optional().default(false).describe("Write to proposals/<date>-<slug>.md with status:proposal instead of the canonical destination. Use for review-first workflows."),
+      proposal_subdir: external_exports.string().optional().describe("Override the proposal subdirectory (default 'proposals'). Useful for source segregation, e.g. 'proposals/research'."),
+      from_session: external_exports.boolean().optional().default(false).describe("When true, pull defaults from the active session: prepend a verification summary to `answer`, default `derived_from` to session.notes_touched, and append session id+task to `sources`. No-op when no session is active.")
+    },
+    async (args) => {
+      let answer = args.answer;
+      let derivedFrom = args.derived_from;
+      let sources = args.sources;
+      if (args.from_session) {
+        const session = await ctx.sessions.readActive();
+        if (session) {
+          const verifLines = session.verifications.map(
+            (v) => `- \`${v.cmd}\` \u2192 exit=${v.exit ?? "(killed)"} in ${v.duration_ms}ms`
+          );
+          if (verifLines.length > 0) {
+            answer = `${answer}
+
+## Session verifications (${session.id})
+
+${verifLines.join("\n")}
+`;
+          }
+          if ((!derivedFrom || derivedFrom.length === 0) && session.notes_touched.length > 0) {
+            derivedFrom = [...session.notes_touched];
+          }
+          const sessionTag = `session:${session.id} task:${session.task}`;
+          sources = sources ? [...sources, sessionTag] : [sessionTag];
+        }
       }
-    );
-    server.tool(
-      "move_note",
-      "Move or rename a note \u2014 updates wikilinks across the vault",
-      { from: external_exports.string(), to: external_exports.string() },
-      async ({ from, to }) => {
-        await crud.move(from, to);
-        return textResponse(`Moved: ${from} \u2192 ${to}`);
+      const preview = buildSynthesizeChangeSet({
+        topic: args.topic,
+        answer,
+        suggested_path: args.suggested_path,
+        type: args.type,
+        sources,
+        derived_from: derivedFrom,
+        related_notes: args.related_notes,
+        status: args.status,
+        confidence: args.confidence,
+        decision_maker: args.decision_maker,
+        decided_on: args.decided_on,
+        severity: args.severity,
+        proposal: args.proposal,
+        proposal_subdir: args.proposal_subdir
+      });
+      const result = await applyPatch(ctx.notesPath, preview.changeset, {
+        dryRun: args.dry_run
+      });
+      if (result.ok && !args.dry_run) {
+        await logEvent(ctx.notesPath, {
+          kind: "synthesis",
+          summary: `synthesized ${preview.title}${preview.is_proposal ? " (proposal)" : ""}`,
+          payload: {
+            path: preview.path,
+            type: args.type,
+            sources: sources ?? [],
+            derived_from: derivedFrom ?? [],
+            ...preview.is_proposal && { is_proposal: true, proposed_target: preview.proposed_target }
+          }
+        }).catch(() => {
+        });
+        await ctx.sessions.recordNotesTouched([preview.path]).catch(() => {
+        });
+      } else if (!result.ok && !args.dry_run) {
+        await logEvent(ctx.notesPath, {
+          kind: "error",
+          summary: `synthesize_note failed: ${result.errors[0] ?? "unknown"}`,
+          payload: { tool: "synthesize_note", path: preview.path, errors: result.errors }
+        }).catch(() => {
+        });
       }
-    );
-    server.tool(
-      "apply_patch",
-      "Atomic multi-note patch with rollback \u2014 apply a ChangeSet of creates/updates/deletes/moves. If any op fails, earlier ops are reverted. In dry-run, nothing is written; result describes the proposed state + schema findings.",
-      {
-        creates: external_exports.array(
-          external_exports.object({
-            path: external_exports.string(),
-            content: external_exports.string(),
-            frontmatter: external_exports.record(external_exports.unknown()).optional()
-          })
-        ).optional(),
-        updates: external_exports.array(
-          external_exports.object({
-            path: external_exports.string(),
-            content: external_exports.string(),
-            mode: external_exports.enum(["overwrite", "append", "prepend", "patch-by-heading"]),
-            heading: external_exports.string().optional()
-          })
-        ).optional(),
-        deletes: external_exports.array(external_exports.object({ path: external_exports.string() })).optional(),
-        moves: external_exports.array(external_exports.object({ from: external_exports.string(), to: external_exports.string() })).optional(),
-        dry_run: external_exports.boolean().optional().default(false),
-        validate: external_exports.boolean().optional().default(true),
-        allow_lint_warnings: external_exports.boolean().optional().default(true)
-      },
-      async (args) => {
-        const cs = {
-          creates: args.creates,
-          updates: args.updates,
-          deletes: args.deletes,
-          moves: args.moves
-        };
-        const result = await applyPatch(notesPath, cs, {
-          dryRun: args.dry_run,
-          validate: args.validate,
-          allowLintWarnings: args.allow_lint_warnings
+      return ctx.textResponse(
+        JSON.stringify(
+          {
+            preview: {
+              path: preview.path,
+              title: preview.title,
+              ...preview.is_proposal && { is_proposal: true, proposed_target: preview.proposed_target }
+            },
+            result
+          },
+          null,
+          2
+        )
+      );
+    }
+  );
+  server.tool(
+    "synthesize_promote",
+    "Move a reviewed proposal note to its canonical destination. Reads the proposal's frontmatter (which must have `status: proposal` and `proposed_target`), strips proposal markers, restores canonical status, and atomically creates the target + deletes the proposal. Optional `target_path` overrides the proposal's recorded `proposed_target`.",
+    {
+      proposal_path: external_exports.string().describe("Path to the proposal note relative to vault root, e.g. 'proposals/2026-05-08-auth-flow.md'"),
+      target_path: external_exports.string().optional().describe("Optional destination override. When omitted, uses the proposal's own `proposed_target` frontmatter."),
+      dry_run: external_exports.boolean().optional().default(false)
+    },
+    async (args) => {
+      const absoluteProposalPath = join2(ctx.notesPath, args.proposal_path);
+      let raw;
+      try {
+        raw = await readFile2(absoluteProposalPath, "utf-8");
+      } catch (err) {
+        return ctx.textResponse(JSON.stringify({
+          ok: false,
+          error: `Proposal file not found: ${args.proposal_path}`
+        }, null, 2));
+      }
+      const parsed = matter(raw);
+      const fm = parsed.data;
+      if (fm.status !== "proposal") {
+        return ctx.textResponse(JSON.stringify({
+          ok: false,
+          error: `Note ${args.proposal_path} does not have status:proposal frontmatter (got status=${JSON.stringify(fm.status)}). Refusing to promote \u2014 only proposal-flagged notes are eligible.`
+        }, null, 2));
+      }
+      let preview;
+      try {
+        preview = buildPromoteChangeSet({
+          proposal_path: args.proposal_path,
+          target_path: args.target_path,
+          body: parsed.content,
+          frontmatter: fm
         });
-        if (!result.ok && !args.dry_run) {
-          await logEvent(notesPath, {
-            kind: "error",
-            summary: `apply_patch failed: ${result.errors[0] ?? "unknown"}`,
-            payload: { tool: "apply_patch", errors: result.errors, rolled_back: result.rolledBack.length }
-          }).catch(() => {
-          });
-        }
-        return textResponse(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return ctx.textResponse(JSON.stringify({ ok: false, error: err?.message ?? String(err) }, null, 2));
       }
-    );
-    server.tool(
-      "synthesize_note",
-      "Turn a researched answer + sources into a new filed note with provenance frontmatter and auto-wikilinks. Builds a ChangeSet and applies it (dry-run supported). The primary path from query-answer to durable vault artifact.",
-      {
-        topic: external_exports.string(),
-        answer: external_exports.string(),
-        suggested_path: external_exports.string().describe("Target path relative to vault root, e.g. 'decisions/auth-migration.md'"),
-        type: external_exports.string().optional().default("note").describe("One of the schema types: note, decision, gotcha, source"),
-        sources: external_exports.array(external_exports.string()).optional().describe("External URLs or paths \u2014 populate provenance.sources"),
-        derived_from: external_exports.array(external_exports.string()).optional().describe("Wikilinks to other vault notes \u2014 populate provenance.derived_from"),
-        related_notes: external_exports.array(external_exports.string()).optional().describe("Note names or paths to auto-link in the body + list under Related"),
-        status: external_exports.string().optional().default("active"),
-        confidence: external_exports.string().optional().default("medium"),
-        decision_maker: external_exports.string().optional(),
-        decided_on: external_exports.string().optional(),
-        severity: external_exports.string().optional(),
-        dry_run: external_exports.boolean().optional().default(false)
-      },
-      async (args) => {
-        const preview = buildSynthesizeChangeSet({
-          topic: args.topic,
-          answer: args.answer,
-          suggested_path: args.suggested_path,
-          type: args.type,
-          sources: args.sources,
-          derived_from: args.derived_from,
-          related_notes: args.related_notes,
-          status: args.status,
-          confidence: args.confidence,
-          decision_maker: args.decision_maker,
-          decided_on: args.decided_on,
-          severity: args.severity
+      const result = await applyPatch(ctx.notesPath, preview.changeset, { dryRun: args.dry_run });
+      if (result.ok && !args.dry_run) {
+        await logEvent(ctx.notesPath, {
+          kind: "synthesis",
+          summary: `promoted proposal ${preview.from} \u2192 ${preview.to}`,
+          payload: { tool: "synthesize_promote", from: preview.from, to: preview.to }
+        }).catch(() => {
         });
-        const result = await applyPatch(notesPath, preview.changeset, {
-          dryRun: args.dry_run
+        await ctx.sessions.recordNotesTouched([preview.to]).catch(() => {
         });
-        if (result.ok && !args.dry_run) {
-          await logEvent(notesPath, {
-            kind: "synthesis",
-            summary: `synthesized ${preview.title}`,
-            payload: { path: preview.path, type: args.type, sources: args.sources ?? [], derived_from: args.derived_from ?? [] }
-          }).catch(() => {
-          });
-        } else if (!result.ok && !args.dry_run) {
-          await logEvent(notesPath, {
-            kind: "error",
-            summary: `synthesize_note failed: ${result.errors[0] ?? "unknown"}`,
-            payload: { tool: "synthesize_note", path: preview.path, errors: result.errors }
-          }).catch(() => {
-          });
-        }
-        return textResponse(
-          JSON.stringify(
-            {
-              preview: { path: preview.path, title: preview.title },
-              result
-            },
-            null,
-            2
-          )
-        );
       }
-    );
-    server.tool(
-      "ingest_source",
-      "Build + apply a ChangeSet that ingests a source (paper, doc, URL) and the notes extracted from it. Produces one sources/<slug>.md note (type=source) plus one create per extracted unit, each stamped with derived_from pointing at the source. Routes through apply_patch \u2014 atomic, validated, rollback-capable, dry-run supported.",
-      {
-        source: external_exports.object({
-          source_uri: external_exports.string(),
-          source_title: external_exports.string(),
-          source_type: external_exports.string().optional(),
-          source_path: external_exports.string().optional(),
-          source_summary: external_exports.string().optional(),
-          source_tags: external_exports.array(external_exports.string()).optional()
-        }),
-        units: external_exports.array(
-          external_exports.object({
-            path: external_exports.string(),
-            title: external_exports.string().optional(),
-            content: external_exports.string(),
-            type: external_exports.string().optional(),
-            extra_derived_from: external_exports.array(external_exports.string()).optional(),
-            extra_frontmatter: external_exports.record(external_exports.unknown()).optional(),
-            confidence: external_exports.string().optional()
-          })
-        ),
-        dry_run: external_exports.boolean().optional().default(false),
-        auto_apply: external_exports.boolean().optional().default(true).describe("If false, force dry-run regardless of dry_run flag \u2014 use for review-first workflows")
-      },
-      async (args) => {
-        const preview = buildIngestChangeSet({
-          source: args.source,
-          units: args.units
+      return ctx.textResponse(JSON.stringify({ preview: { from: preview.from, to: preview.to }, result }, null, 2));
+    }
+  );
+  server.tool(
+    "ingest_source",
+    "Build + apply a ChangeSet that ingests a source (paper, doc, URL) and the notes extracted from it. Produces one sources/<slug>.md note (type=source) plus one create per extracted unit, each stamped with derived_from pointing at the source. Routes through apply_patch \u2014 atomic, validated, rollback-capable, dry-run supported.",
+    {
+      source: external_exports.object({
+        source_uri: external_exports.string(),
+        source_title: external_exports.string(),
+        source_type: external_exports.string().optional(),
+        source_path: external_exports.string().optional(),
+        source_summary: external_exports.string().optional(),
+        source_tags: external_exports.array(external_exports.string()).optional()
+      }),
+      units: external_exports.array(
+        external_exports.object({
+          path: external_exports.string(),
+          title: external_exports.string().optional(),
+          content: external_exports.string(),
+          type: external_exports.string().optional(),
+          extra_derived_from: external_exports.array(external_exports.string()).optional(),
+          extra_frontmatter: external_exports.record(external_exports.unknown()).optional(),
+          confidence: external_exports.string().optional()
+        })
+      ),
+      dry_run: external_exports.boolean().optional().default(false),
+      auto_apply: external_exports.boolean().optional().default(true).describe("If false, force dry-run regardless of dry_run flag \u2014 use for review-first workflows")
+    },
+    async (args) => {
+      const preview = buildIngestChangeSet({
+        source: args.source,
+        units: args.units
+      });
+      const dry = args.dry_run || args.auto_apply === false;
+      const result = await applyPatch(ctx.notesPath, preview.changeset, { dryRun: dry });
+      if (result.ok && !dry) {
+        await logEvent(ctx.notesPath, {
+          kind: "ingest",
+          summary: `ingested ${preview.unitPaths.length} note(s) from ${args.source.source_title}`,
+          payload: {
+            source_path: preview.sourcePath,
+            unit_paths: preview.unitPaths,
+            source_uri: args.source.source_uri
+          }
+        }).catch(() => {
         });
-        const dry = args.dry_run || args.auto_apply === false;
-        const result = await applyPatch(notesPath, preview.changeset, { dryRun: dry });
-        if (result.ok && !dry) {
-          await logEvent(notesPath, {
-            kind: "ingest",
-            summary: `ingested ${preview.unitPaths.length} note(s) from ${args.source.source_title}`,
-            payload: {
+      } else if (!result.ok && !dry) {
+        await logEvent(ctx.notesPath, {
+          kind: "error",
+          summary: `ingest_source failed: ${result.errors[0] ?? "unknown"}`,
+          payload: {
+            tool: "ingest_source",
+            source_uri: args.source.source_uri,
+            source_title: args.source.source_title,
+            errors: result.errors
+          }
+        }).catch(() => {
+        });
+      }
+      return ctx.textResponse(
+        JSON.stringify(
+          {
+            preview: {
               source_path: preview.sourcePath,
-              unit_paths: preview.unitPaths,
-              source_uri: args.source.source_uri
-            }
-          }).catch(() => {
-          });
-        } else if (!result.ok && !dry) {
-          await logEvent(notesPath, {
-            kind: "error",
-            summary: `ingest_source failed: ${result.errors[0] ?? "unknown"}`,
-            payload: {
-              tool: "ingest_source",
-              source_uri: args.source.source_uri,
-              source_title: args.source.source_title,
-              errors: result.errors
-            }
-          }).catch(() => {
-          });
-        }
-        return textResponse(
-          JSON.stringify(
-            {
-              preview: {
-                source_path: preview.sourcePath,
-                unit_paths: preview.unitPaths
-              },
-              result,
-              dry_run: dry
+              unit_paths: preview.unitPaths
             },
-            null,
-            2
-          )
-        );
-      }
-    );
-    server.tool(
-      "install_schema",
-      "Bootstrap vault.schema.yml in the vault root with the default schema (note/decision/gotcha/source types + provenance fields). Skipped if present unless force=true.",
-      { force: external_exports.boolean().optional().default(false) },
-      async ({ force }) => {
-        const r = await installDefaultSchema(notesPath, force);
-        return textResponse(
-          r.written ? `Installed default schema: ${r.path}` : `Schema already exists: ${r.path} (pass force=true to overwrite)`
-        );
-      }
-    );
-  }
+            result,
+            dry_run: dry
+          },
+          null,
+          2
+        )
+      );
+    }
+  );
+  server.tool(
+    "install_schema",
+    "Bootstrap vault.schema.yml in the vault root with the default schema (note/decision/gotcha/source types + provenance fields). Skipped if present unless force=true.",
+    { force: external_exports.boolean().optional().default(false) },
+    async ({ force }) => {
+      const r = await installDefaultSchema(ctx.notesPath, force);
+      return ctx.textResponse(
+        r.written ? `Installed default schema: ${r.path}` : `Schema already exists: ${r.path} (pass force=true to overwrite)`
+      );
+    }
+  );
+}
+
+// src/mcp/tools/lint.ts
+var ALL_CHECKS = ["schema", "provenance", "stale", "broken_links"];
+var RULE_KEY_FOR_CHECK = {
+  schema: "schema_violations",
+  provenance: "missing_provenance",
+  stale: "stale",
+  broken_links: "broken_links"
+};
+function registerLintTools(server, ctx) {
   server.tool(
     "find_schema_violations",
-    "Scan the vault for schema violations \u2014 missing required fields, unknown types, enum mismatches. Errors block apply_patch when validate=true.",
+    "[DEPRECATED \u2014 removed in v2.0.0; use lint_vault({checks:['schema']})] Scan the vault for schema violations \u2014 missing required fields, unknown types, enum mismatches. Errors block apply_patch when validate=true.",
     { pathGlob: external_exports.string().optional() },
     async ({ pathGlob }) => {
-      const report = await lintVault(notesPath, { pathGlob });
-      return textResponse(JSON.stringify(report.byRule.schema_violations, null, 2));
+      const report = await lintVault(ctx.notesPath, { pathGlob });
+      return ctx.textResponse(JSON.stringify(report.byRule.schema_violations, null, 2));
     }
   );
   server.tool(
     "find_missing_provenance",
-    "Scan the vault for notes of types (note/decision/gotcha by default) that lack both sources and derived_from frontmatter. Warnings by default.",
+    "[DEPRECATED \u2014 removed in v2.0.0; use lint_vault({checks:['provenance']})] Scan the vault for notes of types (note/decision/gotcha by default) that lack both sources and derived_from frontmatter. Warnings by default.",
     { pathGlob: external_exports.string().optional() },
     async ({ pathGlob }) => {
-      const report = await lintVault(notesPath, { pathGlob });
-      return textResponse(JSON.stringify(report.byRule.missing_provenance, null, 2));
+      const report = await lintVault(ctx.notesPath, { pathGlob });
+      return ctx.textResponse(JSON.stringify(report.byRule.missing_provenance, null, 2));
     }
   );
   server.tool(
     "find_stale",
-    "Scan the vault for notes whose last_verified date is older than the schema's stale.max_age_days (default 180).",
+    "[DEPRECATED \u2014 removed in v2.0.0; use lint_vault({checks:['stale']})] Scan the vault for notes whose last_verified date is older than the schema's stale.max_age_days (default 180).",
     { pathGlob: external_exports.string().optional() },
     async ({ pathGlob }) => {
-      const report = await lintVault(notesPath, { pathGlob });
-      return textResponse(JSON.stringify(report.byRule.stale, null, 2));
+      const report = await lintVault(ctx.notesPath, { pathGlob });
+      return ctx.textResponse(JSON.stringify(report.byRule.stale, null, 2));
     }
   );
   server.tool(
     "find_broken_links",
-    "Scan the vault for [[wikilinks]] that point to non-existent notes. Heavier than the other lints (cross-note check) but still metadata-only.",
+    "[DEPRECATED \u2014 removed in v2.0.0; use lint_vault({checks:['broken_links']})] Scan the vault for [[wikilinks]] that point to non-existent notes. Heavier than the other lints (cross-note check) but still metadata-only.",
     { pathGlob: external_exports.string().optional() },
     async ({ pathGlob }) => {
-      const report = await lintVault(notesPath, { pathGlob });
-      return textResponse(JSON.stringify(report.byRule.broken_links, null, 2));
+      const report = await lintVault(ctx.notesPath, { pathGlob });
+      return ctx.textResponse(JSON.stringify(report.byRule.broken_links, null, 2));
+    }
+  );
+  server.tool(
+    "lint_vault",
+    "Run lint rules across the vault. Default returns the full LintReport with all findings grouped by rule. Pass `checks` to filter to specific rules (schema, provenance, stale, broken_links) \u2014 when filtered, byRule contains only the requested rules.",
+    {
+      pathGlob: external_exports.string().optional(),
+      checks: external_exports.array(external_exports.enum(["schema", "provenance", "stale", "broken_links"])).optional().describe("Filter to specific lint rules. Omit for full report.")
+    },
+    async ({ pathGlob, checks }) => {
+      const report = await lintVault(ctx.notesPath, { pathGlob });
+      if (!checks || checks.length === 0) {
+        return ctx.textResponse(JSON.stringify(report, null, 2));
+      }
+      const requested = new Set(checks.length > 0 ? checks : ALL_CHECKS);
+      const filteredByRule = {};
+      for (const check of requested) {
+        const ruleKey = RULE_KEY_FOR_CHECK[check];
+        filteredByRule[ruleKey] = report.byRule[ruleKey] ?? [];
+      }
+      const filteredFindings = report.findings.filter((f) => {
+        const matchedCheck = Object.entries(RULE_KEY_FOR_CHECK).find(([, ruleKey]) => ruleKey === f.rule);
+        return matchedCheck ? requested.has(matchedCheck[0]) : false;
+      });
+      return ctx.textResponse(
+        JSON.stringify(
+          {
+            ...report,
+            findings: filteredFindings,
+            byRule: filteredByRule
+          },
+          null,
+          2
+        )
+      );
     }
   );
+}
+
+// src/mcp/tools/log.ts
+function registerLogTools(server, ctx) {
   server.tool(
     "log_event",
     "Append a structured event to the vault's log.md. Each entry renders as a human line + a machine-readable YAML block for later querying.",
@@ -4708,8 +4920,8 @@ async function createServer(notesPath, options = {}) {
       payload: external_exports.record(external_exports.unknown()).optional().describe("Arbitrary structured data")
     },
     async (args) => {
-      const entry = await logEvent(notesPath, args);
-      return textResponse(JSON.stringify(entry, null, 2));
+      const entry = await logEvent(ctx.notesPath, args);
+      return ctx.textResponse(JSON.stringify(entry, null, 2));
     }
   );
   server.tool(
@@ -4722,11 +4934,11 @@ async function createServer(notesPath, options = {}) {
       limit: external_exports.coerce.number().optional()
     },
     async (args) => {
-      const entries = await logQuery(notesPath, args);
-      return textResponse(JSON.stringify(entries, null, 2));
+      const entries = await logQuery(ctx.notesPath, args);
+      return ctx.textResponse(JSON.stringify(entries, null, 2));
     }
   );
-  if (!options.readOnly) {
+  if (!ctx.options.readOnly) {
     server.tool(
       "regenerate_index",
       "Force regeneration of INDEX.md for one directory (or all affected by a list of paths). Idempotent \u2014 skips write if unchanged.",
@@ -4737,89 +4949,94 @@ async function createServer(notesPath, options = {}) {
       async ({ directory, paths }) => {
         let results;
         if (directory) {
-          results = [await regenDirectoryIndex(notesPath, directory)];
+          results = [await regenDirectoryIndex(ctx.notesPath, directory)];
         } else if (paths && paths.length > 0) {
-          results = await regenIndexesForPaths(notesPath, paths);
+          results = await regenIndexesForPaths(ctx.notesPath, paths);
         } else {
-          return textResponse("Provide either `directory` or `paths`.");
+          return ctx.textResponse("Provide either `directory` or `paths`.");
         }
-        return textResponse(JSON.stringify(results, null, 2));
+        return ctx.textResponse(JSON.stringify(results, null, 2));
       }
     );
   }
-  server.tool(
-    "lint_vault",
-    "Run all lint rules at once \u2014 returns full LintReport with findings grouped by rule.",
-    { pathGlob: external_exports.string().optional() },
-    async ({ pathGlob }) => {
-      const report = await lintVault(notesPath, { pathGlob });
-      return textResponse(JSON.stringify(report, null, 2));
-    }
-  );
+}
+
+// src/mcp/tools/metadata.ts
+function registerMetadataTools(server, ctx) {
   server.tool(
     "get_frontmatter",
     "Read parsed YAML frontmatter from a note as JSON",
     { path: external_exports.string() },
     async ({ path }) => {
-      const fm = await frontmatterManager.get(path);
-      return textResponse(JSON.stringify(fm, null, 2));
+      const fm = await ctx.frontmatterManager.get(path);
+      return ctx.textResponse(JSON.stringify(fm, null, 2));
     }
   );
-  if (!options.readOnly) {
-    server.tool(
-      "update_frontmatter",
-      "Set or delete YAML frontmatter keys \u2014 pass null to delete a key",
-      { path: external_exports.string(), fields: external_exports.record(external_exports.unknown()) },
-      async ({ path, fields }) => {
-        await frontmatterManager.update(path, fields);
-        return textResponse(`Frontmatter updated: ${path}`);
-      }
-    );
-    server.tool(
-      "manage_tags",
-      "Add, remove, or list tags on a note (frontmatter and inline)",
-      {
-        path: external_exports.string(),
-        action: external_exports.enum(["add", "remove", "list"]),
-        tags: external_exports.array(external_exports.string()).optional()
-      },
-      async ({ path, action, tags }) => {
-        switch (action) {
-          case "list": {
-            const result = await tagManager.list(path);
-            return textResponse(JSON.stringify(result));
-          }
-          case "add": {
-            if (!tags?.length) return textResponse("No tags provided");
-            await tagManager.add(path, tags);
-            return textResponse(`Added tags to ${path}: ${tags.join(", ")}`);
-          }
-          case "remove": {
-            if (!tags?.length) return textResponse("No tags provided");
-            await tagManager.remove(path, tags);
-            return textResponse(`Removed tags from ${path}: ${tags.join(", ")}`);
-          }
+  if (ctx.options.readOnly) return;
+  server.tool(
+    "update_frontmatter",
+    "Set or delete YAML frontmatter keys \u2014 pass null to delete a key",
+    { path: external_exports.string(), fields: external_exports.record(external_exports.unknown()) },
+    async ({ path, fields }) => {
+      await ctx.frontmatterManager.update(path, fields);
+      return ctx.textResponse(`Frontmatter updated: ${path}`);
+    }
+  );
+  server.tool(
+    "manage_tags",
+    "Add, remove, list, or rename tags on a note (frontmatter and inline). Use action='rename' with `from` and `to` to rename a tag vault-wide; `path` is ignored in that mode.",
+    {
+      path: external_exports.string(),
+      action: external_exports.enum(["add", "remove", "list", "rename"]),
+      tags: external_exports.array(external_exports.string()).optional(),
+      from: external_exports.string().optional().describe("For action='rename': the existing tag name (no leading #)"),
+      to: external_exports.string().optional().describe("For action='rename': the new tag name (no leading #)")
+    },
+    async ({ path, action, tags, from, to }) => {
+      switch (action) {
+        case "list": {
+          const result = await ctx.tagManager.list(path);
+          return ctx.textResponse(JSON.stringify(result));
+        }
+        case "add": {
+          if (!tags?.length) return ctx.textResponse("No tags provided");
+          await ctx.tagManager.add(path, tags);
+          return ctx.textResponse(`Added tags to ${path}: ${tags.join(", ")}`);
+        }
+        case "remove": {
+          if (!tags?.length) return ctx.textResponse("No tags provided");
+          await ctx.tagManager.remove(path, tags);
+          return ctx.textResponse(`Removed tags from ${path}: ${tags.join(", ")}`);
+        }
+        case "rename": {
+          if (!from || !to) return ctx.textResponse("action='rename' requires both `from` and `to`");
+          const count = await ctx.tagManager.renameVaultWide(from, to);
+          return ctx.textResponse(`Renamed #${from} \u2192 #${to} in ${count} files`);
         }
       }
-    );
-    server.tool(
-      "rename_tag",
-      "Rename a tag across all notes in the vault",
-      { oldTag: external_exports.string(), newTag: external_exports.string() },
-      async ({ oldTag, newTag }) => {
-        const count = await tagManager.renameVaultWide(oldTag, newTag);
-        return textResponse(`Renamed #${oldTag} \u2192 #${newTag} in ${count} files`);
-      }
-    );
-  }
+    }
+  );
+  server.tool(
+    "rename_tag",
+    "[DEPRECATED \u2014 removed in v2.0.0; use manage_tags({action:'rename', from, to})] Rename a tag across all notes in the vault",
+    { oldTag: external_exports.string(), newTag: external_exports.string() },
+    async ({ oldTag, newTag }) => {
+      const count = await ctx.tagManager.renameVaultWide(oldTag, newTag);
+      return ctx.textResponse(`Renamed #${oldTag} \u2192 #${newTag} in ${count} files`);
+    }
+  );
+}
+
+// src/mcp/tools/graph.ts
+function registerGraphTools(server, ctx) {
   server.tool(
     "backlinks",
     "Find all notes that link TO a given note",
     { path: external_exports.string(), limit: external_exports.coerce.number().optional().default(50) },
     async ({ path, limit }) => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
-      const results = graph.backlinks(path).slice(0, limit);
-      return textResponse(JSON.stringify(results, null, 2));
+      if (ctx.getDocuments().length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
+      const results = ctx.graph.backlinks(path).slice(0, limit);
+      return ctx.textResponse(JSON.stringify(results, null, 2));
     }
   );
   server.tool(
@@ -4827,9 +5044,9 @@ async function createServer(notesPath, options = {}) {
     "Find all notes linked FROM a given note",
     { path: external_exports.string(), limit: external_exports.coerce.number().optional().default(50) },
     async ({ path, limit }) => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
-      const results = graph.forwardlinks(path).slice(0, limit);
-      return textResponse(JSON.stringify(results, null, 2));
+      if (ctx.getDocuments().length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
+      const results = ctx.graph.forwardlinks(path).slice(0, limit);
+      return ctx.textResponse(JSON.stringify(results, null, 2));
     }
   );
   server.tool(
@@ -4837,10 +5054,10 @@ async function createServer(notesPath, options = {}) {
     "Find the shortest path between two notes in the knowledge graph",
     { from: external_exports.string(), to: external_exports.string() },
     async ({ from, to }) => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
-      const path = graph.findPath(from, to);
-      if (!path) return textResponse("No path found");
-      return textResponse(JSON.stringify(path));
+      if (ctx.getDocuments().length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
+      const path = ctx.graph.findPath(from, to);
+      if (!path) return ctx.textResponse("No path found");
+      return ctx.textResponse(JSON.stringify(path));
     }
   );
   server.tool(
@@ -4848,24 +5065,32 @@ async function createServer(notesPath, options = {}) {
     "Knowledge graph stats \u2014 most connected nodes, orphans, density",
     {},
     async () => {
-      if (documents.length === 0 && indexState !== "ready") return textResponse(indexingMessage());
-      const stats = graph.statistics();
-      return textResponse(JSON.stringify(stats, null, 2));
+      if (ctx.getDocuments().length === 0 && ctx.getIndexState() !== "ready") return ctx.textResponse(ctx.indexingMessage());
+      const stats = ctx.graph.statistics();
+      return ctx.textResponse(JSON.stringify(stats, null, 2));
     }
   );
+}
+
+// src/mcp/tools/system.ts
+function registerSystemTools(server, ctx) {
   server.tool(
     "get_stats",
     "Vault and index statistics \u2014 note count, chunks, embeddings, graph density",
     {},
     async () => {
-      const graphStats = documents.length > 0 ? graph.statistics() : { totalNodes: 0, totalEdges: 0 };
+      const documents = ctx.getDocuments();
+      const vectorIndex = ctx.getVectorIndex();
+      const indexState = ctx.getIndexState();
+      const indexProgress = ctx.getIndexProgress();
+      const graphStats = documents.length > 0 ? ctx.graph.statistics() : { totalNodes: 0, totalEdges: 0 };
       const stats = {
         totalNotes: documents.length,
         totalChunks: documents.reduce((n, d) => n + d.chunks.length, 0),
         totalEmbeddings: vectorIndex?.getChunkMeta().length ?? 0,
-        embeddingDimensions: embedder.getDimensions(),
-        embeddingModel: embedder.getModel(),
-        embeddingRuntime: embedder.getRuntime?.() ?? "unknown",
+        embeddingDimensions: ctx.embedder.getDimensions(),
+        embeddingModel: ctx.embedder.getModel(),
+        embeddingRuntime: ctx.embedder.getRuntime?.() ?? "unknown",
         graphNodes: graphStats.totalNodes,
         graphEdges: graphStats.totalEdges,
         indexSize: 0,
@@ -4873,7 +5098,7 @@ async function createServer(notesPath, options = {}) {
         indexState,
         indexProgress: indexState === "indexing" ? indexProgress : void 0
       };
-      return textResponse(JSON.stringify(stats, null, 2));
+      return ctx.textResponse(JSON.stringify(stats, null, 2));
     }
   );
   server.tool(
@@ -4881,29 +5106,244 @@ async function createServer(notesPath, options = {}) {
     "Force a full reindex of the vault",
     {},
     async () => {
-      if (indexingPromise) return textResponse("Reindex already in progress. " + indexingMessage());
-      await fullIndex();
-      return textResponse(
+      if (ctx.isIndexingInFlight()) return ctx.textResponse("Reindex already in progress. " + ctx.indexingMessage());
+      await ctx.fullIndex();
+      const documents = ctx.getDocuments();
+      return ctx.textResponse(
         `Reindexed: ${documents.length} notes, ${documents.reduce((n, d) => n + d.chunks.length, 0)} chunks`
       );
     }
   );
+}
+
+// src/mcp/tools/inventory.ts
+var CURRENT_TOOL_INVENTORY = [
+  // search
+  { name: "search_semantic", description: "Vector similarity search \u2014 find notes similar to a query by meaning.", group: "search" },
+  { name: "search_text", description: "Full-text keyword or regex search across all notes with optional filters.", group: "search" },
+  { name: "search_graph", description: "Graph traversal \u2014 find notes connected to a concept via wikilinks, related_docs, and tags.", group: "search" },
+  { name: "search_hybrid", description: "Combined semantic + graph search \u2014 vector results re-ranked by graph proximity and load_priority.", group: "search" },
+  // read
+  { name: "read_note", description: "Read the full content of a specific note by path.", group: "read" },
+  { name: "read_multiple_notes", description: "Batch read multiple notes in one call.", group: "read", deprecated: true },
+  { name: "list_notes", description: "List all indexed notes with metadata.", group: "read" },
+  // write (CRUD)
+  { name: "create_note", description: "Create a new markdown note.", group: "write" },
+  { name: "update_note", description: "Edit note content \u2014 overwrite, append, prepend, or patch by heading.", group: "write" },
+  { name: "delete_note", description: "Delete a note permanently.", group: "write" },
+  { name: "move_note", description: "Move or rename a note \u2014 updates wikilinks across the vault.", group: "write" },
+  // patch / synthesis
+  { name: "apply_patch", description: "Atomic multi-note patch with rollback.", group: "patch" },
+  { name: "synthesize_note", description: "Turn a researched answer + sources into a new filed note with provenance frontmatter. Pass proposal:true for review-first workflows.", group: "patch" },
+  { name: "synthesize_promote", description: "Move a reviewed proposal note to its canonical destination, stripping proposal markers.", group: "patch" },
+  { name: "ingest_source", description: "Build + apply a ChangeSet that ingests a source and the notes extracted from it.", group: "patch" },
+  { name: "install_schema", description: "Bootstrap vault.schema.yml in the vault root with the default schema.", group: "patch" },
+  // lint
+  { name: "find_schema_violations", description: "Scan for schema violations.", group: "lint", deprecated: true },
+  { name: "find_missing_provenance", description: "Scan for notes lacking sources/derived_from.", group: "lint", deprecated: true },
+  { name: "find_stale", description: "Scan for notes whose last_verified is older than the threshold.", group: "lint", deprecated: true },
+  { name: "find_broken_links", description: "Scan for [[wikilinks]] pointing to non-existent notes.", group: "lint", deprecated: true },
+  { name: "lint_vault", description: "Run lint rules across the vault. Pass `checks` to filter to specific rules.", group: "lint" },
+  // log
+  { name: "log_event", description: "Append a structured event to the vault's log.md.", group: "log" },
+  { name: "log_query", description: "Read structured log entries filtered by kind and/or date range.", group: "log" },
+  { name: "regenerate_index", description: "Force regeneration of INDEX.md for one or more directories.", group: "log" },
+  // metadata
+  { name: "get_frontmatter", description: "Read parsed YAML frontmatter from a note as JSON.", group: "metadata" },
+  { name: "update_frontmatter", description: "Set or delete YAML frontmatter keys.", group: "metadata" },
+  { name: "manage_tags", description: "Add, remove, list, or rename tags on a note.", group: "metadata" },
+  { name: "rename_tag", description: "Rename a tag across all notes.", group: "metadata", deprecated: true },
+  // graph
+  { name: "backlinks", description: "Find all notes that link TO a given note.", group: "graph" },
+  { name: "forwardlinks", description: "Find all notes linked FROM a given note.", group: "graph" },
+  { name: "graph_path", description: "Find the shortest path between two notes in the knowledge graph.", group: "graph" },
+  { name: "graph_statistics", description: "Knowledge graph stats \u2014 most connected nodes, orphans, density.", group: "graph" },
+  // system
+  { name: "get_stats", description: "Vault and index statistics.", group: "system" },
+  { name: "reindex", description: "Force a full reindex of the vault.", group: "system" },
+  // contract (Phase 3)
+  { name: "regenerate_contract", description: "Generate or refresh AGENTS.md at the project root with a managed-block contract.", group: "contract" },
+  { name: "inspect_contract", description: "Read-only inspection of AGENTS.md state.", group: "contract" },
+  // session (Phase 5)
+  { name: "session_start", description: "Open a verification-gated session for a multi-step task.", group: "session" },
+  { name: "session_run", description: "Run a verification command inside the active session, capture exit and tail.", group: "session" },
+  { name: "session_finish", description: "Close the active session \u2014 hard-gated on verifications unless explicitly waived.", group: "session" },
+  { name: "session_status", description: "Read-only inspection of the active session.", group: "session" }
+];
+
+// src/mcp/tools/contract.ts
+function registerContractTools(server, ctx) {
+  if (ctx.options.readOnly) return;
+  server.tool(
+    "regenerate_contract",
+    "Generate or refresh AGENTS.md at the project root with a managed-block contract. Preserves the 'Local Notes' tail across regenerations. Refuses to overwrite hand-edits inside the managed block unless force=true. Returns the path written and whether hand-edits were detected.",
+    {
+      projectRoot: external_exports.string().optional().describe("Override the project root path. Defaults to the parent of the vault directory if not provided."),
+      force: external_exports.boolean().optional().default(false).describe("Overwrite hand-edited managed-block content.")
+    },
+    async ({ projectRoot, force }) => {
+      const root = projectRoot ?? defaultProjectRoot(ctx.notesPath);
+      const tools = CURRENT_TOOL_INVENTORY.map((t) => ({
+        name: t.name,
+        description: t.description,
+        deprecated: t.deprecated
+      }));
+      const modes = [
+        { name: "vault-first", description: "Project-scoped prose questions trigger vault consultation with cite-or-deflect.", isDefault: true },
+        { name: "research", description: "Every source introduced is filed via ingest_source; mandatory synthesize_note on exit." },
+        { name: "outage-silence", description: "No proactive vault search. Terse responses. Postmortem synthesize_note on exit." }
+      ];
+      const result = await regenerateAgentsContract({
+        projectRoot: root,
+        pluginVersion: "1.1.0",
+        tools,
+        modes,
+        force
+      });
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+  server.tool(
+    "inspect_contract",
+    "Read-only inspection of AGENTS.md state \u2014 whether it exists, whether the managed-block markers are present, and how much Local Notes content is preserved.",
+    {
+      projectRoot: external_exports.string().optional().describe("Override the project root path. Defaults to the parent of the vault directory if not provided.")
+    },
+    async ({ projectRoot }) => {
+      const root = projectRoot ?? defaultProjectRoot(ctx.notesPath);
+      const result = await inspectAgentsContract(root);
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+}
+function defaultProjectRoot(notesPath) {
+  if (notesPath.endsWith("/.claude/.vault") || notesPath.endsWith("\\.claude\\.vault")) {
+    return notesPath.slice(0, -".claude/.vault".length);
+  }
+  return notesPath;
+}
+
+// src/mcp/tools/session.ts
+function registerSessionTools(server, ctx) {
+  if (ctx.options.readOnly) return;
+  server.tool(
+    "session_start",
+    "Open a verification-gated session for a multi-step task. State persists at .claude/.semantic-memory/session.json. Refuses if a session is already open with a different task. Calling with the same task as an open session returns the existing id (idempotent).",
+    {
+      task: external_exports.string().describe("Short description of the task being worked on. Recorded in session state and surfaced at session_finish.")
+    },
+    async ({ task }) => {
+      const result = await ctx.sessions.start(task);
+      if (result.ok) {
+        await logEvent(ctx.notesPath, {
+          kind: "session",
+          summary: result.reused ? `resumed session ${result.id}` : `started session ${result.id}`,
+          payload: { tool: "session_start", id: result.id, task, reused: !!result.reused }
+        }).catch(() => {
+        });
+      }
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+  server.tool(
+    "session_run",
+    "Run a verification command inside the active session. Captures exit code, signal, duration, and a tail of stdout+stderr. Refused when no session is open. Default timeout: 5 minutes.",
+    {
+      cmd: external_exports.string().describe("Shell command to run, e.g. 'npm test' or 'go test ./...'."),
+      timeout_ms: external_exports.coerce.number().int().positive().optional().describe("Override the default 5-minute timeout (in milliseconds).")
+    },
+    async ({ cmd, timeout_ms }) => {
+      const result = await ctx.sessions.run(cmd, timeout_ms);
+      if (result.ok) {
+        await logEvent(ctx.notesPath, {
+          kind: "session",
+          summary: `ran ${cmd} \u2192 exit=${result.record.exit ?? "(killed)"}`,
+          payload: {
+            tool: "session_run",
+            cmd,
+            exit: result.record.exit,
+            signal: result.record.signal,
+            duration_ms: result.record.duration_ms
+          }
+        }).catch(() => {
+        });
+      }
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+  server.tool(
+    "session_finish",
+    "Close the active session. HARD GATED: refused without recorded verifications unless verified=false is passed with a `reason` waiving verification (e.g. for prose-only edits). Deletes session state on success.",
+    {
+      summary: external_exports.string().describe("One-line description of what was accomplished. Appears in the closeout log entry."),
+      verified: external_exports.boolean().optional().default(true).describe("Pass false to explicitly waive verification (requires `reason`)."),
+      reason: external_exports.string().optional().describe("Required when verified=false. Why verification is not applicable to this task.")
+    },
+    async ({ summary, verified, reason }) => {
+      const result = await ctx.sessions.finish({ summary, verified, reason });
+      if (result.ok) {
+        await logEvent(ctx.notesPath, {
+          kind: "session",
+          summary: `finished session ${result.closed.id}: ${summary}`,
+          payload: {
+            tool: "session_finish",
+            id: result.closed.id,
+            task: result.closed.task,
+            verifications: result.closed.verifications.length,
+            verified_waived: !!result.closed.closed_verified_waived,
+            ...result.closed.closed_verified_waived && { waiver_reason: result.closed.closed_waiver_reason }
+          }
+        }).catch(() => {
+        });
+      }
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+  server.tool(
+    "session_status",
+    "Read-only inspection of the active session \u2014 task, verifications, notes_touched, and a state label (active | stale | no_session). 'stale' indicates last_activity_at >24h ago.",
+    {},
+    async () => {
+      const result = await ctx.sessions.status();
+      return ctx.textResponse(JSON.stringify(result, null, 2));
+    }
+  );
+}
+
+// src/mcp/server.ts
+async function createServer(notesPath, options = {}) {
+  const ctx = await buildContext(notesPath, options);
+  const server = new McpServer({
+    name: "semantic-memory",
+    version: "1.0.0"
+  });
+  registerSearchTools(server, ctx);
+  registerReadTools(server, ctx);
+  registerWriteTools(server, ctx);
+  registerPatchTools(server, ctx);
+  registerLintTools(server, ctx);
+  registerLogTools(server, ctx);
+  registerMetadataTools(server, ctx);
+  registerGraphTools(server, ctx);
+  registerSystemTools(server, ctx);
+  registerContractTools(server, ctx);
+  registerSessionTools(server, ctx);
   if (options.waitForReady) {
-    await tryLoadCachedIndex();
-    await fullIndex();
+    await ctx.tryLoadCachedIndex();
+    await ctx.fullIndex();
   } else {
-    tryLoadCachedIndex().then((cached) => {
-      if (!cached) backgroundIndex();
+    ctx.tryLoadCachedIndex().then((cached) => {
+      if (!cached) ctx.backgroundIndex();
     }).catch((err) => {
       process.stderr.write(`Startup error: ${err?.message ?? err}
 `);
-      backgroundIndex();
+      ctx.backgroundIndex();
     });
   }
   if (options.watch !== false) {
     const watcher = new Watcher(notesPath);
     watcher.on("changed", () => {
-      backgroundIndex();
+      ctx.backgroundIndex();
     });
     watcher.start();
   }