@velvetmonkey/flywheel-memory 2.0.18 → 2.0.19

package/dist/index.js

@@ -23,8 +23,8 @@ var init_constants = __esm({
 });
 
 // src/core/write/writer.ts
-import fs15 from "fs/promises";
-import path15 from "path";
+import fs17 from "fs/promises";
+import path16 from "path";
 import matter5 from "gray-matter";
 function isSensitivePath(filePath) {
   const normalizedPath = filePath.replace(/\\/g, "/");
@@ -345,8 +345,8 @@ function validatePath(vaultPath2, notePath) {
   if (notePath.startsWith("\\")) {
     return false;
   }
-  const resolvedVault = path15.resolve(vaultPath2);
-  const resolvedNote = path15.resolve(vaultPath2, notePath);
+  const resolvedVault = path16.resolve(vaultPath2);
+  const resolvedNote = path16.resolve(vaultPath2, notePath);
   return resolvedNote.startsWith(resolvedVault);
 }
 async function validatePathSecure(vaultPath2, notePath) {
@@ -374,8 +374,8 @@ async function validatePathSecure(vaultPath2, notePath) {
       reason: "Path traversal not allowed"
     };
   }
-  const resolvedVault = path15.resolve(vaultPath2);
-  const resolvedNote = path15.resolve(vaultPath2, notePath);
+  const resolvedVault = path16.resolve(vaultPath2);
+  const resolvedNote = path16.resolve(vaultPath2, notePath);
   if (!resolvedNote.startsWith(resolvedVault)) {
     return {
       valid: false,
@@ -389,18 +389,18 @@ async function validatePathSecure(vaultPath2, notePath) {
     };
   }
   try {
-    const fullPath = path15.join(vaultPath2, notePath);
+    const fullPath = path16.join(vaultPath2, notePath);
     try {
-      await fs15.access(fullPath);
-      const realPath = await fs15.realpath(fullPath);
-      const realVaultPath = await fs15.realpath(vaultPath2);
+      await fs17.access(fullPath);
+      const realPath = await fs17.realpath(fullPath);
+      const realVaultPath = await fs17.realpath(vaultPath2);
       if (!realPath.startsWith(realVaultPath)) {
         return {
           valid: false,
           reason: "Symlink target is outside vault"
         };
       }
-      const relativePath = path15.relative(realVaultPath, realPath);
+      const relativePath = path16.relative(realVaultPath, realPath);
       if (isSensitivePath(relativePath)) {
         return {
           valid: false,
@@ -408,11 +408,11 @@ async function validatePathSecure(vaultPath2, notePath) {
         };
       }
     } catch {
-      const parentDir = path15.dirname(fullPath);
+      const parentDir = path16.dirname(fullPath);
       try {
-        await fs15.access(parentDir);
-        const realParentPath = await fs15.realpath(parentDir);
-        const realVaultPath = await fs15.realpath(vaultPath2);
+        await fs17.access(parentDir);
+        const realParentPath = await fs17.realpath(parentDir);
+        const realVaultPath = await fs17.realpath(vaultPath2);
         if (!realParentPath.startsWith(realVaultPath)) {
           return {
             valid: false,
@@ -434,8 +434,8 @@ async function readVaultFile(vaultPath2, notePath) {
   if (!validatePath(vaultPath2, notePath)) {
     throw new Error("Invalid path: path traversal not allowed");
   }
-  const fullPath = path15.join(vaultPath2, notePath);
-  const rawContent = await fs15.readFile(fullPath, "utf-8");
+  const fullPath = path16.join(vaultPath2, notePath);
+  const rawContent = await fs17.readFile(fullPath, "utf-8");
   const lineEnding = detectLineEnding(rawContent);
   const normalizedContent = normalizeLineEndings(rawContent);
   const parsed = matter5(normalizedContent);
@@ -483,11 +483,11 @@ async function writeVaultFile(vaultPath2, notePath, content, frontmatter, lineEn
   if (!validation.valid) {
     throw new Error(`Invalid path: ${validation.reason}`);
   }
-  const fullPath = path15.join(vaultPath2, notePath);
+  const fullPath = path16.join(vaultPath2, notePath);
   let output = matter5.stringify(content, frontmatter);
   output = normalizeTrailingNewline(output);
   output = convertLineEndings(output, lineEnding);
-  await fs15.writeFile(fullPath, output, "utf-8");
+  await fs17.writeFile(fullPath, output, "utf-8");
 }
 function removeFromSection(content, section, pattern, mode = "first", useRegex = false) {
   const lines = content.split("\n");
@@ -711,8 +711,8 @@ function createContext(variables = {}) {
     }
   };
 }
-function resolvePath(obj, path25) {
-  const parts = path25.split(".");
+function resolvePath(obj, path28) {
+  const parts = path28.split(".");
   let current = obj;
   for (const part of parts) {
     if (current === void 0 || current === null) {
@@ -1150,8 +1150,8 @@ __export(conditions_exports, {
   evaluateCondition: () => evaluateCondition,
   shouldStepExecute: () => shouldStepExecute
 });
-import fs21 from "fs/promises";
-import path21 from "path";
+import fs23 from "fs/promises";
+import path22 from "path";
 async function evaluateCondition(condition, vaultPath2, context) {
   const interpolatedPath = condition.path ? interpolate(condition.path, context) : void 0;
   const interpolatedSection = condition.section ? interpolate(condition.section, context) : void 0;
@@ -1204,9 +1204,9 @@ async function evaluateCondition(condition, vaultPath2, context) {
   }
 }
 async function evaluateFileExists(vaultPath2, notePath, expectExists) {
-  const fullPath = path21.join(vaultPath2, notePath);
+  const fullPath = path22.join(vaultPath2, notePath);
   try {
-    await fs21.access(fullPath);
+    await fs23.access(fullPath);
     return {
       met: expectExists,
       reason: expectExists ? `File exists: ${notePath}` : `File exists (expected not to): ${notePath}`
@@ -1219,9 +1219,9 @@ async function evaluateFileExists(vaultPath2, notePath, expectExists) {
   }
 }
 async function evaluateSectionExists(vaultPath2, notePath, sectionName, expectExists) {
-  const fullPath = path21.join(vaultPath2, notePath);
+  const fullPath = path22.join(vaultPath2, notePath);
   try {
-    await fs21.access(fullPath);
+    await fs23.access(fullPath);
   } catch {
     return {
       met: !expectExists,
@@ -1250,9 +1250,9 @@ async function evaluateSectionExists(vaultPath2, notePath, sectionName, expectEx
   }
 }
 async function evaluateFrontmatterExists(vaultPath2, notePath, fieldName, expectExists) {
-  const fullPath = path21.join(vaultPath2, notePath);
+  const fullPath = path22.join(vaultPath2, notePath);
   try {
-    await fs21.access(fullPath);
+    await fs23.access(fullPath);
   } catch {
     return {
       met: !expectExists,
@@ -1281,9 +1281,9 @@ async function evaluateFrontmatterExists(vaultPath2, notePath, fieldName, expect
   }
 }
 async function evaluateFrontmatterEquals(vaultPath2, notePath, fieldName, expectedValue) {
-  const fullPath = path21.join(vaultPath2, notePath);
+  const fullPath = path22.join(vaultPath2, notePath);
   try {
-    await fs21.access(fullPath);
+    await fs23.access(fullPath);
   } catch {
     return {
       met: false,
@@ -1424,6 +1424,7 @@ var init_taskHelpers = __esm({
 });
 
 // src/index.ts
+import * as path27 from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -1689,8 +1690,8 @@ function updateIndexProgress(parsed, total) {
 function normalizeTarget(target) {
   return target.toLowerCase().replace(/\.md$/, "");
 }
-function normalizeNotePath(path25) {
-  return path25.toLowerCase().replace(/\.md$/, "");
+function normalizeNotePath(path28) {
+  return path28.toLowerCase().replace(/\.md$/, "");
 }
 async function buildVaultIndex(vaultPath2, options = {}) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, onProgress } = options;
@@ -1884,7 +1885,7 @@ function findSimilarEntity(index, target) {
   }
   const maxDist = normalizedLen <= 10 ? 1 : 2;
   let bestMatch;
-  for (const [entity, path25] of index.entities) {
+  for (const [entity, path28] of index.entities) {
     const lenDiff = Math.abs(entity.length - normalizedLen);
     if (lenDiff > maxDist) {
       continue;
@@ -1892,7 +1893,7 @@ function findSimilarEntity(index, target) {
     const dist = levenshteinDistance(normalized, entity);
     if (dist > 0 && dist <= maxDist) {
       if (!bestMatch || dist < bestMatch.distance) {
-        bestMatch = { path: path25, entity, distance: dist };
+        bestMatch = { path: path28, entity, distance: dist };
         if (dist === 1) {
           return bestMatch;
         }
@@ -2354,30 +2355,30 @@ var EventQueue = class {
    * Add a new event to the queue
    */
   push(type, rawPath) {
-    const path25 = normalizePath(rawPath);
+    const path28 = normalizePath(rawPath);
     const now = Date.now();
     const event = {
       type,
-      path: path25,
+      path: path28,
       timestamp: now
     };
-    let pending = this.pending.get(path25);
+    let pending = this.pending.get(path28);
     if (!pending) {
       pending = {
         events: [],
         timer: null,
         lastEvent: now
       };
-      this.pending.set(path25, pending);
+      this.pending.set(path28, pending);
     }
     pending.events.push(event);
     pending.lastEvent = now;
-    console.error(`[flywheel] QUEUE: pushed ${type} for ${path25}, pending=${this.pending.size}`);
+    console.error(`[flywheel] QUEUE: pushed ${type} for ${path28}, pending=${this.pending.size}`);
     if (pending.timer) {
       clearTimeout(pending.timer);
     }
     pending.timer = setTimeout(() => {
-      this.flushPath(path25);
+      this.flushPath(path28);
     }, this.config.debounceMs);
     if (this.pending.size >= this.config.batchSize) {
       this.flush();
@@ -2398,10 +2399,10 @@ var EventQueue = class {
   /**
    * Flush a single path's events
    */
-  flushPath(path25) {
-    const pending = this.pending.get(path25);
+  flushPath(path28) {
+    const pending = this.pending.get(path28);
     if (!pending || pending.events.length === 0) return;
-    console.error(`[flywheel] QUEUE: flushing ${path25}, events=${pending.events.length}`);
+    console.error(`[flywheel] QUEUE: flushing ${path28}, events=${pending.events.length}`);
     if (pending.timer) {
       clearTimeout(pending.timer);
       pending.timer = null;
@@ -2410,7 +2411,7 @@ var EventQueue = class {
     if (coalescedType) {
       const coalesced = {
         type: coalescedType,
-        path: path25,
+        path: path28,
         originalEvents: [...pending.events]
       };
       this.onBatch({
@@ -2418,7 +2419,7 @@ var EventQueue = class {
         timestamp: Date.now()
       });
     }
-    this.pending.delete(path25);
+    this.pending.delete(path28);
   }
   /**
    * Flush all pending events
@@ -2430,7 +2431,7 @@ var EventQueue = class {
     }
     if (this.pending.size === 0) return;
     const events = [];
-    for (const [path25, pending] of this.pending) {
+    for (const [path28, pending] of this.pending) {
       if (pending.timer) {
         clearTimeout(pending.timer);
       }
@@ -2438,7 +2439,7 @@ var EventQueue = class {
       if (coalescedType) {
         events.push({
           type: coalescedType,
-          path: path25,
+          path: path28,
           originalEvents: [...pending.events]
         });
       }
@@ -2587,31 +2588,31 @@ function createVaultWatcher(options) {
         usePolling: config.usePolling,
         interval: config.usePolling ? config.pollInterval : void 0
       });
-      watcher.on("add", (path25) => {
-        console.error(`[flywheel] RAW EVENT: add ${path25}`);
-        if (shouldWatch(path25, vaultPath2)) {
-          console.error(`[flywheel] ACCEPTED: add ${path25}`);
-          eventQueue.push("add", path25);
+      watcher.on("add", (path28) => {
+        console.error(`[flywheel] RAW EVENT: add ${path28}`);
+        if (shouldWatch(path28, vaultPath2)) {
+          console.error(`[flywheel] ACCEPTED: add ${path28}`);
+          eventQueue.push("add", path28);
         } else {
-          console.error(`[flywheel] FILTERED: add ${path25}`);
+          console.error(`[flywheel] FILTERED: add ${path28}`);
         }
       });
-      watcher.on("change", (path25) => {
-        console.error(`[flywheel] RAW EVENT: change ${path25}`);
-        if (shouldWatch(path25, vaultPath2)) {
-          console.error(`[flywheel] ACCEPTED: change ${path25}`);
-          eventQueue.push("change", path25);
+      watcher.on("change", (path28) => {
+        console.error(`[flywheel] RAW EVENT: change ${path28}`);
+        if (shouldWatch(path28, vaultPath2)) {
+          console.error(`[flywheel] ACCEPTED: change ${path28}`);
+          eventQueue.push("change", path28);
         } else {
-          console.error(`[flywheel] FILTERED: change ${path25}`);
+          console.error(`[flywheel] FILTERED: change ${path28}`);
         }
       });
-      watcher.on("unlink", (path25) => {
-        console.error(`[flywheel] RAW EVENT: unlink ${path25}`);
-        if (shouldWatch(path25, vaultPath2)) {
-          console.error(`[flywheel] ACCEPTED: unlink ${path25}`);
-          eventQueue.push("unlink", path25);
+      watcher.on("unlink", (path28) => {
+        console.error(`[flywheel] RAW EVENT: unlink ${path28}`);
+        if (shouldWatch(path28, vaultPath2)) {
+          console.error(`[flywheel] ACCEPTED: unlink ${path28}`);
+          eventQueue.push("unlink", path28);
         } else {
-          console.error(`[flywheel] FILTERED: unlink ${path25}`);
+          console.error(`[flywheel] FILTERED: unlink ${path28}`);
         }
       });
       watcher.on("ready", () => {
@@ -2901,10 +2902,10 @@ function getAllFeedbackBoosts(stateDb2, folder) {
   for (const row of globalRows) {
     let accuracy;
     let sampleCount;
-    const fs25 = folderStats?.get(row.entity);
-    if (fs25 && fs25.count >= FEEDBACK_BOOST_MIN_SAMPLES) {
-      accuracy = fs25.accuracy;
-      sampleCount = fs25.count;
+    const fs28 = folderStats?.get(row.entity);
+    if (fs28 && fs28.count >= FEEDBACK_BOOST_MIN_SAMPLES) {
+      accuracy = fs28.accuracy;
+      sampleCount = fs28.count;
     } else {
       accuracy = row.correct_count / row.total;
       sampleCount = row.total;
@@ -5271,11 +5272,228 @@ function getFTS5State() {
   return { ...state };
 }
 
+// src/core/read/embeddings.ts
+import * as crypto from "crypto";
+import * as fs7 from "fs";
+var MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+var EXCLUDED_DIRS3 = /* @__PURE__ */ new Set([
+  ".obsidian",
+  ".trash",
+  ".git",
+  "node_modules",
+  "templates",
+  ".claude",
+  ".flywheel"
+]);
+var MAX_FILE_SIZE2 = 5 * 1024 * 1024;
+var db2 = null;
+var pipeline = null;
+var initPromise = null;
+function setEmbeddingsDatabase(database) {
+  db2 = database;
+}
+async function initEmbeddings() {
+  if (pipeline) return;
+  if (initPromise) return initPromise;
+  initPromise = (async () => {
+    try {
+      const transformers = await Function("specifier", "return import(specifier)")("@huggingface/transformers");
+      pipeline = await transformers.pipeline("feature-extraction", MODEL_ID, {
+        dtype: "fp32"
+      });
+    } catch (err) {
+      initPromise = null;
+      if (err instanceof Error && (err.message.includes("Cannot find package") || err.message.includes("MODULE_NOT_FOUND") || err.message.includes("Cannot find module") || err.message.includes("ERR_MODULE_NOT_FOUND"))) {
+        throw new Error(
+          "Semantic search requires @huggingface/transformers. Install it with: npm install @huggingface/transformers"
+        );
+      }
+      throw err;
+    }
+  })();
+  return initPromise;
+}
+async function embedText(text) {
+  await initEmbeddings();
+  const truncated = text.slice(0, 2e3);
+  const result = await pipeline(truncated, { pooling: "mean", normalize: true });
+  return new Float32Array(result.data);
+}
+function contentHash(content) {
+  return crypto.createHash("md5").update(content).digest("hex");
+}
+function shouldIndexFile2(filePath) {
+  const parts = filePath.split("/");
+  return !parts.some((part) => EXCLUDED_DIRS3.has(part));
+}
+async function buildEmbeddingsIndex(vaultPath2, onProgress) {
+  if (!db2) {
+    throw new Error("Embeddings database not initialized. Call setEmbeddingsDatabase() first.");
+  }
+  await initEmbeddings();
+  const files = await scanVault(vaultPath2);
+  const indexable = files.filter((f) => shouldIndexFile2(f.path));
+  const existingHashes = /* @__PURE__ */ new Map();
+  const rows = db2.prepare("SELECT path, content_hash FROM note_embeddings").all();
+  for (const row of rows) {
+    existingHashes.set(row.path, row.content_hash);
+  }
+  const upsert = db2.prepare(`
+    INSERT OR REPLACE INTO note_embeddings (path, embedding, content_hash, model, updated_at)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+  const progress = { total: indexable.length, current: 0, skipped: 0 };
+  for (const file of indexable) {
+    progress.current++;
+    try {
+      const stats = fs7.statSync(file.absolutePath);
+      if (stats.size > MAX_FILE_SIZE2) {
+        progress.skipped++;
+        continue;
+      }
+      const content = fs7.readFileSync(file.absolutePath, "utf-8");
+      const hash = contentHash(content);
+      if (existingHashes.get(file.path) === hash) {
+        progress.skipped++;
+        if (onProgress) onProgress(progress);
+        continue;
+      }
+      const embedding = await embedText(content);
+      const buf = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+      upsert.run(file.path, buf, hash, MODEL_ID, Date.now());
+    } catch {
+      progress.skipped++;
+    }
+    if (onProgress) onProgress(progress);
+  }
+  const currentPaths = new Set(indexable.map((f) => f.path));
+  const deleteStmt = db2.prepare("DELETE FROM note_embeddings WHERE path = ?");
+  for (const existingPath of existingHashes.keys()) {
+    if (!currentPaths.has(existingPath)) {
+      deleteStmt.run(existingPath);
+    }
+  }
+  console.error(`[Semantic] Indexed ${progress.current - progress.skipped} notes, skipped ${progress.skipped}`);
+  return progress;
+}
+async function updateEmbedding(notePath, absolutePath) {
+  if (!db2) return;
+  try {
+    const content = fs7.readFileSync(absolutePath, "utf-8");
+    const hash = contentHash(content);
+    const existing = db2.prepare("SELECT content_hash FROM note_embeddings WHERE path = ?").get(notePath);
+    if (existing?.content_hash === hash) return;
+    const embedding = await embedText(content);
+    const buf = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+    db2.prepare(`
+      INSERT OR REPLACE INTO note_embeddings (path, embedding, content_hash, model, updated_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(notePath, buf, hash, MODEL_ID, Date.now());
+  } catch {
+  }
+}
+function removeEmbedding(notePath) {
+  if (!db2) return;
+  db2.prepare("DELETE FROM note_embeddings WHERE path = ?").run(notePath);
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denom === 0) return 0;
+  return dot / denom;
+}
+async function semanticSearch(query, limit = 10) {
+  if (!db2) {
+    throw new Error("Embeddings database not initialized. Call setEmbeddingsDatabase() first.");
+  }
+  const queryEmbedding = await embedText(query);
+  const rows = db2.prepare("SELECT path, embedding FROM note_embeddings").all();
+  const scored = [];
+  for (const row of rows) {
+    const noteEmbedding = new Float32Array(
+      row.embedding.buffer,
+      row.embedding.byteOffset,
+      row.embedding.byteLength / Float32Array.BYTES_PER_ELEMENT
+    );
+    const score = cosineSimilarity(queryEmbedding, noteEmbedding);
+    const title = row.path.replace(/\.md$/, "").split("/").pop() || row.path;
+    scored.push({ path: row.path, title, score: Math.round(score * 1e3) / 1e3 });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
+async function findSemanticallySimilar(sourcePath, limit = 10, excludePaths) {
+  if (!db2) {
+    throw new Error("Embeddings database not initialized. Call setEmbeddingsDatabase() first.");
+  }
+  const sourceRow = db2.prepare("SELECT embedding FROM note_embeddings WHERE path = ?").get(sourcePath);
+  if (!sourceRow) {
+    return [];
+  }
+  const sourceEmbedding = new Float32Array(
+    sourceRow.embedding.buffer,
+    sourceRow.embedding.byteOffset,
+    sourceRow.embedding.byteLength / Float32Array.BYTES_PER_ELEMENT
+  );
+  const rows = db2.prepare("SELECT path, embedding FROM note_embeddings WHERE path != ?").all(sourcePath);
+  const scored = [];
+  for (const row of rows) {
+    if (excludePaths?.has(row.path)) continue;
+    const noteEmbedding = new Float32Array(
+      row.embedding.buffer,
+      row.embedding.byteOffset,
+      row.embedding.byteLength / Float32Array.BYTES_PER_ELEMENT
+    );
+    const score = cosineSimilarity(sourceEmbedding, noteEmbedding);
+    const title = row.path.replace(/\.md$/, "").split("/").pop() || row.path;
+    scored.push({ path: row.path, title, score: Math.round(score * 1e3) / 1e3 });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
+function reciprocalRankFusion(...lists) {
+  const k = 60;
+  const scores = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const item = list[rank];
+      const rrfScore = 1 / (k + rank + 1);
+      scores.set(item.path, (scores.get(item.path) || 0) + rrfScore);
+    }
+  }
+  return scores;
+}
+function hasEmbeddingsIndex() {
+  if (!db2) return false;
+  try {
+    const row = db2.prepare("SELECT COUNT(*) as count FROM note_embeddings").get();
+    return row.count > 0;
+  } catch {
+    return false;
+  }
+}
+function getEmbeddingsCount() {
+  if (!db2) return 0;
+  try {
+    const row = db2.prepare("SELECT COUNT(*) as count FROM note_embeddings").get();
+    return row.count;
+  } catch {
+    return 0;
+  }
+}
+
 // src/index.ts
-import { openStateDb, scanVaultEntities as scanVaultEntities3 } from "@velvetmonkey/vault-core";
+import { openStateDb, scanVaultEntities as scanVaultEntities3, getSessionId } from "@velvetmonkey/vault-core";
 
 // src/tools/read/graph.ts
-import * as fs7 from "fs";
+import * as fs8 from "fs";
 import * as path8 from "path";
 import { z } from "zod";
 
@@ -5561,7 +5779,7 @@ function requireIndex() {
 async function getContext(vaultPath2, sourcePath, line, contextLines = 1) {
   try {
     const fullPath = path8.join(vaultPath2, sourcePath);
-    const content = await fs7.promises.readFile(fullPath, "utf-8");
+    const content = await fs8.promises.readFile(fullPath, "utf-8");
     const lines = content.split("\n");
     const startLine = Math.max(0, line - 1 - contextLines);
     const endLine = Math.min(lines.length, line + contextLines);
@@ -5864,14 +6082,14 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
   };
   function findSimilarEntity2(target, entities) {
     const targetLower = target.toLowerCase();
-    for (const [name, path25] of entities) {
+    for (const [name, path28] of entities) {
       if (name.startsWith(targetLower) || targetLower.startsWith(name)) {
-        return path25;
+        return path28;
       }
     }
-    for (const [name, path25] of entities) {
+    for (const [name, path28] of entities) {
       if (name.includes(targetLower) || targetLower.includes(name)) {
-        return path25;
+        return path28;
       }
     }
     return void 0;
@@ -5953,7 +6171,7 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
 }
 
 // src/tools/read/health.ts
-import * as fs8 from "fs";
+import * as fs9 from "fs";
 import { z as z3 } from "zod";
 
 // src/tools/read/periodic.ts
@@ -6316,7 +6534,7 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
       const indexErrorObj = getIndexError();
       let vaultAccessible = false;
       try {
-        fs8.accessSync(vaultPath2, fs8.constants.R_OK);
+        fs9.accessSync(vaultPath2, fs9.constants.R_OK);
         vaultAccessible = true;
       } catch {
         vaultAccessible = false;
@@ -6447,8 +6665,8 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
       daily_counts: z3.record(z3.number())
     }).describe("Activity summary for the last 7 days")
   };
-  function isPeriodicNote(path25) {
-    const filename = path25.split("/").pop() || "";
+  function isPeriodicNote(path28) {
+    const filename = path28.split("/").pop() || "";
     const nameWithoutExt = filename.replace(/\.md$/, "");
     const patterns = [
       /^\d{4}-\d{2}-\d{2}$/,
@@ -6463,7 +6681,7 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
       // YYYY (yearly)
     ];
     const periodicFolders = ["daily", "weekly", "monthly", "quarterly", "yearly", "journal", "journals"];
-    const folder = path25.split("/")[0]?.toLowerCase() || "";
+    const folder = path28.split("/")[0]?.toLowerCase() || "";
     return patterns.some((p) => p.test(nameWithoutExt)) || periodicFolders.includes(folder);
   }
   server2.registerTool(
@@ -6632,10 +6850,10 @@ function sortNotes(notes, sortBy, order) {
 function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
   server2.tool(
     "search",
-    'Search the vault across metadata, content, and entities. Scope controls what to search: "metadata" for frontmatter/tags/folders, "content" for full-text search (FTS5), "entities" for people/projects/technologies, "all" (default) tries metadata then falls back to content search.\n\nExample: search({ query: "quarterly review", scope: "content", limit: 5 })\nExample: search({ where: { type: "project", status: "active" }, scope: "metadata" })',
+    'Search the vault across metadata, content, and entities. Scope controls what to search: "metadata" for frontmatter/tags/folders, "content" for full-text search (FTS5), "entities" for people/projects/technologies, "all" (default) tries metadata then falls back to content search. When embeddings have been built (via init_semantic), content and all scopes automatically include embedding-based results via hybrid ranking.\n\nExample: search({ query: "quarterly review", scope: "content", limit: 5 })\nExample: search({ where: { type: "project", status: "active" }, scope: "metadata" })',
     {
       query: z4.string().optional().describe('Search query text. Required for scope "content", "entities", "all". For "metadata" scope, use filters instead.'),
-      scope: z4.enum(["metadata", "content", "entities", "all"]).default("all").describe("What to search: metadata (frontmatter/tags/folders), content (FTS5 full-text), entities (people/projects), all (metadata then content)"),
+      scope: z4.enum(["metadata", "content", "entities", "all"]).default("all").describe("What to search: metadata (frontmatter/tags/folders), content (FTS5 full-text), entities (people/projects), all (metadata then content). Semantic results are automatically included when embeddings have been built (via init_semantic)."),
       // Metadata filters (used with scope "metadata" or "all")
       where: z4.record(z4.unknown()).optional().describe('Frontmatter filters as key-value pairs. Example: { "type": "project", "status": "active" }'),
       has_tag: z4.string().optional().describe("Filter to notes with this tag"),
@@ -6744,12 +6962,42 @@ function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
           console.error("[FTS5] Index stale or missing, rebuilding...");
           await buildFTS5Index(vaultPath2);
         }
-        const results = searchFTS5(vaultPath2, query, limit);
+        const fts5Results = searchFTS5(vaultPath2, query, limit);
+        if (hasEmbeddingsIndex()) {
+          try {
+            const semanticResults = await semanticSearch(query, limit);
+            const fts5Ranked = fts5Results.map((r) => ({ path: r.path, title: r.title, snippet: r.snippet }));
+            const semanticRanked = semanticResults.map((r) => ({ path: r.path, title: r.title }));
+            const rrfScores = reciprocalRankFusion(fts5Ranked, semanticRanked);
+            const allPaths = /* @__PURE__ */ new Set([...fts5Results.map((r) => r.path), ...semanticResults.map((r) => r.path)]);
+            const fts5Map = new Map(fts5Results.map((r) => [r.path, r]));
+            const semanticMap = new Map(semanticResults.map((r) => [r.path, r]));
+            const merged = Array.from(allPaths).map((p) => ({
+              path: p,
+              title: fts5Map.get(p)?.title || semanticMap.get(p)?.title || p.replace(/\.md$/, "").split("/").pop() || p,
+              snippet: fts5Map.get(p)?.snippet,
+              rrf_score: Math.round((rrfScores.get(p) || 0) * 1e4) / 1e4,
+              in_fts5: fts5Map.has(p),
+              in_semantic: semanticMap.has(p)
+            }));
+            merged.sort((a, b) => b.rrf_score - a.rrf_score);
+            return { content: [{ type: "text", text: JSON.stringify({
+              scope,
+              method: "hybrid",
+              query,
+              total_results: Math.min(merged.length, limit),
+              results: merged.slice(0, limit)
+            }, null, 2) }] };
+          } catch (err) {
+            console.error("[Semantic] Hybrid search failed, falling back to FTS5:", err instanceof Error ? err.message : err);
+          }
+        }
         return { content: [{ type: "text", text: JSON.stringify({
           scope: "content",
+          method: "fts5",
           query,
-          total_results: results.length,
-          results
+          total_results: fts5Results.length,
+          results: fts5Results
         }, null, 2) }] };
       }
       return { content: [{ type: "text", text: JSON.stringify({ error: "Invalid scope" }, null, 2) }] };
@@ -6758,7 +7006,7 @@ function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
 }
 
 // src/tools/read/system.ts
-import * as fs9 from "fs";
+import * as fs10 from "fs";
 import * as path9 from "path";
 import { z as z5 } from "zod";
 import { scanVaultEntities as scanVaultEntities2 } from "@velvetmonkey/vault-core";
@@ -6993,7 +7241,7 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
         }
         try {
           const fullPath = path9.join(vaultPath2, note.path);
-          const content = await fs9.promises.readFile(fullPath, "utf-8");
+          const content = await fs10.promises.readFile(fullPath, "utf-8");
           const lines = content.split("\n");
           for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
@@ -7109,7 +7357,7 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
       if (include_word_count) {
         try {
           const fullPath = path9.join(vaultPath2, resolvedPath);
-          const content = await fs9.promises.readFile(fullPath, "utf-8");
+          const content = await fs10.promises.readFile(fullPath, "utf-8");
           wordCount = content.split(/\s+/).filter((w) => w.length > 0).length;
         } catch {
         }
@@ -7211,7 +7459,7 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
 import { z as z6 } from "zod";
 
 // src/tools/read/structure.ts
-import * as fs10 from "fs";
+import * as fs11 from "fs";
 import * as path10 from "path";
 var HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
 function extractHeadings(content) {
@@ -7269,7 +7517,7 @@ async function getNoteStructure(index, notePath, vaultPath2) {
   const absolutePath = path10.join(vaultPath2, notePath);
   let content;
   try {
-    content = await fs10.promises.readFile(absolutePath, "utf-8");
+    content = await fs11.promises.readFile(absolutePath, "utf-8");
   } catch {
     return null;
   }
@@ -7292,7 +7540,7 @@ async function getSectionContent(index, notePath, headingText, vaultPath2, inclu
   const absolutePath = path10.join(vaultPath2, notePath);
   let content;
   try {
-    content = await fs10.promises.readFile(absolutePath, "utf-8");
+    content = await fs11.promises.readFile(absolutePath, "utf-8");
   } catch {
     return null;
   }
@@ -7334,7 +7582,7 @@ async function findSections(index, headingPattern, vaultPath2, folder) {
     const absolutePath = path10.join(vaultPath2, note.path);
     let content;
     try {
-      content = await fs10.promises.readFile(absolutePath, "utf-8");
+      content = await fs11.promises.readFile(absolutePath, "utf-8");
     } catch {
       continue;
     }
@@ -7354,7 +7602,7 @@ async function findSections(index, headingPattern, vaultPath2, folder) {
 }
 
 // src/tools/read/tasks.ts
-import * as fs11 from "fs";
+import * as fs12 from "fs";
 import * as path11 from "path";
 var TASK_REGEX = /^(\s*)- \[([ xX\-])\]\s+(.+)$/;
 var TAG_REGEX2 = /#([a-zA-Z][a-zA-Z0-9_/-]*)/g;
@@ -7381,7 +7629,7 @@ function extractDueDate(text) {
 async function extractTasksFromNote(notePath, absolutePath) {
   let content;
   try {
-    content = await fs11.promises.readFile(absolutePath, "utf-8");
+    content = await fs12.promises.readFile(absolutePath, "utf-8");
   } catch {
     return [];
   }
@@ -7486,18 +7734,18 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
         include_content: z6.boolean().default(false).describe("Include the text content under each top-level section")
       }
     },
-    async ({ path: path25, include_content }) => {
+    async ({ path: path28, include_content }) => {
       const index = getIndex();
       const vaultPath2 = getVaultPath();
-      const result = await getNoteStructure(index, path25, vaultPath2);
+      const result = await getNoteStructure(index, path28, vaultPath2);
       if (!result) {
         return {
-          content: [{ type: "text", text: JSON.stringify({ error: "Note not found", path: path25 }, null, 2) }]
+          content: [{ type: "text", text: JSON.stringify({ error: "Note not found", path: path28 }, null, 2) }]
         };
       }
       if (include_content) {
         for (const section of result.sections) {
-          const sectionResult = await getSectionContent(index, path25, section.heading.text, vaultPath2, true);
+          const sectionResult = await getSectionContent(index, path28, section.heading.text, vaultPath2, true);
           if (sectionResult) {
             section.content = sectionResult.content;
           }
@@ -7519,15 +7767,15 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
         include_subheadings: z6.boolean().default(true).describe("Include content under subheadings")
       }
     },
-    async ({ path: path25, heading, include_subheadings }) => {
+    async ({ path: path28, heading, include_subheadings }) => {
       const index = getIndex();
       const vaultPath2 = getVaultPath();
-      const result = await getSectionContent(index, path25, heading, vaultPath2, include_subheadings);
+      const result = await getSectionContent(index, path28, heading, vaultPath2, include_subheadings);
       if (!result) {
         return {
           content: [{ type: "text", text: JSON.stringify({
             error: "Section not found",
-            path: path25,
+            path: path28,
             heading
           }, null, 2) }]
         };
@@ -7581,16 +7829,16 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
         offset: z6.coerce.number().default(0).describe("Number of results to skip (for pagination)")
       }
     },
-    async ({ path: path25, status, has_due_date, folder, tag, limit: requestedLimit, offset }) => {
+    async ({ path: path28, status, has_due_date, folder, tag, limit: requestedLimit, offset }) => {
       const limit = Math.min(requestedLimit ?? 25, MAX_LIMIT);
       const index = getIndex();
       const vaultPath2 = getVaultPath();
       const config = getConfig();
-      if (path25) {
-        const result2 = await getTasksFromNote(index, path25, vaultPath2, config.exclude_task_tags || []);
+      if (path28) {
+        const result2 = await getTasksFromNote(index, path28, vaultPath2, config.exclude_task_tags || []);
         if (!result2) {
           return {
-            content: [{ type: "text", text: JSON.stringify({ error: "Note not found", path: path25 }, null, 2) }]
+            content: [{ type: "text", text: JSON.stringify({ error: "Note not found", path: path28 }, null, 2) }]
           };
         }
         let filtered = result2;
@@ -7600,7 +7848,7 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
         const paged2 = filtered.slice(offset, offset + limit);
         return {
           content: [{ type: "text", text: JSON.stringify({
-            path: path25,
+            path: path28,
             total_count: filtered.length,
             returned_count: paged2.length,
             open: result2.filter((t) => t.status === "open").length,
@@ -7715,7 +7963,7 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
 
 // src/tools/read/migrations.ts
 import { z as z7 } from "zod";
-import * as fs12 from "fs/promises";
+import * as fs13 from "fs/promises";
 import * as path12 from "path";
 import matter2 from "gray-matter";
 function getNotesInFolder(index, folder) {
@@ -7731,7 +7979,7 @@ function getNotesInFolder(index, folder) {
 async function readFileContent(notePath, vaultPath2) {
   const fullPath = path12.join(vaultPath2, notePath);
   try {
-    return await fs12.readFile(fullPath, "utf-8");
+    return await fs13.readFile(fullPath, "utf-8");
   } catch {
     return null;
   }
@@ -7739,7 +7987,7 @@ async function readFileContent(notePath, vaultPath2) {
 async function writeFileContent(notePath, vaultPath2, content) {
   const fullPath = path12.join(vaultPath2, notePath);
   try {
-    await fs12.writeFile(fullPath, content, "utf-8");
+    await fs13.writeFile(fullPath, content, "utf-8");
     return true;
   } catch {
     return false;
@@ -7917,324 +8165,33 @@ function registerMigrationTools(server2, getIndex, getVaultPath) {
 }
 
 // src/tools/read/graphAnalysis.ts
+import fs14 from "node:fs";
+import path13 from "node:path";
 import { z as z8 } from "zod";
-function registerGraphAnalysisTools(server2, getIndex, getVaultPath) {
-  server2.registerTool(
-    "graph_analysis",
-    {
-      title: "Graph Analysis",
-      description: 'Analyze vault link graph structure. Use analysis to pick the mode:\n- "orphans": Notes with no backlinks (disconnected content)\n- "dead_ends": Notes with backlinks but no outgoing links\n- "sources": Notes with outgoing links but no backlinks\n- "hubs": Highly connected notes (many links to/from)\n- "stale": Important notes (by backlink count) not recently modified\n\nExample: graph_analysis({ analysis: "hubs", limit: 10 })\nExample: graph_analysis({ analysis: "stale", days: 30, min_backlinks: 3 })',
-      inputSchema: {
-        analysis: z8.enum(["orphans", "dead_ends", "sources", "hubs", "stale"]).describe("Type of graph analysis to perform"),
-        folder: z8.string().optional().describe("Limit to notes in this folder (orphans, dead_ends, sources)"),
-        min_links: z8.coerce.number().default(5).describe("Minimum total connections for hubs"),
-        min_backlinks: z8.coerce.number().default(1).describe("Minimum backlinks (dead_ends, stale)"),
-        min_outlinks: z8.coerce.number().default(1).describe("Minimum outlinks (sources)"),
-        days: z8.coerce.number().optional().describe("Notes not modified in this many days (stale, required)"),
-        limit: z8.coerce.number().default(50).describe("Maximum number of results to return"),
-        offset: z8.coerce.number().default(0).describe("Number of results to skip (for pagination)")
-      }
-    },
-    async ({ analysis, folder, min_links, min_backlinks, min_outlinks, days, limit: requestedLimit, offset }) => {
-      requireIndex();
-      const limit = Math.min(requestedLimit ?? 50, MAX_LIMIT);
-      const index = getIndex();
-      switch (analysis) {
-        case "orphans": {
-          const allOrphans = findOrphanNotes(index, folder);
-          const orphans = allOrphans.slice(offset, offset + limit);
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              analysis: "orphans",
-              orphan_count: allOrphans.length,
-              returned_count: orphans.length,
-              folder,
-              orphans: orphans.map((o) => ({
-                path: o.path,
-                title: o.title,
-                modified: o.modified.toISOString()
-              }))
-            }, null, 2) }]
-          };
-        }
-        case "dead_ends": {
-          const allResults = findDeadEnds(index, folder, min_backlinks);
-          const result = allResults.slice(offset, offset + limit);
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              analysis: "dead_ends",
-              criteria: { folder, min_backlinks },
-              total_count: allResults.length,
-              returned_count: result.length,
-              dead_ends: result
-            }, null, 2) }]
-          };
-        }
-        case "sources": {
-          const allResults = findSources(index, folder, min_outlinks);
-          const result = allResults.slice(offset, offset + limit);
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              analysis: "sources",
-              criteria: { folder, min_outlinks },
-              total_count: allResults.length,
-              returned_count: result.length,
-              sources: result
-            }, null, 2) }]
-          };
-        }
-        case "hubs": {
-          const allHubs = findHubNotes(index, min_links);
-          const hubs = allHubs.slice(offset, offset + limit);
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              analysis: "hubs",
-              hub_count: allHubs.length,
-              returned_count: hubs.length,
-              min_links,
-              hubs: hubs.map((h) => ({
-                path: h.path,
-                title: h.title,
-                backlink_count: h.backlink_count,
-                forward_link_count: h.forward_link_count,
-                total_connections: h.total_connections
-              }))
-            }, null, 2) }]
-          };
-        }
-        case "stale": {
-          if (days === void 0) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({
-                error: "days parameter is required for stale analysis"
-              }, null, 2) }]
-            };
-          }
-          const result = getStaleNotes(index, days, min_backlinks).slice(0, limit);
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              analysis: "stale",
-              criteria: { days, min_backlinks },
-              count: result.length,
-              notes: result.map((n) => ({
-                ...n,
-                modified: n.modified.toISOString()
-              }))
-            }, null, 2) }]
-          };
-        }
-      }
-    }
-  );
-}
-
-// src/tools/read/vaultSchema.ts
-import { z as z9 } from "zod";
 
-// src/tools/read/frontmatter.ts
+// src/tools/read/schema.ts
 function getValueType(value) {
   if (value === null) return "null";
   if (value === void 0) return "undefined";
-  if (Array.isArray(value)) return "array";
+  if (Array.isArray(value)) {
+    if (value.some((v) => typeof v === "string" && /^\[\[.+\]\]$/.test(v))) {
+      return "wikilink[]";
+    }
+    return "array";
+  }
+  if (typeof value === "string") {
+    if (/^\[\[.+\]\]$/.test(value)) return "wikilink";
+    if (/^\d{4}-\d{2}-\d{2}/.test(value)) return "date";
+  }
   if (value instanceof Date) return "date";
   return typeof value;
 }
-function getFrontmatterSchema(index) {
-  const fieldMap = /* @__PURE__ */ new Map();
-  let notesWithFrontmatter = 0;
-  for (const note of index.notes.values()) {
-    const fm = note.frontmatter;
-    if (!fm || Object.keys(fm).length === 0) continue;
-    notesWithFrontmatter++;
-    for (const [key, value] of Object.entries(fm)) {
-      if (!fieldMap.has(key)) {
-        fieldMap.set(key, {
-          types: /* @__PURE__ */ new Set(),
-          count: 0,
-          examples: [],
-          notes: []
-        });
-      }
-      const info = fieldMap.get(key);
-      info.count++;
-      info.types.add(getValueType(value));
-      if (info.examples.length < 5) {
-        const valueStr = JSON.stringify(value);
-        const existingStrs = info.examples.map((e) => JSON.stringify(e));
-        if (!existingStrs.includes(valueStr)) {
-          info.examples.push(value);
-        }
-      }
-      if (info.notes.length < 5) {
-        info.notes.push(note.path);
-      }
-    }
-  }
-  const fields = Array.from(fieldMap.entries()).map(([name, info]) => ({
-    name,
-    types: Array.from(info.types),
-    count: info.count,
-    examples: info.examples,
-    notes_sample: info.notes
-  })).sort((a, b) => b.count - a.count);
-  return {
-    total_notes: index.notes.size,
-    notes_with_frontmatter: notesWithFrontmatter,
-    field_count: fields.length,
-    fields
-  };
-}
-function getFieldValues(index, fieldName) {
-  const valueMap = /* @__PURE__ */ new Map();
-  let totalWithField = 0;
-  for (const note of index.notes.values()) {
-    const value = note.frontmatter[fieldName];
-    if (value === void 0) continue;
-    totalWithField++;
-    const values = Array.isArray(value) ? value : [value];
-    for (const v of values) {
-      const key = JSON.stringify(v);
-      if (!valueMap.has(key)) {
-        valueMap.set(key, {
-          value: v,
-          count: 0,
-          notes: []
-        });
-      }
-      const info = valueMap.get(key);
-      info.count++;
-      info.notes.push(note.path);
-    }
-  }
-  const valuesList = Array.from(valueMap.values()).sort((a, b) => b.count - a.count);
-  return {
-    field: fieldName,
-    total_notes_with_field: totalWithField,
-    unique_values: valuesList.length,
-    values: valuesList
-  };
-}
-function findFrontmatterInconsistencies(index) {
-  const schema = getFrontmatterSchema(index);
-  const inconsistencies = [];
-  for (const field of schema.fields) {
-    if (field.types.length > 1) {
-      const examples = [];
-      for (const note of index.notes.values()) {
-        const value = note.frontmatter[field.name];
-        if (value === void 0) continue;
-        const type = getValueType(value);
-        if (!examples.some((e) => e.type === type)) {
-          examples.push({
-            type,
-            value,
-            note: note.path
-          });
-        }
-        if (examples.length >= field.types.length) break;
-      }
-      inconsistencies.push({
-        field: field.name,
-        types_found: field.types,
-        examples
-      });
-    }
-  }
-  return inconsistencies;
-}
-function validateFrontmatter(index, schema, folder) {
-  const results = [];
-  for (const note of index.notes.values()) {
-    if (folder && !note.path.startsWith(folder)) continue;
-    const issues = [];
-    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
-      const value = note.frontmatter[fieldName];
-      if (fieldSchema.required && value === void 0) {
-        issues.push({
-          field: fieldName,
-          issue: "missing",
-          expected: "value required"
-        });
-        continue;
-      }
-      if (value === void 0) continue;
-      if (fieldSchema.type) {
-        const actualType = getValueType(value);
-        const allowedTypes = Array.isArray(fieldSchema.type) ? fieldSchema.type : [fieldSchema.type];
-        if (!allowedTypes.includes(actualType)) {
-          issues.push({
-            field: fieldName,
-            issue: "wrong_type",
-            expected: allowedTypes.join(" | "),
-            actual: actualType
-          });
-        }
-      }
-      if (fieldSchema.values) {
-        const valueStr = JSON.stringify(value);
-        const allowedStrs = fieldSchema.values.map((v) => JSON.stringify(v));
-        if (!allowedStrs.includes(valueStr)) {
-          issues.push({
-            field: fieldName,
-            issue: "invalid_value",
-            expected: fieldSchema.values.map((v) => String(v)).join(" | "),
-            actual: String(value)
-          });
-        }
-      }
-    }
-    if (issues.length > 0) {
-      results.push({
-        path: note.path,
-        issues
-      });
-    }
-  }
-  return results;
-}
-function findMissingFrontmatter(index, folderSchemas) {
-  const results = [];
-  for (const note of index.notes.values()) {
-    for (const [folder, requiredFields] of Object.entries(folderSchemas)) {
-      if (!note.path.startsWith(folder)) continue;
-      const missing = requiredFields.filter(
-        (field) => note.frontmatter[field] === void 0
-      );
-      if (missing.length > 0) {
-        results.push({
-          path: note.path,
-          folder,
-          missing_fields: missing
-        });
-      }
-    }
-  }
-  return results;
-}
-
-// src/tools/read/schema.ts
-function getValueType2(value) {
-  if (value === null) return "null";
-  if (value === void 0) return "undefined";
-  if (Array.isArray(value)) {
-    if (value.some((v) => typeof v === "string" && /^\[\[.+\]\]$/.test(v))) {
-      return "wikilink[]";
-    }
-    return "array";
-  }
-  if (typeof value === "string") {
-    if (/^\[\[.+\]\]$/.test(value)) return "wikilink";
-    if (/^\d{4}-\d{2}-\d{2}/.test(value)) return "date";
-  }
-  if (value instanceof Date) return "date";
-  return typeof value;
-}
-function getFolder(notePath) {
-  const lastSlash = notePath.lastIndexOf("/");
-  return lastSlash === -1 ? "" : notePath.substring(0, lastSlash);
-}
-function getNotesInFolder2(index, folder) {
-  const notes = [];
+function getFolder(notePath) {
+  const lastSlash = notePath.lastIndexOf("/");
+  return lastSlash === -1 ? "" : notePath.substring(0, lastSlash);
+}
+function getNotesInFolder2(index, folder) {
+  const notes = [];
   for (const note of index.notes.values()) {
     if (!folder || note.path.startsWith(folder + "/") || getFolder(note.path) === folder) {
       notes.push(note);
@@ -8298,7 +8255,7 @@ function inferFolderConventions(index, folder, minConfidence = 0.5) {
       }
       const stats = fieldStats.get(key);
       stats.count++;
-      const type = getValueType2(value);
+      const type = getValueType(value);
       stats.types.set(type, (stats.types.get(type) || 0) + 1);
       const valueStr = JSON.stringify(value);
       stats.values.set(valueStr, (stats.values.get(valueStr) || 0) + 1);
@@ -8430,7 +8387,7 @@ function suggestFieldValues(index, field, context) {
     const value = note.frontmatter[field];
     if (value === void 0) continue;
     totalWithField++;
-    const type = getValueType2(value);
+    const type = getValueType(value);
     typeCounts.set(type, (typeCounts.get(type) || 0) + 1);
     const values = Array.isArray(value) ? value : [value];
     for (const v of values) {
@@ -8489,148 +8446,480 @@ function suggestFieldValues(index, field, context) {
     is_enumerable: isEnumerable
   };
 }
+var SKIP_CONTRADICTION_FIELDS = /* @__PURE__ */ new Set([
+  "title",
+  "created",
+  "modified",
+  "path",
+  "aliases",
+  "tags",
+  "date",
+  "updated",
+  "word_count",
+  "link_count"
+]);
+function findContradictions(index, entity) {
+  const contradictions = [];
+  const entitiesToCheck = [];
+  if (entity) {
+    const normalized = entity.toLowerCase();
+    const entityPath = index.entities.get(normalized);
+    if (entityPath) {
+      entitiesToCheck.push([normalized, entityPath]);
+    }
+  } else {
+    for (const [name, entityPath] of index.entities) {
+      entitiesToCheck.push([name, entityPath]);
+    }
+  }
+  for (const [entityName, _entityPath] of entitiesToCheck) {
+    const backlinks = index.backlinks.get(entityName);
+    if (!backlinks || backlinks.length < 2) continue;
+    const sourcePaths = [...new Set(backlinks.map((bl) => bl.source))];
+    if (sourcePaths.length < 2) continue;
+    const notesFrontmatter = [];
+    for (const srcPath of sourcePaths) {
+      const note = index.notes.get(srcPath);
+      if (note && Object.keys(note.frontmatter).length > 0) {
+        notesFrontmatter.push({ path: srcPath, fm: note.frontmatter });
+      }
+    }
+    if (notesFrontmatter.length < 2) continue;
+    const allFields = /* @__PURE__ */ new Set();
+    for (const { fm } of notesFrontmatter) {
+      for (const key of Object.keys(fm)) {
+        if (!SKIP_CONTRADICTION_FIELDS.has(key)) {
+          allFields.add(key);
+        }
+      }
+    }
+    for (const field of allFields) {
+      const valueMap = /* @__PURE__ */ new Map();
+      for (const { path: notePath, fm } of notesFrontmatter) {
+        if (fm[field] === void 0) continue;
+        const key = JSON.stringify(fm[field]);
+        if (!valueMap.has(key)) {
+          valueMap.set(key, []);
+        }
+        valueMap.get(key).push(notePath);
+      }
+      if (valueMap.size >= 2) {
+        contradictions.push({
+          entity: entityName,
+          field,
+          values: Array.from(valueMap.entries()).map(([serialized, notes]) => ({
+            value: JSON.parse(serialized),
+            notes
+          }))
+        });
+      }
+    }
+  }
+  return contradictions;
+}
 
-// src/tools/read/vaultSchema.ts
-function registerVaultSchemaTools(server2, getIndex, getVaultPath) {
-  server2.registerTool(
-    "vault_schema",
-    {
-      title: "Vault Schema",
-      description: 'Analyze and validate vault frontmatter schema. Use analysis to pick the mode:\n- "overview": Schema of all frontmatter fields across the vault\n- "field_values": All unique values for a specific field\n- "inconsistencies": Fields with multiple types across notes\n- "validate": Validate notes against a provided schema\n- "missing": Find notes missing expected fields by folder\n- "conventions": Auto-detect metadata conventions for a folder\n- "incomplete": Find notes missing expected fields (inferred)\n- "suggest_values": Suggest values for a field based on usage\n\nExample: vault_schema({ analysis: "field_values", field: "status" })\nExample: vault_schema({ analysis: "conventions", folder: "projects" })',
-      inputSchema: {
-        analysis: z9.enum([
-          "overview",
-          "field_values",
-          "inconsistencies",
-          "validate",
-          "missing",
-          "conventions",
-          "incomplete",
-          "suggest_values"
-        ]).describe("Type of schema analysis to perform"),
-        field: z9.string().optional().describe("Field name (field_values, suggest_values)"),
-        folder: z9.string().optional().describe("Folder to scope analysis to"),
-        schema: z9.record(z9.object({
-          required: z9.boolean().optional().describe("Whether field is required"),
-          type: z9.union([z9.string(), z9.array(z9.string())]).optional().describe("Expected type(s)"),
-          values: z9.array(z9.unknown()).optional().describe("Allowed values")
-        })).optional().describe("Schema to validate against (validate mode)"),
-        folder_schemas: z9.record(z9.array(z9.string())).optional().describe("Map of folder paths to required fields (missing mode)"),
-        min_confidence: z9.coerce.number().min(0).max(1).optional().describe("Minimum confidence threshold (conventions)"),
-        min_frequency: z9.coerce.number().min(0).max(1).optional().describe("Minimum field frequency (incomplete)"),
-        existing_frontmatter: z9.record(z9.unknown()).optional().describe("Existing frontmatter for context (suggest_values)"),
-        limit: z9.coerce.number().default(50).describe("Maximum results to return"),
-        offset: z9.coerce.number().default(0).describe("Number of results to skip")
+// src/core/shared/graphSnapshots.ts
+function computeGraphMetrics(index) {
+  const noteCount = index.notes.size;
+  if (noteCount === 0) {
+    return {
+      avg_degree: 0,
+      max_degree: 0,
+      cluster_count: 0,
+      largest_cluster_size: 0,
+      hub_scores_top10: []
+    };
+  }
+  const degreeMap = /* @__PURE__ */ new Map();
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const [notePath, note] of index.notes) {
+    if (!adjacency.has(notePath)) adjacency.set(notePath, /* @__PURE__ */ new Set());
+    let degree = note.outlinks.length;
+    for (const link of note.outlinks) {
+      const targetLower = link.target.toLowerCase();
+      const resolvedPath = index.entities.get(targetLower);
+      if (resolvedPath && index.notes.has(resolvedPath)) {
+        adjacency.get(notePath).add(resolvedPath);
+        if (!adjacency.has(resolvedPath)) adjacency.set(resolvedPath, /* @__PURE__ */ new Set());
+        adjacency.get(resolvedPath).add(notePath);
       }
-    },
-    async (params) => {
-      requireIndex();
-      const limit = Math.min(params.limit ?? 50, MAX_LIMIT);
-      const index = getIndex();
-      switch (params.analysis) {
-        case "overview": {
-          const result = getFrontmatterSchema(index);
-          return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-          };
-        }
-        case "field_values": {
-          if (!params.field) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({
-                error: "field parameter is required for field_values analysis"
-              }, null, 2) }]
-            };
+    }
+    degreeMap.set(notePath, degree);
+  }
+  for (const [target, backlinks] of index.backlinks) {
+    const targetLower = target.toLowerCase();
+    const resolvedPath = index.entities.get(targetLower);
+    if (resolvedPath && degreeMap.has(resolvedPath)) {
+      degreeMap.set(resolvedPath, degreeMap.get(resolvedPath) + backlinks.length);
+    }
+  }
+  let totalDegree = 0;
+  let maxDegree = 0;
+  let maxDegreeNote = "";
+  for (const [notePath, degree] of degreeMap) {
+    totalDegree += degree;
+    if (degree > maxDegree) {
+      maxDegree = degree;
+      maxDegreeNote = notePath;
+    }
+  }
+  const avgDegree = noteCount > 0 ? Math.round(totalDegree / noteCount * 100) / 100 : 0;
+  const visited = /* @__PURE__ */ new Set();
+  const clusters = [];
+  for (const notePath of index.notes.keys()) {
+    if (visited.has(notePath)) continue;
+    const queue = [notePath];
+    visited.add(notePath);
+    let clusterSize = 0;
+    while (queue.length > 0) {
+      const current = queue.shift();
+      clusterSize++;
+      const neighbors = adjacency.get(current);
+      if (neighbors) {
+        for (const neighbor of neighbors) {
+          if (!visited.has(neighbor)) {
+            visited.add(neighbor);
+            queue.push(neighbor);
           }
-          const result = getFieldValues(index, params.field);
-          return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-          };
         }
-        case "inconsistencies": {
-          const result = findFrontmatterInconsistencies(index);
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              inconsistency_count: result.length,
-              inconsistencies: result
-            }, null, 2) }]
+      }
+    }
+    clusters.push(clusterSize);
+  }
+  const clusterCount = clusters.length;
+  const largestClusterSize = clusters.length > 0 ? Math.max(...clusters) : 0;
+  const sorted = Array.from(degreeMap.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10);
+  const hubScoresTop10 = sorted.map(([notePath, degree]) => {
+    const note = index.notes.get(notePath);
+    return {
+      entity: note?.title ?? notePath,
+      degree
+    };
+  });
+  return {
+    avg_degree: avgDegree,
+    max_degree: maxDegree,
+    cluster_count: clusterCount,
+    largest_cluster_size: largestClusterSize,
+    hub_scores_top10: hubScoresTop10
+  };
+}
+function recordGraphSnapshot(stateDb2, metrics) {
+  const timestamp = Date.now();
+  const insert = stateDb2.db.prepare(
+    "INSERT INTO graph_snapshots (timestamp, metric, value, details) VALUES (?, ?, ?, ?)"
+  );
+  const transaction = stateDb2.db.transaction(() => {
+    insert.run(timestamp, "avg_degree", metrics.avg_degree, null);
+    insert.run(timestamp, "max_degree", metrics.max_degree, null);
+    insert.run(timestamp, "cluster_count", metrics.cluster_count, null);
+    insert.run(timestamp, "largest_cluster_size", metrics.largest_cluster_size, null);
+    insert.run(
+      timestamp,
+      "hub_scores_top10",
+      metrics.hub_scores_top10.length,
+      JSON.stringify(metrics.hub_scores_top10)
+    );
+  });
+  transaction();
+}
+function getGraphEvolution(stateDb2, daysBack = 30) {
+  const now = Date.now();
+  const cutoff = now - daysBack * 24 * 60 * 60 * 1e3;
+  const SCALAR_METRICS = ["avg_degree", "max_degree", "cluster_count", "largest_cluster_size"];
+  const latestRows = stateDb2.db.prepare(`
+    SELECT metric, value FROM graph_snapshots
+    WHERE metric IN ('avg_degree', 'max_degree', 'cluster_count', 'largest_cluster_size')
+    GROUP BY metric
+    HAVING timestamp = MAX(timestamp)
+  `).all();
+  const currentValues = /* @__PURE__ */ new Map();
+  for (const row of latestRows) {
+    currentValues.set(row.metric, row.value);
+  }
+  const previousRows = stateDb2.db.prepare(`
+    SELECT metric, value FROM graph_snapshots
+    WHERE metric IN ('avg_degree', 'max_degree', 'cluster_count', 'largest_cluster_size')
+      AND timestamp >= ? AND timestamp <= ?
+    GROUP BY metric
+    HAVING timestamp = MIN(timestamp)
+  `).all(cutoff, cutoff + 24 * 60 * 60 * 1e3);
+  const previousValues = /* @__PURE__ */ new Map();
+  for (const row of previousRows) {
+    previousValues.set(row.metric, row.value);
+  }
+  if (previousValues.size === 0) {
+    const fallbackRows = stateDb2.db.prepare(`
+      SELECT metric, value FROM graph_snapshots
+      WHERE metric IN ('avg_degree', 'max_degree', 'cluster_count', 'largest_cluster_size')
+        AND timestamp >= ?
+      GROUP BY metric
+      HAVING timestamp = MIN(timestamp)
+    `).all(cutoff);
+    for (const row of fallbackRows) {
+      previousValues.set(row.metric, row.value);
+    }
+  }
+  const evolutions = [];
+  for (const metric of SCALAR_METRICS) {
+    const current = currentValues.get(metric) ?? 0;
+    const previous = previousValues.get(metric) ?? current;
+    const delta = current - previous;
+    const deltaPct = previous !== 0 ? Math.round(delta / previous * 1e4) / 100 : delta !== 0 ? 100 : 0;
+    let direction = "stable";
+    if (delta > 0) direction = "up";
+    if (delta < 0) direction = "down";
+    evolutions.push({
+      metric,
+      current,
+      previous,
+      delta,
+      delta_percent: deltaPct,
+      direction
+    });
+  }
+  return evolutions;
+}
+function getEmergingHubs(stateDb2, daysBack = 30) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  const latestRow = stateDb2.db.prepare(
+    `SELECT details FROM graph_snapshots
+     WHERE metric = 'hub_scores_top10'
+     ORDER BY timestamp DESC LIMIT 1`
+  ).get();
+  const previousRow = stateDb2.db.prepare(
+    `SELECT details FROM graph_snapshots
+     WHERE metric = 'hub_scores_top10' AND timestamp >= ?
+     ORDER BY timestamp ASC LIMIT 1`
+  ).get(cutoff);
+  if (!latestRow?.details) return [];
+  const currentHubs = JSON.parse(latestRow.details);
+  const previousHubs = previousRow?.details ? JSON.parse(previousRow.details) : [];
+  const previousMap = /* @__PURE__ */ new Map();
+  for (const hub of previousHubs) {
+    previousMap.set(hub.entity, hub.degree);
+  }
+  const emerging = currentHubs.map((hub) => {
+    const prevDegree = previousMap.get(hub.entity) ?? 0;
+    return {
+      entity: hub.entity,
+      current_degree: hub.degree,
+      previous_degree: prevDegree,
+      growth: hub.degree - prevDegree
+    };
+  });
+  emerging.sort((a, b) => b.growth - a.growth);
+  return emerging;
+}
+function purgeOldSnapshots(stateDb2, retentionDays = 90) {
+  const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1e3;
+  const result = stateDb2.db.prepare(
+    "DELETE FROM graph_snapshots WHERE timestamp < ?"
+  ).run(cutoff);
+  return result.changes;
+}
+
+// src/tools/read/graphAnalysis.ts
+function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb) {
+  server2.registerTool(
+    "graph_analysis",
+    {
+      title: "Graph Analysis",
+      description: 'Analyze vault link graph structure. Use analysis to pick the mode:\n- "orphans": Notes with no backlinks (disconnected content)\n- "dead_ends": Notes with backlinks but no outgoing links\n- "sources": Notes with outgoing links but no backlinks\n- "hubs": Highly connected notes (many links to/from)\n- "stale": Important notes (by backlink count) not recently modified\n- "immature": Notes scored by maturity (word count, links, frontmatter completeness, backlinks)\n- "evolution": Graph topology metrics over time (avg_degree, cluster_count, etc.)\n- "emerging_hubs": Entities growing fastest in connection count\n\nExample: graph_analysis({ analysis: "hubs", limit: 10 })\nExample: graph_analysis({ analysis: "stale", days: 30, min_backlinks: 3 })\nExample: graph_analysis({ analysis: "immature", folder: "projects", limit: 20 })\nExample: graph_analysis({ analysis: "evolution", days: 30 })\nExample: graph_analysis({ analysis: "emerging_hubs", days: 30 })',
+      inputSchema: {
+        analysis: z8.enum(["orphans", "dead_ends", "sources", "hubs", "stale", "immature", "evolution", "emerging_hubs"]).describe("Type of graph analysis to perform"),
+        folder: z8.string().optional().describe("Limit to notes in this folder (orphans, dead_ends, sources)"),
+        min_links: z8.coerce.number().default(5).describe("Minimum total connections for hubs"),
+        min_backlinks: z8.coerce.number().default(1).describe("Minimum backlinks (dead_ends, stale)"),
+        min_outlinks: z8.coerce.number().default(1).describe("Minimum outlinks (sources)"),
+        days: z8.coerce.number().optional().describe("Notes not modified in this many days (stale, required)"),
+        limit: z8.coerce.number().default(50).describe("Maximum number of results to return"),
+        offset: z8.coerce.number().default(0).describe("Number of results to skip (for pagination)")
+      }
+    },
+    async ({ analysis, folder, min_links, min_backlinks, min_outlinks, days, limit: requestedLimit, offset }) => {
+      requireIndex();
+      const limit = Math.min(requestedLimit ?? 50, MAX_LIMIT);
+      const index = getIndex();
+      switch (analysis) {
+        case "orphans": {
+          const allOrphans = findOrphanNotes(index, folder);
+          const orphans = allOrphans.slice(offset, offset + limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "orphans",
+              orphan_count: allOrphans.length,
+              returned_count: orphans.length,
+              folder,
+              orphans: orphans.map((o) => ({
+                path: o.path,
+                title: o.title,
+                modified: o.modified.toISOString()
+              }))
+            }, null, 2) }]
           };
         }
-        case "validate": {
-          if (!params.schema) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({
-                error: "schema parameter is required for validate analysis"
-              }, null, 2) }]
-            };
-          }
-          const result = validateFrontmatter(
-            index,
-            params.schema,
-            params.folder
-          );
+        case "dead_ends": {
+          const allResults = findDeadEnds(index, folder, min_backlinks);
+          const result = allResults.slice(offset, offset + limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
-              notes_with_issues: result.length,
-              results: result
+              analysis: "dead_ends",
+              criteria: { folder, min_backlinks },
+              total_count: allResults.length,
+              returned_count: result.length,
+              dead_ends: result
             }, null, 2) }]
           };
         }
-        case "missing": {
-          if (!params.folder_schemas) {
+        case "sources": {
+          const allResults = findSources(index, folder, min_outlinks);
+          const result = allResults.slice(offset, offset + limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "sources",
+              criteria: { folder, min_outlinks },
+              total_count: allResults.length,
+              returned_count: result.length,
+              sources: result
+            }, null, 2) }]
+          };
+        }
+        case "hubs": {
+          const allHubs = findHubNotes(index, min_links);
+          const hubs = allHubs.slice(offset, offset + limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "hubs",
+              hub_count: allHubs.length,
+              returned_count: hubs.length,
+              min_links,
+              hubs: hubs.map((h) => ({
+                path: h.path,
+                title: h.title,
+                backlink_count: h.backlink_count,
+                forward_link_count: h.forward_link_count,
+                total_connections: h.total_connections
+              }))
+            }, null, 2) }]
+          };
+        }
+        case "stale": {
+          if (days === void 0) {
             return {
               content: [{ type: "text", text: JSON.stringify({
-                error: "folder_schemas parameter is required for missing analysis"
+                error: "days parameter is required for stale analysis"
               }, null, 2) }]
             };
           }
-          const result = findMissingFrontmatter(
-            index,
-            params.folder_schemas
-          );
+          const result = getStaleNotes(index, days, min_backlinks).slice(0, limit);
           return {
             content: [{ type: "text", text: JSON.stringify({
-              notes_with_missing_fields: result.length,
-              results: result
+              analysis: "stale",
+              criteria: { days, min_backlinks },
+              count: result.length,
+              notes: result.map((n) => ({
+                ...n,
+                modified: n.modified.toISOString()
+              }))
             }, null, 2) }]
           };
         }
-        case "conventions": {
-          const result = inferFolderConventions(
-            index,
-            params.folder,
-            params.min_confidence ?? 0.5
+        case "immature": {
+          const vaultPath2 = getVaultPath();
+          const allNotes = Array.from(index.notes.values()).filter(
+            (note) => !folder || note.path.startsWith(folder + "/") || note.path.substring(0, note.path.lastIndexOf("/")) === folder
           );
+          const conventions = inferFolderConventions(index, folder, 0.5);
+          const expectedFields = conventions.inferred_fields.map((f) => f.name);
+          const scored = allNotes.map((note) => {
+            let wordCount = 0;
+            try {
+              const content = fs14.readFileSync(path13.join(vaultPath2, note.path), "utf-8");
+              const body = content.replace(/^---[\s\S]*?---\n?/, "");
+              wordCount = body.split(/\s+/).filter((w) => w.length > 0).length;
+            } catch {
+            }
+            const wordScore = wordCount < 100 ? 0 : wordCount < 500 ? 0.5 : 1;
+            const outlinkCount = note.outlinks.length;
+            const outlinkScore = outlinkCount === 0 ? 0 : outlinkCount <= 3 ? 0.5 : 1;
+            let frontmatterScore = 0;
+            if (expectedFields.length > 0) {
+              const existingFields = Object.keys(note.frontmatter);
+              const presentCount = expectedFields.filter((f) => existingFields.includes(f)).length;
+              frontmatterScore = presentCount / expectedFields.length;
+            } else {
+              frontmatterScore = 1;
+            }
+            const normalizedTitle = note.title.toLowerCase();
+            const backlinks = index.backlinks.get(normalizedTitle) || [];
+            const backlinkCount = backlinks.length;
+            const backlinkScore = backlinkCount === 0 ? 0 : backlinkCount <= 2 ? 0.5 : 1;
+            const maturity = (wordScore + outlinkScore + frontmatterScore + backlinkScore) / 4;
+            return {
+              path: note.path,
+              title: note.title,
+              maturity_score: Math.round(maturity * 100) / 100,
+              components: {
+                word_count: { value: wordCount, score: wordScore },
+                outlinks: { value: outlinkCount, score: outlinkScore },
+                frontmatter: { value: `${expectedFields.length > 0 ? Math.round(frontmatterScore * 100) : 100}%`, score: Math.round(frontmatterScore * 100) / 100 },
+                backlinks: { value: backlinkCount, score: backlinkScore }
+              },
+              modified: note.modified.toISOString()
+            };
+          });
+          scored.sort((a, b) => a.maturity_score - b.maturity_score);
+          const total = scored.length;
+          const paginated = scored.slice(offset, offset + limit);
           return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "immature",
+              criteria: { folder: folder || null },
+              total_count: total,
+              returned_count: paginated.length,
+              expected_fields: expectedFields,
+              notes: paginated
+            }, null, 2) }]
           };
         }
-        case "incomplete": {
-          const result = findIncompleteNotes(
-            index,
-            params.folder,
-            params.min_frequency ?? 0.7,
-            limit,
-            params.offset ?? 0
-          );
+        case "evolution": {
+          const db3 = getStateDb?.();
+          if (!db3) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({
+                error: "StateDb not available \u2014 graph evolution requires persistent state"
+              }, null, 2) }]
+            };
+          }
+          const daysBack = days ?? 30;
+          const evolutions = getGraphEvolution(db3, daysBack);
           return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "evolution",
+              days_back: daysBack,
+              metrics: evolutions
+            }, null, 2) }]
           };
         }
-        case "suggest_values": {
-          if (!params.field) {
+        case "emerging_hubs": {
+          const db3 = getStateDb?.();
+          if (!db3) {
             return {
               content: [{ type: "text", text: JSON.stringify({
-                error: "field parameter is required for suggest_values analysis"
+                error: "StateDb not available \u2014 emerging hubs requires persistent state"
               }, null, 2) }]
             };
           }
-          const result = suggestFieldValues(index, params.field, {
-            folder: params.folder,
-            existing_frontmatter: params.existing_frontmatter
-          });
+          const daysBack = days ?? 30;
+          const hubs = getEmergingHubs(db3, daysBack);
           return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "emerging_hubs",
+              days_back: daysBack,
+              count: hubs.length,
+              hubs
+            }, null, 2) }]
           };
         }
       }
@@ -8638,45 +8927,392 @@ function registerVaultSchemaTools(server2, getIndex, getVaultPath) {
   );
 }
 
-// src/tools/read/noteIntelligence.ts
-import { z as z10 } from "zod";
+// src/tools/read/vaultSchema.ts
+import { z as z9 } from "zod";
 
-// src/tools/read/bidirectional.ts
-import * as fs13 from "fs/promises";
-import * as path13 from "path";
-import matter3 from "gray-matter";
-var PROSE_PATTERN_REGEX = /^([A-Za-z][A-Za-z0-9 _-]*):\s*(?:\[\[([^\]]+)\]\]|"([^"]+)"|([^\n]+?))\s*$/gm;
-var CODE_BLOCK_REGEX2 = /```[\s\S]*?```|`[^`\n]+`/g;
-var WIKILINK_REGEX2 = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]+)?\]\]/g;
-async function readFileContent2(notePath, vaultPath2) {
-  const fullPath = path13.join(vaultPath2, notePath);
-  try {
-    return await fs13.readFile(fullPath, "utf-8");
-  } catch {
-    return null;
-  }
-}
-function getBodyContent(content) {
-  try {
-    const parsed = matter3(content);
-    const frontmatterMatch = content.match(/^---\n[\s\S]*?\n---\n?/);
-    const bodyStartLine = frontmatterMatch ? frontmatterMatch[0].split("\n").length : 1;
-    return { body: parsed.content, bodyStartLine };
-  } catch {
-    return { body: content, bodyStartLine: 1 };
-  }
-}
-function removeCodeBlocks(content) {
-  return content.replace(CODE_BLOCK_REGEX2, (match) => {
-    const newlines = (match.match(/\n/g) || []).length;
-    return "\n".repeat(newlines);
-  });
+// src/tools/read/frontmatter.ts
+function getValueType2(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (Array.isArray(value)) return "array";
+  if (value instanceof Date) return "date";
+  return typeof value;
 }
-function extractWikilinksFromValue(value) {
-  if (typeof value === "string") {
-    const matches = [];
-    let match;
-    WIKILINK_REGEX2.lastIndex = 0;
+function getFrontmatterSchema(index) {
+  const fieldMap = /* @__PURE__ */ new Map();
+  let notesWithFrontmatter = 0;
+  for (const note of index.notes.values()) {
+    const fm = note.frontmatter;
+    if (!fm || Object.keys(fm).length === 0) continue;
+    notesWithFrontmatter++;
+    for (const [key, value] of Object.entries(fm)) {
+      if (!fieldMap.has(key)) {
+        fieldMap.set(key, {
+          types: /* @__PURE__ */ new Set(),
+          count: 0,
+          examples: [],
+          notes: []
+        });
+      }
+      const info = fieldMap.get(key);
+      info.count++;
+      info.types.add(getValueType2(value));
+      if (info.examples.length < 5) {
+        const valueStr = JSON.stringify(value);
+        const existingStrs = info.examples.map((e) => JSON.stringify(e));
+        if (!existingStrs.includes(valueStr)) {
+          info.examples.push(value);
+        }
+      }
+      if (info.notes.length < 5) {
+        info.notes.push(note.path);
+      }
+    }
+  }
+  const fields = Array.from(fieldMap.entries()).map(([name, info]) => ({
+    name,
+    types: Array.from(info.types),
+    count: info.count,
+    examples: info.examples,
+    notes_sample: info.notes
+  })).sort((a, b) => b.count - a.count);
+  return {
+    total_notes: index.notes.size,
+    notes_with_frontmatter: notesWithFrontmatter,
+    field_count: fields.length,
+    fields
+  };
+}
+function getFieldValues(index, fieldName) {
+  const valueMap = /* @__PURE__ */ new Map();
+  let totalWithField = 0;
+  for (const note of index.notes.values()) {
+    const value = note.frontmatter[fieldName];
+    if (value === void 0) continue;
+    totalWithField++;
+    const values = Array.isArray(value) ? value : [value];
+    for (const v of values) {
+      const key = JSON.stringify(v);
+      if (!valueMap.has(key)) {
+        valueMap.set(key, {
+          value: v,
+          count: 0,
+          notes: []
+        });
+      }
+      const info = valueMap.get(key);
+      info.count++;
+      info.notes.push(note.path);
+    }
+  }
+  const valuesList = Array.from(valueMap.values()).sort((a, b) => b.count - a.count);
+  return {
+    field: fieldName,
+    total_notes_with_field: totalWithField,
+    unique_values: valuesList.length,
+    values: valuesList
+  };
+}
+function findFrontmatterInconsistencies(index) {
+  const schema = getFrontmatterSchema(index);
+  const inconsistencies = [];
+  for (const field of schema.fields) {
+    if (field.types.length > 1) {
+      const examples = [];
+      for (const note of index.notes.values()) {
+        const value = note.frontmatter[field.name];
+        if (value === void 0) continue;
+        const type = getValueType2(value);
+        if (!examples.some((e) => e.type === type)) {
+          examples.push({
+            type,
+            value,
+            note: note.path
+          });
+        }
+        if (examples.length >= field.types.length) break;
+      }
+      inconsistencies.push({
+        field: field.name,
+        types_found: field.types,
+        examples
+      });
+    }
+  }
+  return inconsistencies;
+}
+function validateFrontmatter(index, schema, folder) {
+  const results = [];
+  for (const note of index.notes.values()) {
+    if (folder && !note.path.startsWith(folder)) continue;
+    const issues = [];
+    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
+      const value = note.frontmatter[fieldName];
+      if (fieldSchema.required && value === void 0) {
+        issues.push({
+          field: fieldName,
+          issue: "missing",
+          expected: "value required"
+        });
+        continue;
+      }
+      if (value === void 0) continue;
+      if (fieldSchema.type) {
+        const actualType = getValueType2(value);
+        const allowedTypes = Array.isArray(fieldSchema.type) ? fieldSchema.type : [fieldSchema.type];
+        if (!allowedTypes.includes(actualType)) {
+          issues.push({
+            field: fieldName,
+            issue: "wrong_type",
+            expected: allowedTypes.join(" | "),
+            actual: actualType
+          });
+        }
+      }
+      if (fieldSchema.values) {
+        const valueStr = JSON.stringify(value);
+        const allowedStrs = fieldSchema.values.map((v) => JSON.stringify(v));
+        if (!allowedStrs.includes(valueStr)) {
+          issues.push({
+            field: fieldName,
+            issue: "invalid_value",
+            expected: fieldSchema.values.map((v) => String(v)).join(" | "),
+            actual: String(value)
+          });
+        }
+      }
+    }
+    if (issues.length > 0) {
+      results.push({
+        path: note.path,
+        issues
+      });
+    }
+  }
+  return results;
+}
+function findMissingFrontmatter(index, folderSchemas) {
+  const results = [];
+  for (const note of index.notes.values()) {
+    for (const [folder, requiredFields] of Object.entries(folderSchemas)) {
+      if (!note.path.startsWith(folder)) continue;
+      const missing = requiredFields.filter(
+        (field) => note.frontmatter[field] === void 0
+      );
+      if (missing.length > 0) {
+        results.push({
+          path: note.path,
+          folder,
+          missing_fields: missing
+        });
+      }
+    }
+  }
+  return results;
+}
+
+// src/tools/read/vaultSchema.ts
+function registerVaultSchemaTools(server2, getIndex, getVaultPath) {
+  server2.registerTool(
+    "vault_schema",
+    {
+      title: "Vault Schema",
+      description: 'Analyze and validate vault frontmatter schema. Use analysis to pick the mode:\n- "overview": Schema of all frontmatter fields across the vault\n- "field_values": All unique values for a specific field\n- "inconsistencies": Fields with multiple types across notes\n- "validate": Validate notes against a provided schema\n- "missing": Find notes missing expected fields by folder\n- "conventions": Auto-detect metadata conventions for a folder\n- "incomplete": Find notes missing expected fields (inferred)\n- "suggest_values": Suggest values for a field based on usage\n- "contradictions": Find conflicting frontmatter values across notes referencing the same entity\n\nExample: vault_schema({ analysis: "field_values", field: "status" })\nExample: vault_schema({ analysis: "conventions", folder: "projects" })\nExample: vault_schema({ analysis: "contradictions", entity: "project alpha" })',
+      inputSchema: {
+        analysis: z9.enum([
+          "overview",
+          "field_values",
+          "inconsistencies",
+          "validate",
+          "missing",
+          "conventions",
+          "incomplete",
+          "suggest_values",
+          "contradictions"
+        ]).describe("Type of schema analysis to perform"),
+        field: z9.string().optional().describe("Field name (field_values, suggest_values)"),
+        entity: z9.string().optional().describe("Entity name to scope contradiction detection to (contradictions mode)"),
+        folder: z9.string().optional().describe("Folder to scope analysis to"),
+        schema: z9.record(z9.object({
+          required: z9.boolean().optional().describe("Whether field is required"),
+          type: z9.union([z9.string(), z9.array(z9.string())]).optional().describe("Expected type(s)"),
+          values: z9.array(z9.unknown()).optional().describe("Allowed values")
+        })).optional().describe("Schema to validate against (validate mode)"),
+        folder_schemas: z9.record(z9.array(z9.string())).optional().describe("Map of folder paths to required fields (missing mode)"),
+        min_confidence: z9.coerce.number().min(0).max(1).optional().describe("Minimum confidence threshold (conventions)"),
+        min_frequency: z9.coerce.number().min(0).max(1).optional().describe("Minimum field frequency (incomplete)"),
+        existing_frontmatter: z9.record(z9.unknown()).optional().describe("Existing frontmatter for context (suggest_values)"),
+        limit: z9.coerce.number().default(50).describe("Maximum results to return"),
+        offset: z9.coerce.number().default(0).describe("Number of results to skip")
+      }
+    },
+    async (params) => {
+      requireIndex();
+      const limit = Math.min(params.limit ?? 50, MAX_LIMIT);
+      const index = getIndex();
+      switch (params.analysis) {
+        case "overview": {
+          const result = getFrontmatterSchema(index);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+          };
+        }
+        case "field_values": {
+          if (!params.field) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({
+                error: "field parameter is required for field_values analysis"
+              }, null, 2) }]
+            };
+          }
+          const result = getFieldValues(index, params.field);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+          };
+        }
+        case "inconsistencies": {
+          const result = findFrontmatterInconsistencies(index);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              inconsistency_count: result.length,
+              inconsistencies: result
+            }, null, 2) }]
+          };
+        }
+        case "validate": {
+          if (!params.schema) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({
+                error: "schema parameter is required for validate analysis"
+              }, null, 2) }]
+            };
+          }
+          const result = validateFrontmatter(
+            index,
+            params.schema,
+            params.folder
+          );
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              notes_with_issues: result.length,
+              results: result
+            }, null, 2) }]
+          };
+        }
+        case "missing": {
+          if (!params.folder_schemas) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({
+                error: "folder_schemas parameter is required for missing analysis"
+              }, null, 2) }]
+            };
+          }
+          const result = findMissingFrontmatter(
+            index,
+            params.folder_schemas
+          );
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              notes_with_missing_fields: result.length,
+              results: result
+            }, null, 2) }]
+          };
+        }
+        case "conventions": {
+          const result = inferFolderConventions(
+            index,
+            params.folder,
+            params.min_confidence ?? 0.5
+          );
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+          };
+        }
+        case "incomplete": {
+          const result = findIncompleteNotes(
+            index,
+            params.folder,
+            params.min_frequency ?? 0.7,
+            limit,
+            params.offset ?? 0
+          );
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+          };
+        }
+        case "suggest_values": {
+          if (!params.field) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({
+                error: "field parameter is required for suggest_values analysis"
+              }, null, 2) }]
+            };
+          }
+          const result = suggestFieldValues(index, params.field, {
+            folder: params.folder,
+            existing_frontmatter: params.existing_frontmatter
+          });
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+          };
+        }
+        case "contradictions": {
+          const allContradictions = findContradictions(index, params.entity);
+          const paginated = allContradictions.slice(params.offset ?? 0, (params.offset ?? 0) + limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "contradictions",
+              entity: params.entity || null,
+              total_count: allContradictions.length,
+              returned_count: paginated.length,
+              contradictions: paginated
+            }, null, 2) }]
+          };
+        }
+      }
+    }
+  );
+}
+
+// src/tools/read/noteIntelligence.ts
+import { z as z10 } from "zod";
+
+// src/tools/read/bidirectional.ts
+import * as fs15 from "fs/promises";
+import * as path14 from "path";
+import matter3 from "gray-matter";
+var PROSE_PATTERN_REGEX = /^([A-Za-z][A-Za-z0-9 _-]*):\s*(?:\[\[([^\]]+)\]\]|"([^"]+)"|([^\n]+?))\s*$/gm;
+var CODE_BLOCK_REGEX2 = /```[\s\S]*?```|`[^`\n]+`/g;
+var WIKILINK_REGEX2 = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]+)?\]\]/g;
+async function readFileContent2(notePath, vaultPath2) {
+  const fullPath = path14.join(vaultPath2, notePath);
+  try {
+    return await fs15.readFile(fullPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function getBodyContent(content) {
+  try {
+    const parsed = matter3(content);
+    const frontmatterMatch = content.match(/^---\n[\s\S]*?\n---\n?/);
+    const bodyStartLine = frontmatterMatch ? frontmatterMatch[0].split("\n").length : 1;
+    return { body: parsed.content, bodyStartLine };
+  } catch {
+    return { body: content, bodyStartLine: 1 };
+  }
+}
+function removeCodeBlocks(content) {
+  return content.replace(CODE_BLOCK_REGEX2, (match) => {
+    const newlines = (match.match(/\n/g) || []).length;
+    return "\n".repeat(newlines);
+  });
+}
+function extractWikilinksFromValue(value) {
+  if (typeof value === "string") {
+    const matches = [];
+    let match;
+    WIKILINK_REGEX2.lastIndex = 0;
     while ((match = WIKILINK_REGEX2.exec(value)) !== null) {
       matches.push(match[1].trim());
     }
@@ -8918,21 +9554,21 @@ async function validateCrossLayer(index, notePath, vaultPath2) {
 }
 
 // src/tools/read/computed.ts
-import * as fs14 from "fs/promises";
-import * as path14 from "path";
+import * as fs16 from "fs/promises";
+import * as path15 from "path";
 import matter4 from "gray-matter";
 async function readFileContent3(notePath, vaultPath2) {
-  const fullPath = path14.join(vaultPath2, notePath);
+  const fullPath = path15.join(vaultPath2, notePath);
   try {
-    return await fs14.readFile(fullPath, "utf-8");
+    return await fs16.readFile(fullPath, "utf-8");
   } catch {
     return null;
   }
 }
 async function getFileStats(notePath, vaultPath2) {
-  const fullPath = path14.join(vaultPath2, notePath);
+  const fullPath = path15.join(vaultPath2, notePath);
   try {
-    const stats = await fs14.stat(fullPath);
+    const stats = await fs16.stat(fullPath);
     return {
       modified: stats.mtime,
       created: stats.birthtime
@@ -9142,8 +9778,8 @@ function registerNoteIntelligenceTools(server2, getIndex, getVaultPath) {
 // src/tools/write/mutations.ts
 init_writer();
 import { z as z11 } from "zod";
-import fs17 from "fs/promises";
-import path17 from "path";
+import fs19 from "fs/promises";
+import path18 from "path";
 
 // src/core/write/validator.ts
 var TIMESTAMP_PATTERN = /^\*\*\d{2}:\d{2}\*\*/;
@@ -9345,8 +9981,8 @@ function runValidationPipeline(content, format, options = {}) {
 
 // src/core/write/mutation-helpers.ts
 init_writer();
-import fs16 from "fs/promises";
-import path16 from "path";
+import fs18 from "fs/promises";
+import path17 from "path";
 init_constants();
 init_writer();
 function formatMcpResult(result) {
@@ -9395,9 +10031,9 @@ async function handleGitCommit(vaultPath2, notePath, commit, prefix) {
   return info;
 }
 async function ensureFileExists(vaultPath2, notePath) {
-  const fullPath = path16.join(vaultPath2, notePath);
+  const fullPath = path17.join(vaultPath2, notePath);
   try {
-    await fs16.access(fullPath);
+    await fs18.access(fullPath);
     return null;
   } catch {
     return errorResult(notePath, `File not found: ${notePath}`);
@@ -9495,10 +10131,10 @@ async function withVaultFrontmatter(options, operation) {
 
 // src/tools/write/mutations.ts
 async function createNoteFromTemplate(vaultPath2, notePath, config) {
-  const fullPath = path17.join(vaultPath2, notePath);
-  await fs17.mkdir(path17.dirname(fullPath), { recursive: true });
+  const fullPath = path18.join(vaultPath2, notePath);
+  await fs19.mkdir(path18.dirname(fullPath), { recursive: true });
   const templates = config.templates || {};
-  const filename = path17.basename(notePath, ".md").toLowerCase();
+  const filename = path18.basename(notePath, ".md").toLowerCase();
   let templatePath;
   const dailyPattern = /^\d{4}-\d{2}-\d{2}/;
   const weeklyPattern = /^\d{4}-W\d{2}/;
@@ -9519,10 +10155,10 @@ async function createNoteFromTemplate(vaultPath2, notePath, config) {
   let templateContent;
   if (templatePath) {
     try {
-      const absTemplatePath = path17.join(vaultPath2, templatePath);
-      templateContent = await fs17.readFile(absTemplatePath, "utf-8");
+      const absTemplatePath = path18.join(vaultPath2, templatePath);
+      templateContent = await fs19.readFile(absTemplatePath, "utf-8");
     } catch {
-      const title = path17.basename(notePath, ".md");
+      const title = path18.basename(notePath, ".md");
       templateContent = `---
 ---
 
@@ -9531,7 +10167,7 @@ async function createNoteFromTemplate(vaultPath2, notePath, config) {
       templatePath = void 0;
     }
   } else {
-    const title = path17.basename(notePath, ".md");
+    const title = path18.basename(notePath, ".md");
     templateContent = `---
 ---
 
@@ -9540,8 +10176,8 @@ async function createNoteFromTemplate(vaultPath2, notePath, config) {
   }
   const now = /* @__PURE__ */ new Date();
   const dateStr = now.toISOString().split("T")[0];
-  templateContent = templateContent.replace(/\{\{date\}\}/g, dateStr).replace(/\{\{title\}\}/g, path17.basename(notePath, ".md"));
-  await fs17.writeFile(fullPath, templateContent, "utf-8");
+  templateContent = templateContent.replace(/\{\{date\}\}/g, dateStr).replace(/\{\{title\}\}/g, path18.basename(notePath, ".md"));
+  await fs19.writeFile(fullPath, templateContent, "utf-8");
   return { created: true, templateUsed: templatePath };
 }
 function registerMutationTools(server2, vaultPath2, getConfig = () => ({})) {
@@ -9572,9 +10208,9 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
       let noteCreated = false;
       let templateUsed;
       if (create_if_missing) {
-        const fullPath = path17.join(vaultPath2, notePath);
+        const fullPath = path18.join(vaultPath2, notePath);
         try {
-          await fs17.access(fullPath);
+          await fs19.access(fullPath);
         } catch {
           const config = getConfig();
           const result = await createNoteFromTemplate(vaultPath2, notePath, config);
@@ -10009,8 +10645,8 @@ Example: vault_update_frontmatter({ path: "projects/alpha.md", frontmatter: { st
 // src/tools/write/notes.ts
 init_writer();
 import { z as z14 } from "zod";
-import fs18 from "fs/promises";
-import path18 from "path";
+import fs20 from "fs/promises";
+import path19 from "path";
 function registerNoteTools(server2, vaultPath2, getIndex) {
   server2.tool(
     "vault_create_note",
@@ -10033,23 +10669,23 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
         if (!validatePath(vaultPath2, notePath)) {
           return formatMcpResult(errorResult(notePath, "Invalid path: path traversal not allowed"));
         }
-        const fullPath = path18.join(vaultPath2, notePath);
+        const fullPath = path19.join(vaultPath2, notePath);
         const existsCheck = await ensureFileExists(vaultPath2, notePath);
         if (existsCheck === null && !overwrite) {
           return formatMcpResult(errorResult(notePath, `File already exists: ${notePath}. Use overwrite=true to replace.`));
         }
-        const dir = path18.dirname(fullPath);
-        await fs18.mkdir(dir, { recursive: true });
+        const dir = path19.dirname(fullPath);
+        await fs20.mkdir(dir, { recursive: true });
         let effectiveContent = content;
         let effectiveFrontmatter = frontmatter;
         if (template) {
-          const templatePath = path18.join(vaultPath2, template);
+          const templatePath = path19.join(vaultPath2, template);
           try {
-            const raw = await fs18.readFile(templatePath, "utf-8");
+            const raw = await fs20.readFile(templatePath, "utf-8");
             const matter9 = (await import("gray-matter")).default;
             const parsed = matter9(raw);
             const dateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-            const title = path18.basename(notePath, ".md");
+            const title = path19.basename(notePath, ".md");
             let templateContent = parsed.content.replace(/\{\{date\}\}/g, dateStr).replace(/\{\{title\}\}/g, title);
             if (content) {
               templateContent = templateContent.trimEnd() + "\n\n" + content;
@@ -10061,7 +10697,7 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
           }
         }
         const warnings = [];
-        const noteName = path18.basename(notePath, ".md");
+        const noteName = path19.basename(notePath, ".md");
         const existingAliases = Array.isArray(effectiveFrontmatter?.aliases) ? effectiveFrontmatter.aliases.filter((a) => typeof a === "string") : [];
         const preflight = checkPreflightSimilarity(noteName);
         if (preflight.existingEntity) {
@@ -10178,8 +10814,8 @@ ${sources}`;
           }
           return formatMcpResult(errorResult(notePath, previewLines.join("\n")));
         }
-        const fullPath = path18.join(vaultPath2, notePath);
-        await fs18.unlink(fullPath);
+        const fullPath = path19.join(vaultPath2, notePath);
+        await fs20.unlink(fullPath);
         const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Delete]");
         const message = backlinkWarning ? `Deleted note: ${notePath}
 
@@ -10197,8 +10833,8 @@ Warning: ${backlinkWarning}` : `Deleted note: ${notePath}`;
 // src/tools/write/move-notes.ts
 init_writer();
 import { z as z15 } from "zod";
-import fs19 from "fs/promises";
-import path19 from "path";
+import fs21 from "fs/promises";
+import path20 from "path";
 import matter6 from "gray-matter";
 function escapeRegex(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -10217,16 +10853,16 @@ function extractWikilinks2(content) {
   return wikilinks;
 }
 function getTitleFromPath(filePath) {
-  return path19.basename(filePath, ".md");
+  return path20.basename(filePath, ".md");
 }
 async function findBacklinks(vaultPath2, targetTitle, targetAliases) {
   const results = [];
   const allTargets = [targetTitle, ...targetAliases].map((t) => t.toLowerCase());
   async function scanDir(dir) {
     const files = [];
-    const entries = await fs19.readdir(dir, { withFileTypes: true });
+    const entries = await fs21.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = path19.join(dir, entry.name);
+      const fullPath = path20.join(dir, entry.name);
       if (entry.isDirectory() && !entry.name.startsWith(".")) {
         files.push(...await scanDir(fullPath));
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -10237,8 +10873,8 @@ async function findBacklinks(vaultPath2, targetTitle, targetAliases) {
   }
   const allFiles = await scanDir(vaultPath2);
   for (const filePath of allFiles) {
-    const relativePath = path19.relative(vaultPath2, filePath);
-    const content = await fs19.readFile(filePath, "utf-8");
+    const relativePath = path20.relative(vaultPath2, filePath);
+    const content = await fs21.readFile(filePath, "utf-8");
     const wikilinks = extractWikilinks2(content);
     const matchingLinks = [];
     for (const link of wikilinks) {
@@ -10257,8 +10893,8 @@ async function findBacklinks(vaultPath2, targetTitle, targetAliases) {
   return results;
 }
 async function updateBacklinksInFile(vaultPath2, filePath, oldTitles, newTitle) {
-  const fullPath = path19.join(vaultPath2, filePath);
-  const raw = await fs19.readFile(fullPath, "utf-8");
+  const fullPath = path20.join(vaultPath2, filePath);
+  const raw = await fs21.readFile(fullPath, "utf-8");
   const parsed = matter6(raw);
   let content = parsed.content;
   let totalUpdated = 0;
@@ -10324,10 +10960,10 @@ function registerMoveNoteTools(server2, vaultPath2) {
           };
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
-        const oldFullPath = path19.join(vaultPath2, oldPath);
-        const newFullPath = path19.join(vaultPath2, newPath);
+        const oldFullPath = path20.join(vaultPath2, oldPath);
+        const newFullPath = path20.join(vaultPath2, newPath);
         try {
-          await fs19.access(oldFullPath);
+          await fs21.access(oldFullPath);
         } catch {
           const result2 = {
             success: false,
@@ -10337,7 +10973,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         try {
-          await fs19.access(newFullPath);
+          await fs21.access(newFullPath);
           const result2 = {
             success: false,
             message: `Destination already exists: ${newPath}`,
@@ -10346,7 +10982,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         } catch {
         }
-        const sourceContent = await fs19.readFile(oldFullPath, "utf-8");
+        const sourceContent = await fs21.readFile(oldFullPath, "utf-8");
         const parsed = matter6(sourceContent);
         const aliases = extractAliases2(parsed.data);
         const oldTitle = getTitleFromPath(oldPath);
@@ -10375,9 +11011,9 @@ function registerMoveNoteTools(server2, vaultPath2) {
             }
           }
         }
-        const destDir = path19.dirname(newFullPath);
-        await fs19.mkdir(destDir, { recursive: true });
-        await fs19.rename(oldFullPath, newFullPath);
+        const destDir = path20.dirname(newFullPath);
+        await fs21.mkdir(destDir, { recursive: true });
+        await fs21.rename(oldFullPath, newFullPath);
         let gitCommit;
         let undoAvailable;
         let staleLockDetected;
@@ -10461,12 +11097,12 @@ function registerMoveNoteTools(server2, vaultPath2) {
         if (sanitizedTitle !== newTitle) {
           console.error(`[Flywheel] Title sanitized: "${newTitle}" \u2192 "${sanitizedTitle}"`);
         }
-        const fullPath = path19.join(vaultPath2, notePath);
-        const dir = path19.dirname(notePath);
-        const newPath = dir === "." ? `${sanitizedTitle}.md` : path19.join(dir, `${sanitizedTitle}.md`);
-        const newFullPath = path19.join(vaultPath2, newPath);
+        const fullPath = path20.join(vaultPath2, notePath);
+        const dir = path20.dirname(notePath);
+        const newPath = dir === "." ? `${sanitizedTitle}.md` : path20.join(dir, `${sanitizedTitle}.md`);
+        const newFullPath = path20.join(vaultPath2, newPath);
         try {
-          await fs19.access(fullPath);
+          await fs21.access(fullPath);
         } catch {
           const result2 = {
             success: false,
@@ -10477,7 +11113,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
         }
         if (fullPath !== newFullPath) {
           try {
-            await fs19.access(newFullPath);
+            await fs21.access(newFullPath);
             const result2 = {
               success: false,
               message: `A note with this title already exists: ${newPath}`,
@@ -10487,7 +11123,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
           } catch {
           }
         }
-        const sourceContent = await fs19.readFile(fullPath, "utf-8");
+        const sourceContent = await fs21.readFile(fullPath, "utf-8");
         const parsed = matter6(sourceContent);
         const aliases = extractAliases2(parsed.data);
         const oldTitle = getTitleFromPath(notePath);
@@ -10516,7 +11152,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
           }
         }
         if (fullPath !== newFullPath) {
-          await fs19.rename(fullPath, newFullPath);
+          await fs21.rename(fullPath, newFullPath);
         }
         let gitCommit;
         let undoAvailable;
@@ -10689,8 +11325,8 @@ init_schema();
 
 // src/core/write/policy/parser.ts
 init_schema();
-import fs20 from "fs/promises";
-import path20 from "path";
+import fs22 from "fs/promises";
+import path21 from "path";
 import matter7 from "gray-matter";
 function parseYaml(content) {
   const parsed = matter7(`---
@@ -10715,7 +11351,7 @@ function parsePolicyString(yamlContent) {
 }
 async function loadPolicyFile(filePath) {
   try {
-    const content = await fs20.readFile(filePath, "utf-8");
+    const content = await fs22.readFile(filePath, "utf-8");
     return parsePolicyString(content);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -10739,15 +11375,15 @@ async function loadPolicyFile(filePath) {
   }
 }
 async function loadPolicy(vaultPath2, policyName) {
-  const policiesDir = path20.join(vaultPath2, ".claude", "policies");
-  const policyPath = path20.join(policiesDir, `${policyName}.yaml`);
+  const policiesDir = path21.join(vaultPath2, ".claude", "policies");
+  const policyPath = path21.join(policiesDir, `${policyName}.yaml`);
   try {
-    await fs20.access(policyPath);
+    await fs22.access(policyPath);
     return loadPolicyFile(policyPath);
   } catch {
-    const ymlPath = path20.join(policiesDir, `${policyName}.yml`);
+    const ymlPath = path21.join(policiesDir, `${policyName}.yml`);
     try {
-      await fs20.access(ymlPath);
+      await fs22.access(ymlPath);
       return loadPolicyFile(ymlPath);
     } catch {
       return {
@@ -10885,8 +11521,8 @@ init_template();
 init_conditions();
 init_schema();
 init_writer();
-import fs22 from "fs/promises";
-import path22 from "path";
+import fs24 from "fs/promises";
+import path23 from "path";
 init_constants();
 async function executeStep(step, vaultPath2, context, conditionResults) {
   const { execute, reason } = shouldStepExecute(step.when, conditionResults);
@@ -10955,9 +11591,9 @@ async function executeAddToSection(params, vaultPath2, context) {
   const preserveListNesting = params.preserveListNesting !== false;
   const suggestOutgoingLinks = params.suggestOutgoingLinks !== false;
   const maxSuggestions = Number(params.maxSuggestions) || 3;
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -10995,9 +11631,9 @@ async function executeRemoveFromSection(params, vaultPath2) {
   const pattern = String(params.pattern || "");
   const mode = params.mode || "first";
   const useRegex = Boolean(params.useRegex);
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -11026,9 +11662,9 @@ async function executeReplaceInSection(params, vaultPath2, context) {
   const mode = params.mode || "first";
   const useRegex = Boolean(params.useRegex);
   const skipWikilinks = Boolean(params.skipWikilinks);
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -11069,16 +11705,16 @@ async function executeCreateNote(params, vaultPath2, context) {
   if (!validatePath(vaultPath2, notePath)) {
     return { success: false, message: "Invalid path: path traversal not allowed", path: notePath };
   }
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
     if (!overwrite) {
       return { success: false, message: `File already exists: ${notePath}`, path: notePath };
     }
   } catch {
   }
-  const dir = path22.dirname(fullPath);
-  await fs22.mkdir(dir, { recursive: true });
+  const dir = path23.dirname(fullPath);
+  await fs24.mkdir(dir, { recursive: true });
   const { content: processedContent } = maybeApplyWikilinks(content, skipWikilinks, notePath);
   await writeVaultFile(vaultPath2, notePath, processedContent, frontmatter);
   return {
@@ -11097,13 +11733,13 @@ async function executeDeleteNote(params, vaultPath2) {
   if (!validatePath(vaultPath2, notePath)) {
     return { success: false, message: "Invalid path: path traversal not allowed", path: notePath };
   }
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
-  await fs22.unlink(fullPath);
+  await fs24.unlink(fullPath);
   return {
     success: true,
     message: `Deleted note: ${notePath}`,
@@ -11114,9 +11750,9 @@ async function executeToggleTask(params, vaultPath2) {
   const notePath = String(params.path || "");
   const task = String(params.task || "");
   const section = params.section ? String(params.section) : void 0;
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -11157,9 +11793,9 @@ async function executeAddTask(params, vaultPath2, context) {
   const completed = Boolean(params.completed);
   const skipWikilinks = Boolean(params.skipWikilinks);
   const preserveListNesting = params.preserveListNesting !== false;
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -11194,9 +11830,9 @@ async function executeAddTask(params, vaultPath2, context) {
 async function executeUpdateFrontmatter(params, vaultPath2) {
   const notePath = String(params.path || "");
   const updates = params.frontmatter || {};
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -11216,9 +11852,9 @@ async function executeAddFrontmatterField(params, vaultPath2) {
   const notePath = String(params.path || "");
   const key = String(params.key || "");
   const value = params.value;
-  const fullPath = path22.join(vaultPath2, notePath);
+  const fullPath = path23.join(vaultPath2, notePath);
   try {
-    await fs22.access(fullPath);
+    await fs24.access(fullPath);
   } catch {
     return { success: false, message: `File not found: ${notePath}`, path: notePath };
   }
@@ -11376,15 +12012,15 @@ async function executePolicy(policy, vaultPath2, variables, commit = false) {
 async function rollbackChanges(vaultPath2, originalContents, filesModified) {
   for (const filePath of filesModified) {
     const original = originalContents.get(filePath);
-    const fullPath = path22.join(vaultPath2, filePath);
+    const fullPath = path23.join(vaultPath2, filePath);
     if (original === null) {
       try {
-        await fs22.unlink(fullPath);
+        await fs24.unlink(fullPath);
       } catch {
       }
     } else if (original !== void 0) {
       try {
-        await fs22.writeFile(fullPath, original);
+        await fs24.writeFile(fullPath, original);
       } catch {
       }
     }
@@ -11430,27 +12066,27 @@ async function previewPolicy(policy, vaultPath2, variables) {
 }
 
 // src/core/write/policy/storage.ts
-import fs23 from "fs/promises";
-import path23 from "path";
+import fs25 from "fs/promises";
+import path24 from "path";
 function getPoliciesDir(vaultPath2) {
-  return path23.join(vaultPath2, ".claude", "policies");
+  return path24.join(vaultPath2, ".claude", "policies");
 }
 async function ensurePoliciesDir(vaultPath2) {
   const dir = getPoliciesDir(vaultPath2);
-  await fs23.mkdir(dir, { recursive: true });
+  await fs25.mkdir(dir, { recursive: true });
 }
 async function listPolicies(vaultPath2) {
   const dir = getPoliciesDir(vaultPath2);
   const policies = [];
   try {
-    const files = await fs23.readdir(dir);
+    const files = await fs25.readdir(dir);
     for (const file of files) {
       if (!file.endsWith(".yaml") && !file.endsWith(".yml")) {
         continue;
       }
-      const filePath = path23.join(dir, file);
-      const stat3 = await fs23.stat(filePath);
-      const content = await fs23.readFile(filePath, "utf-8");
+      const filePath = path24.join(dir, file);
+      const stat3 = await fs25.stat(filePath);
+      const content = await fs25.readFile(filePath, "utf-8");
       const metadata = extractPolicyMetadata(content);
       policies.push({
         name: metadata.name || file.replace(/\.ya?ml$/, ""),
@@ -11473,10 +12109,10 @@ async function writePolicyRaw(vaultPath2, policyName, content, overwrite = false
   const dir = getPoliciesDir(vaultPath2);
   await ensurePoliciesDir(vaultPath2);
   const filename = `${policyName}.yaml`;
-  const filePath = path23.join(dir, filename);
+  const filePath = path24.join(dir, filename);
   if (!overwrite) {
     try {
-      await fs23.access(filePath);
+      await fs25.access(filePath);
       return {
         success: false,
         path: filename,
@@ -11493,7 +12129,7 @@ async function writePolicyRaw(vaultPath2, policyName, content, overwrite = false
       message: `Invalid policy: ${validation.errors.map((e) => e.message).join("; ")}`
     };
   }
-  await fs23.writeFile(filePath, content, "utf-8");
+  await fs25.writeFile(filePath, content, "utf-8");
   return {
     success: true,
     path: filename,
@@ -12016,8 +12652,8 @@ function registerPolicyTools(server2, vaultPath2) {
 import { z as z19 } from "zod";
 
 // src/core/write/tagRename.ts
-import * as fs24 from "fs/promises";
-import * as path24 from "path";
+import * as fs26 from "fs/promises";
+import * as path25 from "path";
 import matter8 from "gray-matter";
 import { getProtectedZones } from "@velvetmonkey/vault-core";
 function getNotesInFolder3(index, folder) {
@@ -12123,10 +12759,10 @@ async function renameTag(index, vaultPath2, oldTag, newTag, options) {
   const previews = [];
   let totalChanges = 0;
   for (const note of affectedNotes) {
-    const fullPath = path24.join(vaultPath2, note.path);
+    const fullPath = path25.join(vaultPath2, note.path);
     let fileContent;
     try {
-      fileContent = await fs24.readFile(fullPath, "utf-8");
+      fileContent = await fs26.readFile(fullPath, "utf-8");
     } catch {
       continue;
     }
@@ -12186,385 +12822,987 @@ async function renameTag(index, vaultPath2, oldTag, newTag, options) {
         fm.tags = newTags;
       }
     }
-    const { content: updatedContent, changes: contentChanges } = replaceInlineTags(
-      parsed.content,
-      cleanOld,
-      cleanNew,
-      renameChildren
-    );
-    preview.content_changes = contentChanges;
-    preview.total_changes = preview.frontmatter_changes.length + preview.content_changes.length;
-    totalChanges += preview.total_changes;
-    if (preview.total_changes > 0) {
-      previews.push(preview);
-      if (!dryRun) {
-        const newContent = matter8.stringify(updatedContent, fm);
-        await fs24.writeFile(fullPath, newContent, "utf-8");
-      }
+    const { content: updatedContent, changes: contentChanges } = replaceInlineTags(
+      parsed.content,
+      cleanOld,
+      cleanNew,
+      renameChildren
+    );
+    preview.content_changes = contentChanges;
+    preview.total_changes = preview.frontmatter_changes.length + preview.content_changes.length;
+    totalChanges += preview.total_changes;
+    if (preview.total_changes > 0) {
+      previews.push(preview);
+      if (!dryRun) {
+        const newContent = matter8.stringify(updatedContent, fm);
+        await fs26.writeFile(fullPath, newContent, "utf-8");
+      }
+    }
+  }
+  return {
+    old_tag: cleanOld,
+    new_tag: cleanNew,
+    rename_children: renameChildren,
+    dry_run: dryRun,
+    affected_notes: previews.length,
+    total_changes: totalChanges,
+    previews
+  };
+}
+
+// src/tools/write/tags.ts
+function registerTagTools(server2, getIndex, getVaultPath) {
+  server2.registerTool(
+    "rename_tag",
+    {
+      title: "Rename Tag",
+      description: "Bulk rename a tag across all notes (frontmatter and inline). Supports hierarchical rename (#project \u2192 #work also transforms #project/active \u2192 #work/active). Dry-run by default (preview only). Handles deduplication when new tag already exists.",
+      inputSchema: {
+        old_tag: z19.string().describe('Tag to rename (without #, e.g., "project")'),
+        new_tag: z19.string().describe('New tag name (without #, e.g., "work")'),
+        rename_children: z19.boolean().optional().describe("Also rename child tags (e.g., #project/active \u2192 #work/active). Default: true"),
+        folder: z19.string().optional().describe('Limit to notes in this folder (e.g., "projects")'),
+        dry_run: z19.boolean().optional().describe("Preview only, no changes (default: true)"),
+        commit: z19.boolean().optional().describe("Commit changes to git (default: false)")
+      }
+    },
+    async ({ old_tag, new_tag, rename_children, folder, dry_run, commit }) => {
+      const index = getIndex();
+      const vaultPath2 = getVaultPath();
+      const result = await renameTag(index, vaultPath2, old_tag, new_tag, {
+        rename_children: rename_children ?? true,
+        folder,
+        dry_run: dry_run ?? true,
+        commit: commit ?? false
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/write/wikilinkFeedback.ts
+import { z as z20 } from "zod";
+function registerWikilinkFeedbackTools(server2, getStateDb) {
+  server2.registerTool(
+    "wikilink_feedback",
+    {
+      title: "Wikilink Feedback",
+      description: 'Report and query wikilink accuracy feedback. Modes: "report" (record feedback), "list" (view recent feedback), "stats" (entity accuracy statistics). Entities with >=30% false positive rate (and >=10 samples) are auto-suppressed from future wikilink application.',
+      inputSchema: {
+        mode: z20.enum(["report", "list", "stats"]).describe("Operation mode"),
+        entity: z20.string().optional().describe("Entity name (required for report mode, optional filter for list/stats)"),
+        note_path: z20.string().optional().describe("Note path where the wikilink appeared (for report mode)"),
+        context: z20.string().optional().describe("Surrounding text context (for report mode)"),
+        correct: z20.boolean().optional().describe("Whether the wikilink was correct (for report mode)"),
+        limit: z20.number().optional().describe("Max entries to return for list mode (default: 20)")
+      }
+    },
+    async ({ mode, entity, note_path, context, correct, limit }) => {
+      const stateDb2 = getStateDb();
+      if (!stateDb2) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available" }) }]
+        };
+      }
+      let result;
+      switch (mode) {
+        case "report": {
+          if (!entity || correct === void 0) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "entity and correct are required for report mode" }) }]
+            };
+          }
+          recordFeedback(stateDb2, entity, context || "", note_path || "", correct);
+          const suppressionUpdated = updateSuppressionList(stateDb2) > 0;
+          result = {
+            mode: "report",
+            reported: {
+              entity,
+              correct,
+              suppression_updated: suppressionUpdated
+            },
+            total_suppressed: getSuppressedCount(stateDb2)
+          };
+          break;
+        }
+        case "list": {
+          const entries = getFeedback(stateDb2, entity, limit ?? 20);
+          result = {
+            mode: "list",
+            entries,
+            total_feedback: entries.length
+          };
+          break;
+        }
+        case "stats": {
+          const stats = getEntityStats(stateDb2);
+          result = {
+            mode: "stats",
+            stats,
+            total_feedback: stats.reduce((sum, s) => sum + s.total, 0),
+            total_suppressed: getSuppressedCount(stateDb2)
+          };
+          break;
+        }
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/read/metrics.ts
+import { z as z21 } from "zod";
+
+// src/core/shared/metrics.ts
+var ALL_METRICS = [
+  "note_count",
+  "link_count",
+  "orphan_count",
+  "tag_count",
+  "entity_count",
+  "avg_links_per_note",
+  "link_density",
+  "connected_ratio",
+  "wikilink_accuracy",
+  "wikilink_feedback_volume",
+  "wikilink_suppressed_count"
+];
+function computeMetrics(index, stateDb2) {
+  const noteCount = index.notes.size;
+  let linkCount = 0;
+  for (const note of index.notes.values()) {
+    linkCount += note.outlinks.length;
+  }
+  const connectedNotes = /* @__PURE__ */ new Set();
+  for (const [notePath, note] of index.notes) {
+    if (note.outlinks.length > 0) {
+      connectedNotes.add(notePath);
+    }
+  }
+  for (const [target, backlinks] of index.backlinks) {
+    for (const bl of backlinks) {
+      connectedNotes.add(bl.source);
+    }
+    for (const note of index.notes.values()) {
+      const normalizedTitle = note.title.toLowerCase();
+      if (normalizedTitle === target.toLowerCase() || note.path.toLowerCase() === target.toLowerCase()) {
+        connectedNotes.add(note.path);
+      }
+    }
+  }
+  let orphanCount = 0;
+  for (const [notePath, note] of index.notes) {
+    if (!connectedNotes.has(notePath)) {
+      orphanCount++;
+    }
+  }
+  const tagCount = index.tags.size;
+  const entityCount = index.entities.size;
+  const avgLinksPerNote = noteCount > 0 ? linkCount / noteCount : 0;
+  const possibleLinks = noteCount * (noteCount - 1);
+  const linkDensity = possibleLinks > 0 ? linkCount / possibleLinks : 0;
+  const connectedRatio = noteCount > 0 ? connectedNotes.size / noteCount : 0;
+  let wikilinkAccuracy = 0;
+  let wikilinkFeedbackVolume = 0;
+  let wikilinkSuppressedCount = 0;
+  if (stateDb2) {
+    const entityStatsList = getEntityStats(stateDb2);
+    wikilinkFeedbackVolume = entityStatsList.reduce((sum, s) => sum + s.total, 0);
+    if (wikilinkFeedbackVolume > 0) {
+      const totalCorrect = entityStatsList.reduce((sum, s) => sum + s.correct, 0);
+      wikilinkAccuracy = Math.round(totalCorrect / wikilinkFeedbackVolume * 1e3) / 1e3;
     }
+    wikilinkSuppressedCount = getSuppressedCount(stateDb2);
   }
   return {
-    old_tag: cleanOld,
-    new_tag: cleanNew,
-    rename_children: renameChildren,
-    dry_run: dryRun,
-    affected_notes: previews.length,
-    total_changes: totalChanges,
-    previews
+    note_count: noteCount,
+    link_count: linkCount,
+    orphan_count: orphanCount,
+    tag_count: tagCount,
+    entity_count: entityCount,
+    avg_links_per_note: Math.round(avgLinksPerNote * 100) / 100,
+    link_density: Math.round(linkDensity * 1e4) / 1e4,
+    connected_ratio: Math.round(connectedRatio * 1e3) / 1e3,
+    wikilink_accuracy: wikilinkAccuracy,
+    wikilink_feedback_volume: wikilinkFeedbackVolume,
+    wikilink_suppressed_count: wikilinkSuppressedCount
   };
 }
+function recordMetrics(stateDb2, metrics) {
+  const timestamp = Date.now();
+  const insert = stateDb2.db.prepare(
+    "INSERT INTO vault_metrics (timestamp, metric, value) VALUES (?, ?, ?)"
+  );
+  const transaction = stateDb2.db.transaction(() => {
+    for (const [metric, value] of Object.entries(metrics)) {
+      insert.run(timestamp, metric, value);
+    }
+  });
+  transaction();
+}
+function getMetricHistory(stateDb2, metric, daysBack = 30) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  let rows;
+  if (metric) {
+    rows = stateDb2.db.prepare(
+      "SELECT timestamp, metric, value FROM vault_metrics WHERE metric = ? AND timestamp >= ? ORDER BY timestamp"
+    ).all(metric, cutoff);
+  } else {
+    rows = stateDb2.db.prepare(
+      "SELECT timestamp, metric, value FROM vault_metrics WHERE timestamp >= ? ORDER BY timestamp"
+    ).all(cutoff);
+  }
+  return rows.map((r) => ({
+    metric: r.metric,
+    value: r.value,
+    timestamp: r.timestamp
+  }));
+}
+function computeTrends(stateDb2, currentMetrics, daysBack = 30) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  const rows = stateDb2.db.prepare(`
+    SELECT metric, value FROM vault_metrics
+    WHERE timestamp >= ? AND timestamp <= ?
+    GROUP BY metric
+    HAVING timestamp = MIN(timestamp)
+  `).all(cutoff, cutoff + 24 * 60 * 60 * 1e3);
+  const previousValues = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    previousValues.set(row.metric, row.value);
+  }
+  if (previousValues.size === 0) {
+    const fallbackRows = stateDb2.db.prepare(`
+      SELECT metric, MIN(value) as value FROM vault_metrics
+      WHERE timestamp >= ?
+      GROUP BY metric
+      HAVING timestamp = MIN(timestamp)
+    `).all(cutoff);
+    for (const row of fallbackRows) {
+      previousValues.set(row.metric, row.value);
+    }
+  }
+  const trends = [];
+  for (const metricName of ALL_METRICS) {
+    const current = currentMetrics[metricName] ?? 0;
+    const previous = previousValues.get(metricName) ?? current;
+    const delta = current - previous;
+    const deltaPct = previous !== 0 ? Math.round(delta / previous * 1e4) / 100 : delta !== 0 ? 100 : 0;
+    let direction = "stable";
+    if (delta > 0) direction = "up";
+    if (delta < 0) direction = "down";
+    trends.push({
+      metric: metricName,
+      current,
+      previous,
+      delta,
+      delta_percent: deltaPct,
+      direction
+    });
+  }
+  return trends;
+}
+function purgeOldMetrics(stateDb2, retentionDays = 90) {
+  const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1e3;
+  const result = stateDb2.db.prepare(
+    "DELETE FROM vault_metrics WHERE timestamp < ?"
+  ).run(cutoff);
+  return result.changes;
+}
 
-// src/tools/write/tags.ts
-function registerTagTools(server2, getIndex, getVaultPath) {
+// src/tools/read/metrics.ts
+function registerMetricsTools(server2, getIndex, getStateDb) {
   server2.registerTool(
-    "rename_tag",
+    "vault_growth",
     {
-      title: "Rename Tag",
-      description: "Bulk rename a tag across all notes (frontmatter and inline). Supports hierarchical rename (#project \u2192 #work also transforms #project/active \u2192 #work/active). Dry-run by default (preview only). Handles deduplication when new tag already exists.",
+      title: "Vault Growth",
+      description: 'Track vault growth over time. Modes: "current" (live snapshot), "history" (time series), "trends" (deltas vs N days ago), "index_activity" (rebuild history). Tracks 11 metrics: note_count, link_count, orphan_count, tag_count, entity_count, avg_links_per_note, link_density, connected_ratio, wikilink_accuracy, wikilink_feedback_volume, wikilink_suppressed_count.',
       inputSchema: {
-        old_tag: z19.string().describe('Tag to rename (without #, e.g., "project")'),
-        new_tag: z19.string().describe('New tag name (without #, e.g., "work")'),
-        rename_children: z19.boolean().optional().describe("Also rename child tags (e.g., #project/active \u2192 #work/active). Default: true"),
-        folder: z19.string().optional().describe('Limit to notes in this folder (e.g., "projects")'),
-        dry_run: z19.boolean().optional().describe("Preview only, no changes (default: true)"),
-        commit: z19.boolean().optional().describe("Commit changes to git (default: false)")
+        mode: z21.enum(["current", "history", "trends", "index_activity"]).describe("Query mode: current snapshot, historical time series, trend analysis, or index rebuild activity"),
+        metric: z21.string().optional().describe('Filter to specific metric (e.g., "note_count"). Omit for all metrics.'),
+        days_back: z21.number().optional().describe("Number of days to look back for history/trends (default: 30)"),
+        limit: z21.number().optional().describe("Number of recent events to return for index_activity mode (default: 20)")
       }
     },
-    async ({ old_tag, new_tag, rename_children, folder, dry_run, commit }) => {
+    async ({ mode, metric, days_back, limit: eventLimit }) => {
       const index = getIndex();
-      const vaultPath2 = getVaultPath();
-      const result = await renameTag(index, vaultPath2, old_tag, new_tag, {
-        rename_children: rename_children ?? true,
-        folder,
-        dry_run: dry_run ?? true,
-        commit: commit ?? false
-      });
+      const stateDb2 = getStateDb();
+      const daysBack = days_back ?? 30;
+      let result;
+      switch (mode) {
+        case "current": {
+          const metrics = computeMetrics(index, stateDb2 ?? void 0);
+          result = {
+            mode: "current",
+            metrics,
+            recorded_at: Date.now()
+          };
+          break;
+        }
+        case "history": {
+          if (!stateDb2) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available for historical queries" }) }]
+            };
+          }
+          const history = getMetricHistory(stateDb2, metric, daysBack);
+          result = {
+            mode: "history",
+            history
+          };
+          break;
+        }
+        case "trends": {
+          if (!stateDb2) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available for trend analysis" }) }]
+            };
+          }
+          const currentMetrics = computeMetrics(index, stateDb2);
+          const trends = computeTrends(stateDb2, currentMetrics, daysBack);
+          result = {
+            mode: "trends",
+            trends
+          };
+          break;
+        }
+        case "index_activity": {
+          if (!stateDb2) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available for index activity queries" }) }]
+            };
+          }
+          const summary = getIndexActivitySummary(stateDb2);
+          const recentEvents = getRecentIndexEvents(stateDb2, eventLimit ?? 20);
+          result = {
+            mode: "index_activity",
+            index_activity: { summary, recent_events: recentEvents }
+          };
+          break;
+        }
+      }
       return {
         content: [
           {
             type: "text",
             text: JSON.stringify(result, null, 2)
           }
-        ]
-      };
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/read/activity.ts
+import { z as z22 } from "zod";
+
+// src/core/shared/toolTracking.ts
+function recordToolInvocation(stateDb2, event) {
+  stateDb2.db.prepare(
+    `INSERT INTO tool_invocations (timestamp, tool_name, session_id, note_paths, duration_ms, success)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  ).run(
+    Date.now(),
+    event.tool_name,
+    event.session_id ?? null,
+    event.note_paths ? JSON.stringify(event.note_paths) : null,
+    event.duration_ms ?? null,
+    event.success !== false ? 1 : 0
+  );
+}
+function rowToInvocation(row) {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    tool_name: row.tool_name,
+    session_id: row.session_id,
+    note_paths: row.note_paths ? JSON.parse(row.note_paths) : null,
+    duration_ms: row.duration_ms,
+    success: row.success === 1
+  };
+}
+function getToolUsageSummary(stateDb2, daysBack = 30) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  const rows = stateDb2.db.prepare(`
+    SELECT
+      tool_name,
+      COUNT(*) as invocation_count,
+      AVG(duration_ms) as avg_duration_ms,
+      SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) * 1.0 / COUNT(*) as success_rate,
+      MAX(timestamp) as last_used
+    FROM tool_invocations
+    WHERE timestamp >= ?
+    GROUP BY tool_name
+    ORDER BY invocation_count DESC
+  `).all(cutoff);
+  return rows.map((r) => ({
+    tool_name: r.tool_name,
+    invocation_count: r.invocation_count,
+    avg_duration_ms: Math.round(r.avg_duration_ms ?? 0),
+    success_rate: Math.round(r.success_rate * 1e3) / 1e3,
+    last_used: r.last_used
+  }));
+}
+function getNoteAccessFrequency(stateDb2, daysBack = 30) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  const rows = stateDb2.db.prepare(`
+    SELECT note_paths, tool_name, timestamp
+    FROM tool_invocations
+    WHERE timestamp >= ? AND note_paths IS NOT NULL
+    ORDER BY timestamp DESC
+  `).all(cutoff);
+  const noteMap = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    let paths;
+    try {
+      paths = JSON.parse(row.note_paths);
+    } catch {
+      continue;
+    }
+    for (const p of paths) {
+      const existing = noteMap.get(p);
+      if (existing) {
+        existing.access_count++;
+        existing.last_accessed = Math.max(existing.last_accessed, row.timestamp);
+        existing.tools.add(row.tool_name);
+      } else {
+        noteMap.set(p, {
+          access_count: 1,
+          last_accessed: row.timestamp,
+          tools: /* @__PURE__ */ new Set([row.tool_name])
+        });
+      }
+    }
+  }
+  return Array.from(noteMap.entries()).map(([path28, stats]) => ({
+    path: path28,
+    access_count: stats.access_count,
+    last_accessed: stats.last_accessed,
+    tools_used: Array.from(stats.tools)
+  })).sort((a, b) => b.access_count - a.access_count);
+}
+function getSessionHistory(stateDb2, sessionId) {
+  if (sessionId) {
+    const rows2 = stateDb2.db.prepare(`
+      SELECT * FROM tool_invocations
+      WHERE session_id = ?
+      ORDER BY timestamp
+    `).all(sessionId);
+    if (rows2.length === 0) return [];
+    const tools = /* @__PURE__ */ new Set();
+    const notes = /* @__PURE__ */ new Set();
+    for (const row of rows2) {
+      tools.add(row.tool_name);
+      if (row.note_paths) {
+        try {
+          for (const p of JSON.parse(row.note_paths)) {
+            notes.add(p);
+          }
+        } catch {
+        }
+      }
     }
-  );
+    return [{
+      session_id: sessionId,
+      started_at: rows2[0].timestamp,
+      last_activity: rows2[rows2.length - 1].timestamp,
+      tool_count: rows2.length,
+      unique_tools: Array.from(tools),
+      notes_accessed: Array.from(notes)
+    }];
+  }
+  const rows = stateDb2.db.prepare(`
+    SELECT
+      session_id,
+      MIN(timestamp) as started_at,
+      MAX(timestamp) as last_activity,
+      COUNT(*) as tool_count
+    FROM tool_invocations
+    WHERE session_id IS NOT NULL
+    GROUP BY session_id
+    ORDER BY last_activity DESC
+    LIMIT 20
+  `).all();
+  return rows.map((r) => ({
+    session_id: r.session_id,
+    started_at: r.started_at,
+    last_activity: r.last_activity,
+    tool_count: r.tool_count,
+    unique_tools: [],
+    notes_accessed: []
+  }));
+}
+function getRecentInvocations(stateDb2, limit = 20) {
+  const rows = stateDb2.db.prepare(
+    "SELECT * FROM tool_invocations ORDER BY timestamp DESC LIMIT ?"
+  ).all(limit);
+  return rows.map(rowToInvocation);
+}
+function purgeOldInvocations(stateDb2, retentionDays = 90) {
+  const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1e3;
+  const result = stateDb2.db.prepare(
+    "DELETE FROM tool_invocations WHERE timestamp < ?"
+  ).run(cutoff);
+  return result.changes;
 }
 
-// src/tools/write/wikilinkFeedback.ts
-import { z as z20 } from "zod";
-function registerWikilinkFeedbackTools(server2, getStateDb) {
+// src/tools/read/activity.ts
+function registerActivityTools(server2, getStateDb, getSessionId2) {
   server2.registerTool(
-    "wikilink_feedback",
+    "vault_activity",
     {
-      title: "Wikilink Feedback",
-      description: 'Report and query wikilink accuracy feedback. Modes: "report" (record feedback), "list" (view recent feedback), "stats" (entity accuracy statistics). Entities with >=30% false positive rate (and >=10 samples) are auto-suppressed from future wikilink application.',
+      title: "Vault Activity",
+      description: 'Track tool usage patterns and session activity. Modes:\n- "session": Current session summary (tools called, notes accessed)\n- "sessions": List of recent sessions\n- "note_access": Notes ranked by query frequency\n- "tool_usage": Tool usage patterns (most-used tools, avg duration)',
       inputSchema: {
-        mode: z20.enum(["report", "list", "stats"]).describe("Operation mode"),
-        entity: z20.string().optional().describe("Entity name (required for report mode, optional filter for list/stats)"),
-        note_path: z20.string().optional().describe("Note path where the wikilink appeared (for report mode)"),
-        context: z20.string().optional().describe("Surrounding text context (for report mode)"),
-        correct: z20.boolean().optional().describe("Whether the wikilink was correct (for report mode)"),
-        limit: z20.number().optional().describe("Max entries to return for list mode (default: 20)")
+        mode: z22.enum(["session", "sessions", "note_access", "tool_usage"]).describe("Activity query mode"),
+        session_id: z22.string().optional().describe("Specific session ID (for session mode, defaults to current)"),
+        days_back: z22.number().optional().describe("Number of days to look back (default: 30)"),
+        limit: z22.number().optional().describe("Maximum results to return (default: 20)")
       }
     },
-    async ({ mode, entity, note_path, context, correct, limit }) => {
+    async ({ mode, session_id, days_back, limit: resultLimit }) => {
       const stateDb2 = getStateDb();
       if (!stateDb2) {
         return {
           content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available" }) }]
         };
       }
-      let result;
+      const daysBack = days_back ?? 30;
+      const limit = resultLimit ?? 20;
       switch (mode) {
-        case "report": {
-          if (!entity || correct === void 0) {
+        case "session": {
+          const sid = session_id ?? getSessionId2();
+          if (!sid) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ error: "entity and correct are required for report mode" }) }]
+              content: [{ type: "text", text: JSON.stringify({ error: "No session ID available" }) }]
             };
           }
-          recordFeedback(stateDb2, entity, context || "", note_path || "", correct);
-          const suppressionUpdated = updateSuppressionList(stateDb2) > 0;
-          result = {
-            mode: "report",
-            reported: {
-              entity,
-              correct,
-              suppression_updated: suppressionUpdated
-            },
-            total_suppressed: getSuppressedCount(stateDb2)
+          const sessions = getSessionHistory(stateDb2, sid);
+          const recent = getRecentInvocations(stateDb2, limit);
+          const sessionInvocations = recent.filter((r) => r.session_id === sid);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              mode: "session",
+              session_id: sid,
+              summary: sessions[0] ?? null,
+              recent_invocations: sessionInvocations
+            }, null, 2) }]
           };
-          break;
         }
-        case "list": {
-          const entries = getFeedback(stateDb2, entity, limit ?? 20);
-          result = {
-            mode: "list",
-            entries,
-            total_feedback: entries.length
+        case "sessions": {
+          const sessions = getSessionHistory(stateDb2);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              mode: "sessions",
+              sessions: sessions.slice(0, limit)
+            }, null, 2) }]
           };
-          break;
         }
-        case "stats": {
-          const stats = getEntityStats(stateDb2);
-          result = {
-            mode: "stats",
-            stats,
-            total_feedback: stats.reduce((sum, s) => sum + s.total, 0),
-            total_suppressed: getSuppressedCount(stateDb2)
+        case "note_access": {
+          const notes = getNoteAccessFrequency(stateDb2, daysBack);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              mode: "note_access",
+              days_back: daysBack,
+              notes: notes.slice(0, limit)
+            }, null, 2) }]
+          };
+        }
+        case "tool_usage": {
+          const tools = getToolUsageSummary(stateDb2, daysBack);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              mode: "tool_usage",
+              days_back: daysBack,
+              tools: tools.slice(0, limit)
+            }, null, 2) }]
           };
-          break;
         }
       }
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      };
     }
   );
 }
 
-// src/tools/read/metrics.ts
-import { z as z21 } from "zod";
+// src/tools/read/similarity.ts
+import { z as z23 } from "zod";
 
-// src/core/shared/metrics.ts
-var ALL_METRICS = [
-  "note_count",
-  "link_count",
-  "orphan_count",
-  "tag_count",
-  "entity_count",
-  "avg_links_per_note",
-  "link_density",
-  "connected_ratio",
-  "wikilink_accuracy",
-  "wikilink_feedback_volume",
-  "wikilink_suppressed_count"
-];
-function computeMetrics(index, stateDb2) {
-  const noteCount = index.notes.size;
-  let linkCount = 0;
-  for (const note of index.notes.values()) {
-    linkCount += note.outlinks.length;
-  }
-  const connectedNotes = /* @__PURE__ */ new Set();
-  for (const [notePath, note] of index.notes) {
-    if (note.outlinks.length > 0) {
-      connectedNotes.add(notePath);
-    }
-  }
-  for (const [target, backlinks] of index.backlinks) {
-    for (const bl of backlinks) {
-      connectedNotes.add(bl.source);
-    }
-    for (const note of index.notes.values()) {
-      const normalizedTitle = note.title.toLowerCase();
-      if (normalizedTitle === target.toLowerCase() || note.path.toLowerCase() === target.toLowerCase()) {
-        connectedNotes.add(note.path);
-      }
-    }
-  }
-  let orphanCount = 0;
-  for (const [notePath, note] of index.notes) {
-    if (!connectedNotes.has(notePath)) {
-      orphanCount++;
-    }
+// src/core/read/similarity.ts
+import * as fs27 from "fs";
+import * as path26 from "path";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "be",
+  "to",
+  "of",
+  "and",
+  "a",
+  "in",
+  "that",
+  "have",
+  "i",
+  "it",
+  "for",
+  "not",
+  "on",
+  "with",
+  "he",
+  "as",
+  "you",
+  "do",
+  "at",
+  "this",
+  "but",
+  "his",
+  "by",
+  "from",
+  "they",
+  "we",
+  "say",
+  "her",
+  "she",
+  "or",
+  "an",
+  "will",
+  "my",
+  "one",
+  "all",
+  "would",
+  "there",
+  "their",
+  "what",
+  "so",
+  "up",
+  "out",
+  "if",
+  "about",
+  "who",
+  "get",
+  "which",
+  "go",
+  "me",
+  "when",
+  "make",
+  "can",
+  "like",
+  "time",
+  "no",
+  "just",
+  "him",
+  "know",
+  "take",
+  "people",
+  "into",
+  "year",
+  "your",
+  "good",
+  "some",
+  "could",
+  "them",
+  "see",
+  "other",
+  "than",
+  "then",
+  "now",
+  "look",
+  "only",
+  "come",
+  "its",
+  "over",
+  "think",
+  "also",
+  "back",
+  "after",
+  "use",
+  "two",
+  "how",
+  "our",
+  "work",
+  "first",
+  "well",
+  "way",
+  "even",
+  "new",
+  "want",
+  "because",
+  "any",
+  "these",
+  "give",
+  "day",
+  "most",
+  "us",
+  "is",
+  "was",
+  "are",
+  "been",
+  "has",
+  "had",
+  "did",
+  "being",
+  "were",
+  "does",
+  "done",
+  "may",
+  "should",
+  "each",
+  "much",
+  "need",
+  "very",
+  "still",
+  "between",
+  "own"
+]);
+function extractKeyTerms(content, maxTerms = 15) {
+  const bodyMatch = content.match(/^---[\s\S]*?---\n([\s\S]*)$/);
+  const body = bodyMatch ? bodyMatch[1] : content;
+  const cleaned = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/\[\[([^\]|]+)(\|[^\]]+)?\]\]/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/https?:\/\/\S+/g, "").replace(/[#*_~>|=-]+/g, " ").replace(/\d+/g, " ");
+  const words = cleaned.toLowerCase().split(/\W+/).filter((w) => w.length > 2);
+  const freq = /* @__PURE__ */ new Map();
+  for (const w of words) {
+    if (STOP_WORDS.has(w)) continue;
+    freq.set(w, (freq.get(w) || 0) + 1);
+  }
+  return Array.from(freq.entries()).sort((a, b) => b[1] - a[1]).slice(0, maxTerms).map(([word]) => word);
+}
+function findSimilarNotes(db3, vaultPath2, index, sourcePath, options = {}) {
+  const limit = options.limit ?? 10;
+  const absPath = path26.join(vaultPath2, sourcePath);
+  let content;
+  try {
+    content = fs27.readFileSync(absPath, "utf-8");
+  } catch {
+    return [];
   }
-  const tagCount = index.tags.size;
-  const entityCount = index.entities.size;
-  const avgLinksPerNote = noteCount > 0 ? linkCount / noteCount : 0;
-  const possibleLinks = noteCount * (noteCount - 1);
-  const linkDensity = possibleLinks > 0 ? linkCount / possibleLinks : 0;
-  const connectedRatio = noteCount > 0 ? connectedNotes.size / noteCount : 0;
-  let wikilinkAccuracy = 0;
-  let wikilinkFeedbackVolume = 0;
-  let wikilinkSuppressedCount = 0;
-  if (stateDb2) {
-    const entityStatsList = getEntityStats(stateDb2);
-    wikilinkFeedbackVolume = entityStatsList.reduce((sum, s) => sum + s.total, 0);
-    if (wikilinkFeedbackVolume > 0) {
-      const totalCorrect = entityStatsList.reduce((sum, s) => sum + s.correct, 0);
-      wikilinkAccuracy = Math.round(totalCorrect / wikilinkFeedbackVolume * 1e3) / 1e3;
+  const terms = extractKeyTerms(content);
+  if (terms.length === 0) return [];
+  const query = terms.join(" OR ");
+  try {
+    const results = db3.prepare(`
+      SELECT
+        path,
+        title,
+        bm25(notes_fts) as score,
+        snippet(notes_fts, 2, '[', ']', '...', 15) as snippet
+      FROM notes_fts
+      WHERE notes_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `).all(query, limit + 20);
+    let filtered = results.filter((r) => r.path !== sourcePath);
+    if (options.excludeLinked) {
+      const note = index.notes.get(sourcePath);
+      if (note) {
+        const linkedPaths = /* @__PURE__ */ new Set();
+        for (const link of note.outlinks) {
+          const resolved = index.entities.get(link.target.toLowerCase());
+          if (resolved) linkedPaths.add(resolved);
+        }
+        const normalizedTitle = note.title.toLowerCase();
+        const backlinks = index.backlinks.get(normalizedTitle) || [];
+        for (const bl of backlinks) {
+          linkedPaths.add(bl.source);
+        }
+        filtered = filtered.filter((r) => !linkedPaths.has(r.path));
+      }
     }
-    wikilinkSuppressedCount = getSuppressedCount(stateDb2);
+    return filtered.slice(0, limit).map((r) => ({
+      path: r.path,
+      title: r.title,
+      score: Math.round(Math.abs(r.score) * 1e3) / 1e3,
+      snippet: r.snippet
+    }));
+  } catch {
+    return [];
   }
-  return {
-    note_count: noteCount,
-    link_count: linkCount,
-    orphan_count: orphanCount,
-    tag_count: tagCount,
-    entity_count: entityCount,
-    avg_links_per_note: Math.round(avgLinksPerNote * 100) / 100,
-    link_density: Math.round(linkDensity * 1e4) / 1e4,
-    connected_ratio: Math.round(connectedRatio * 1e3) / 1e3,
-    wikilink_accuracy: wikilinkAccuracy,
-    wikilink_feedback_volume: wikilinkFeedbackVolume,
-    wikilink_suppressed_count: wikilinkSuppressedCount
-  };
-}
-function recordMetrics(stateDb2, metrics) {
-  const timestamp = Date.now();
-  const insert = stateDb2.db.prepare(
-    "INSERT INTO vault_metrics (timestamp, metric, value) VALUES (?, ?, ?)"
-  );
-  const transaction = stateDb2.db.transaction(() => {
-    for (const [metric, value] of Object.entries(metrics)) {
-      insert.run(timestamp, metric, value);
-    }
-  });
-  transaction();
 }
-function getMetricHistory(stateDb2, metric, daysBack = 30) {
-  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
-  let rows;
-  if (metric) {
-    rows = stateDb2.db.prepare(
-      "SELECT timestamp, metric, value FROM vault_metrics WHERE metric = ? AND timestamp >= ? ORDER BY timestamp"
-    ).all(metric, cutoff);
-  } else {
-    rows = stateDb2.db.prepare(
-      "SELECT timestamp, metric, value FROM vault_metrics WHERE timestamp >= ? ORDER BY timestamp"
-    ).all(cutoff);
-  }
-  return rows.map((r) => ({
-    metric: r.metric,
-    value: r.value,
-    timestamp: r.timestamp
+function getLinkedPaths(index, sourcePath) {
+  const linkedPaths = /* @__PURE__ */ new Set();
+  const note = index.notes.get(sourcePath);
+  if (!note) return linkedPaths;
+  for (const link of note.outlinks) {
+    const resolved = index.entities.get(link.target.toLowerCase());
+    if (resolved) linkedPaths.add(resolved);
+  }
+  const normalizedTitle = note.title.toLowerCase();
+  const backlinks = index.backlinks.get(normalizedTitle) || [];
+  for (const bl of backlinks) {
+    linkedPaths.add(bl.source);
+  }
+  return linkedPaths;
+}
+async function findSemanticSimilarNotes(vaultPath2, index, sourcePath, options = {}) {
+  const limit = options.limit ?? 10;
+  if (!hasEmbeddingsIndex()) {
+    await buildEmbeddingsIndex(vaultPath2);
+  }
+  const excludePaths = options.excludeLinked ? getLinkedPaths(index, sourcePath) : void 0;
+  const results = await findSemanticallySimilar(sourcePath, limit, excludePaths);
+  return results.map((r) => ({
+    path: r.path,
+    title: r.title,
+    score: r.score,
+    snippet: ""
+    // Semantic results don't have snippets
   }));
 }
-function computeTrends(stateDb2, currentMetrics, daysBack = 30) {
-  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
-  const rows = stateDb2.db.prepare(`
-    SELECT metric, value FROM vault_metrics
-    WHERE timestamp >= ? AND timestamp <= ?
-    GROUP BY metric
-    HAVING timestamp = MIN(timestamp)
-  `).all(cutoff, cutoff + 24 * 60 * 60 * 1e3);
-  const previousValues = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    previousValues.set(row.metric, row.value);
-  }
-  if (previousValues.size === 0) {
-    const fallbackRows = stateDb2.db.prepare(`
-      SELECT metric, MIN(value) as value FROM vault_metrics
-      WHERE timestamp >= ?
-      GROUP BY metric
-      HAVING timestamp = MIN(timestamp)
-    `).all(cutoff);
-    for (const row of fallbackRows) {
-      previousValues.set(row.metric, row.value);
-    }
-  }
-  const trends = [];
-  for (const metricName of ALL_METRICS) {
-    const current = currentMetrics[metricName] ?? 0;
-    const previous = previousValues.get(metricName) ?? current;
-    const delta = current - previous;
-    const deltaPct = previous !== 0 ? Math.round(delta / previous * 1e4) / 100 : delta !== 0 ? 100 : 0;
-    let direction = "stable";
-    if (delta > 0) direction = "up";
-    if (delta < 0) direction = "down";
-    trends.push({
-      metric: metricName,
-      current,
-      previous,
-      delta,
-      delta_percent: deltaPct,
-      direction
+async function findHybridSimilarNotes(db3, vaultPath2, index, sourcePath, options = {}) {
+  const limit = options.limit ?? 10;
+  const bm25Results = findSimilarNotes(db3, vaultPath2, index, sourcePath, {
+    limit: limit * 2,
+    excludeLinked: options.excludeLinked
+  });
+  let semanticResults;
+  try {
+    semanticResults = await findSemanticSimilarNotes(vaultPath2, index, sourcePath, {
+      limit: limit * 2,
+      excludeLinked: options.excludeLinked
     });
+  } catch {
+    return bm25Results.slice(0, limit);
   }
-  return trends;
-}
-function purgeOldMetrics(stateDb2, retentionDays = 90) {
-  const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1e3;
-  const result = stateDb2.db.prepare(
-    "DELETE FROM vault_metrics WHERE timestamp < ?"
-  ).run(cutoff);
-  return result.changes;
+  const rrfScores = reciprocalRankFusion(
+    bm25Results.map((r) => ({ path: r.path })),
+    semanticResults.map((r) => ({ path: r.path }))
+  );
+  const bm25Map = new Map(bm25Results.map((r) => [r.path, r]));
+  const semanticMap = new Map(semanticResults.map((r) => [r.path, r]));
+  const allPaths = /* @__PURE__ */ new Set([...bm25Results.map((r) => r.path), ...semanticResults.map((r) => r.path)]);
+  const merged = Array.from(allPaths).map((p) => {
+    const bm25 = bm25Map.get(p);
+    const semantic = semanticMap.get(p);
+    return {
+      path: p,
+      title: bm25?.title || semantic?.title || p.replace(/\.md$/, "").split("/").pop() || p,
+      score: Math.round((rrfScores.get(p) || 0) * 1e4) / 1e4,
+      snippet: bm25?.snippet || ""
+    };
+  });
+  merged.sort((a, b) => b.score - a.score);
+  return merged.slice(0, limit);
 }
 
-// src/tools/read/metrics.ts
-function registerMetricsTools(server2, getIndex, getStateDb) {
+// src/tools/read/similarity.ts
+function registerSimilarityTools(server2, getIndex, getVaultPath, getStateDb) {
   server2.registerTool(
-    "vault_growth",
+    "find_similar",
     {
-      title: "Vault Growth",
-      description: 'Track vault growth over time. Modes: "current" (live snapshot), "history" (time series), "trends" (deltas vs N days ago), "index_activity" (rebuild history). Tracks 11 metrics: note_count, link_count, orphan_count, tag_count, entity_count, avg_links_per_note, link_density, connected_ratio, wikilink_accuracy, wikilink_feedback_volume, wikilink_suppressed_count.',
+      title: "Find Similar Notes",
+      description: "Find notes similar to a given note using FTS5 keyword matching. When embeddings have been built (via init_semantic), automatically uses hybrid ranking (BM25 + embedding similarity via Reciprocal Rank Fusion). Use exclude_linked to filter out notes already connected via wikilinks.",
       inputSchema: {
-        mode: z21.enum(["current", "history", "trends", "index_activity"]).describe("Query mode: current snapshot, historical time series, trend analysis, or index rebuild activity"),
-        metric: z21.string().optional().describe('Filter to specific metric (e.g., "note_count"). Omit for all metrics.'),
-        days_back: z21.number().optional().describe("Number of days to look back for history/trends (default: 30)"),
-        limit: z21.number().optional().describe("Number of recent events to return for index_activity mode (default: 20)")
+        path: z23.string().describe('Path to the source note (relative to vault root, e.g. "projects/alpha.md")'),
+        limit: z23.number().optional().describe("Maximum number of similar notes to return (default: 10)"),
+        exclude_linked: z23.boolean().optional().describe("Exclude notes already linked to/from the source note (default: true)")
       }
     },
-    async ({ mode, metric, days_back, limit: eventLimit }) => {
+    async ({ path: path28, limit, exclude_linked }) => {
       const index = getIndex();
+      const vaultPath2 = getVaultPath();
       const stateDb2 = getStateDb();
-      const daysBack = days_back ?? 30;
-      let result;
-      switch (mode) {
-        case "current": {
-          const metrics = computeMetrics(index, stateDb2 ?? void 0);
-          result = {
-            mode: "current",
-            metrics,
-            recorded_at: Date.now()
-          };
-          break;
-        }
-        case "history": {
-          if (!stateDb2) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available for historical queries" }) }]
-            };
-          }
-          const history = getMetricHistory(stateDb2, metric, daysBack);
-          result = {
-            mode: "history",
-            history
-          };
-          break;
-        }
-        case "trends": {
-          if (!stateDb2) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available for trend analysis" }) }]
-            };
-          }
-          const currentMetrics = computeMetrics(index, stateDb2);
-          const trends = computeTrends(stateDb2, currentMetrics, daysBack);
-          result = {
-            mode: "trends",
-            trends
-          };
-          break;
-        }
-        case "index_activity": {
-          if (!stateDb2) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available for index activity queries" }) }]
-            };
-          }
-          const summary = getIndexActivitySummary(stateDb2);
-          const recentEvents = getRecentIndexEvents(stateDb2, eventLimit ?? 20);
-          result = {
-            mode: "index_activity",
-            index_activity: { summary, recent_events: recentEvents }
-          };
-          break;
-        }
+      if (!stateDb2) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available" }) }]
+        };
       }
+      if (!index.notes.has(path28)) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({
+            error: `Note not found: ${path28}`,
+            hint: "Use the full relative path including .md extension"
+          }, null, 2) }]
+        };
+      }
+      const opts = {
+        limit: limit ?? 10,
+        excludeLinked: exclude_linked ?? true
+      };
+      const useHybrid = hasEmbeddingsIndex();
+      const method = useHybrid ? "hybrid" : "bm25";
+      const results = useHybrid ? await findHybridSimilarNotes(stateDb2.db, vaultPath2, index, path28, opts) : findSimilarNotes(stateDb2.db, vaultPath2, index, path28, opts);
       return {
-        content: [
-          {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            source: path28,
+            method,
+            exclude_linked: exclude_linked ?? true,
+            count: results.length,
+            similar: results
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
+// src/tools/read/semantic.ts
+import { z as z24 } from "zod";
+function registerSemanticTools(server2, getVaultPath, getStateDb) {
+  server2.registerTool(
+    "init_semantic",
+    {
+      title: "Initialize Semantic Search",
+      description: "Download the embedding model and build semantic search index for this vault. After running, search and find_similar automatically use hybrid ranking (BM25 + semantic). Run once per vault \u2014 subsequent calls skip already-embedded notes unless force=true.",
+      inputSchema: {
+        force: z24.boolean().optional().describe(
+          "Rebuild all embeddings even if they already exist (default: false)"
+        )
+      }
+    },
+    async ({ force }) => {
+      const stateDb2 = getStateDb();
+      if (!stateDb2) {
+        return {
+          content: [{
             type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
+            text: JSON.stringify({ error: "StateDb not available \u2014 vault may not be initialized yet" })
+          }]
+        };
+      }
+      setEmbeddingsDatabase(stateDb2.db);
+      if (hasEmbeddingsIndex() && !force) {
+        const count = getEmbeddingsCount();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              already_built: true,
+              embedded: count,
+              hint: "Embeddings already built. All searches automatically use hybrid ranking."
+            }, null, 2)
+          }]
+        };
+      }
+      const vaultPath2 = getVaultPath();
+      const progress = await buildEmbeddingsIndex(vaultPath2, (p) => {
+        if (p.current % 50 === 0 || p.current === p.total) {
+          console.error(`[Semantic] Embedding ${p.current}/${p.total} notes (${p.skipped} skipped)...`);
+        }
+      });
+      const embedded = progress.total - progress.skipped;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            embedded,
+            skipped: progress.skipped,
+            total: progress.total,
+            hint: "Embeddings built. All searches now automatically use hybrid ranking."
+          }, null, 2)
+        }]
       };
     }
   );
@@ -12763,6 +14001,7 @@ var TOOL_CATEGORY = {
   get_unlinked_mentions: "health",
   // search (unified: metadata + content + entities)
   search: "search",
+  init_semantic: "search",
   // backlinks
   get_backlinks: "backlinks",
   get_forward_links: "backlinks",
@@ -12809,7 +14048,11 @@ var TOOL_CATEGORY = {
   // health (growth metrics)
   vault_growth: "health",
   // wikilinks (feedback)
-  wikilink_feedback: "wikilinks"
+  wikilink_feedback: "wikilinks",
+  // health (activity tracking)
+  vault_activity: "health",
+  // schema (content similarity)
+  find_similar: "schema"
 };
 var server = new McpServer({
   name: "flywheel-memory",
@@ -12826,15 +14069,62 @@ function gateByCategory(name) {
   _registeredCount++;
   return true;
 }
+function wrapHandlerWithTracking(toolName, handler) {
+  return async (...args) => {
+    const start = Date.now();
+    let success = true;
+    let notePaths;
+    const params = args[0];
+    if (params && typeof params === "object") {
+      const paths = [];
+      if (typeof params.path === "string") paths.push(params.path);
+      if (Array.isArray(params.paths)) paths.push(...params.paths.filter((p) => typeof p === "string"));
+      if (typeof params.note_path === "string") paths.push(params.note_path);
+      if (typeof params.source === "string") paths.push(params.source);
+      if (typeof params.target === "string") paths.push(params.target);
+      if (paths.length > 0) notePaths = paths;
+    }
+    try {
+      return await handler(...args);
+    } catch (err) {
+      success = false;
+      throw err;
+    } finally {
+      if (stateDb) {
+        try {
+          let sessionId;
+          try {
+            sessionId = getSessionId();
+          } catch {
+          }
+          recordToolInvocation(stateDb, {
+            tool_name: toolName,
+            session_id: sessionId,
+            note_paths: notePaths,
+            duration_ms: Date.now() - start,
+            success
+          });
+        } catch {
+        }
+      }
+    }
+  };
+}
 var _originalTool = server.tool.bind(server);
 server.tool = (name, ...args) => {
   if (!gateByCategory(name)) return;
+  if (args.length > 0 && typeof args[args.length - 1] === "function") {
+    args[args.length - 1] = wrapHandlerWithTracking(name, args[args.length - 1]);
+  }
   return _originalTool(name, ...args);
 };
 var _originalRegisterTool = server.registerTool?.bind(server);
 if (_originalRegisterTool) {
   server.registerTool = (name, ...args) => {
     if (!gateByCategory(name)) return;
+    if (args.length > 0 && typeof args[args.length - 1] === "function") {
+      args[args.length - 1] = wrapHandlerWithTracking(name, args[args.length - 1]);
+    }
     return _originalRegisterTool(name, ...args);
   };
 }
@@ -12857,7 +14147,7 @@ registerGraphTools(server, () => vaultIndex, () => vaultPath);
 registerWikilinkTools(server, () => vaultIndex, () => vaultPath);
 registerQueryTools(server, () => vaultIndex, () => vaultPath, () => stateDb);
 registerPrimitiveTools(server, () => vaultIndex, () => vaultPath, () => flywheelConfig);
-registerGraphAnalysisTools(server, () => vaultIndex, () => vaultPath);
+registerGraphAnalysisTools(server, () => vaultIndex, () => vaultPath, () => stateDb);
 registerVaultSchemaTools(server, () => vaultIndex, () => vaultPath);
 registerNoteIntelligenceTools(server, () => vaultIndex, () => vaultPath);
 registerMigrationTools(server, () => vaultIndex, () => vaultPath);
@@ -12871,6 +14161,15 @@ registerPolicyTools(server, vaultPath);
 registerTagTools(server, () => vaultIndex, () => vaultPath);
 registerWikilinkFeedbackTools(server, () => stateDb);
 registerMetricsTools(server, () => vaultIndex, () => stateDb);
+registerActivityTools(server, () => stateDb, () => {
+  try {
+    return getSessionId();
+  } catch {
+    return null;
+  }
+});
+registerSimilarityTools(server, () => vaultIndex, () => vaultPath, () => stateDb);
+registerSemanticTools(server, () => vaultPath, () => stateDb);
 registerVaultResources(server, () => vaultIndex ?? null);
 console.error(`[Memory] Registered ${_registeredCount} tools, skipped ${_skippedCount}`);
 async function main() {
@@ -12881,6 +14180,7 @@ async function main() {
     stateDb = openStateDb(vaultPath);
     console.error("[Memory] StateDb initialized");
     setFTS5Database(stateDb.db);
+    setEmbeddingsDatabase(stateDb.db);
     setWriteStateDb(stateDb);
     await initializeEntityIndex(vaultPath);
   } catch (err) {
@@ -13005,11 +14305,21 @@ async function runPostIndexWork(index) {
       recordMetrics(stateDb, metrics);
       purgeOldMetrics(stateDb, 90);
       purgeOldIndexEvents(stateDb, 90);
+      purgeOldInvocations(stateDb, 90);
       console.error("[Memory] Growth metrics recorded");
     } catch (err) {
       console.error("[Memory] Failed to record metrics:", err);
     }
   }
+  if (stateDb) {
+    try {
+      const graphMetrics = computeGraphMetrics(index);
+      recordGraphSnapshot(stateDb, graphMetrics);
+      purgeOldSnapshots(stateDb, 90);
+    } catch (err) {
+      console.error("[Memory] Failed to record graph snapshot:", err);
+    }
+  }
   if (stateDb) {
     try {
       updateSuppressionList(stateDb);
@@ -13052,6 +14362,19 @@ async function runPostIndexWork(index) {
           }
           await updateEntitiesInStateDb();
           await exportHubScores(vaultIndex, stateDb);
+          if (hasEmbeddingsIndex()) {
+            for (const event of batch.events) {
+              try {
+                if (event.type === "delete") {
+                  removeEmbedding(event.path);
+                } else if (event.path.endsWith(".md")) {
+                  const absPath = path27.join(vaultPath, event.path);
+                  await updateEmbedding(event.path, absPath);
+                }
+              } catch {
+              }
+            }
+          }
           if (stateDb) {
             try {
               saveVaultIndexToCache(stateDb, vaultIndex);
@@ -13088,10 +14411,32 @@ async function runPostIndexWork(index) {
     watcher.start();
   }
 }
-main().catch((error) => {
-  console.error("[Memory] Fatal error:", error);
-  process.exit(1);
-});
+if (process.argv.includes("--init-semantic")) {
+  (async () => {
+    console.error("[Semantic] Pre-warming semantic search...");
+    console.error(`[Semantic] Vault: ${vaultPath}`);
+    try {
+      const db3 = openStateDb(vaultPath);
+      setEmbeddingsDatabase(db3.db);
+      const progress = await buildEmbeddingsIndex(vaultPath, (p) => {
+        if (p.current % 50 === 0 || p.current === p.total) {
+          console.error(`[Semantic] Embedding ${p.current}/${p.total} notes (${p.skipped} skipped)...`);
+        }
+      });
+      console.error(`[Semantic] Done. Embedded ${progress.total - progress.skipped} notes, skipped ${progress.skipped}.`);
+      db3.close();
+      process.exit(0);
+    } catch (err) {
+      console.error("[Semantic] Failed:", err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  })();
+} else {
+  main().catch((error) => {
+    console.error("[Memory] Fatal error:", error);
+    process.exit(1);
+  });
+}
 process.on("beforeExit", async () => {
   await flushLogs();
 });