@velvetmonkey/flywheel-memory 2.0.7 → 2.0.9

package/dist/index.js

@@ -567,6 +567,7 @@ function injectMutationMetadata(frontmatter, scoping) {
     if (scoping.session_id) {
       frontmatter._session_id = scoping.session_id;
     }
+    frontmatter._source = "ai";
     if (scoping.agent_id && scoping.session_id) {
       frontmatter._last_modified_by = `${scoping.agent_id}:${scoping.session_id}`;
     } else if (scoping.agent_id) {
@@ -2732,9 +2733,9 @@ import { simpleGit, CheckRepoActions } from "simple-git";
 import path5 from "path";
 import fs5 from "fs/promises";
 import {
-  setCrankState,
-  getCrankState,
-  deleteCrankState
+  setWriteState,
+  getWriteState,
+  deleteWriteState
 } from "@velvetmonkey/vault-core";
 var moduleStateDb = null;
 function setGitStateDb(stateDb2) {
@@ -2747,9 +2748,9 @@ var DEFAULT_RETRY = {
   jitter: true
 };
 var STALE_LOCK_THRESHOLD_MS = 3e4;
-function saveLastCrankCommit(hash, message) {
+function saveLastMutationCommit(hash, message) {
   if (!moduleStateDb) {
-    console.error("[Crank] No StateDb available for saving last commit");
+    console.error("[Flywheel] No StateDb available for saving last commit");
     return;
   }
   const data = {
@@ -2758,27 +2759,27 @@ function saveLastCrankCommit(hash, message) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
-    setCrankState(moduleStateDb, "last_commit", data);
+    setWriteState(moduleStateDb, "last_commit", data);
   } catch (e) {
-    console.error("[Crank] Failed to save last commit to StateDb:", e);
+    console.error("[Flywheel] Failed to save last commit to StateDb:", e);
   }
 }
-function getLastCrankCommit() {
+function getLastMutationCommit() {
   if (!moduleStateDb) {
     return null;
   }
   try {
-    return getCrankState(moduleStateDb, "last_commit");
+    return getWriteState(moduleStateDb, "last_commit");
   } catch {
     return null;
   }
 }
-function clearLastCrankCommit() {
+function clearLastMutationCommit() {
   if (!moduleStateDb) {
     return;
   }
   try {
-    deleteCrankState(moduleStateDb, "last_commit");
+    deleteWriteState(moduleStateDb, "last_commit");
   } catch {
   }
 }
@@ -2860,7 +2861,7 @@ async function commitChange(vaultPath2, filePath, messagePrefix, retryConfig = D
       const commitMessage = `${messagePrefix} Update ${fileName}`;
       const result = await git.commit(commitMessage);
       if (result.commit) {
-        saveLastCrankCommit(result.commit, commitMessage);
+        saveLastMutationCommit(result.commit, commitMessage);
       }
       return {
         success: true,
@@ -2995,7 +2996,7 @@ Files:
 ${files.map((f) => `- ${f}`).join("\n")}`;
       const result = await git.commit(commitMessage);
       if (result.commit) {
-        saveLastCrankCommit(result.commit, commitMessage);
+        saveLastMutationCommit(result.commit, commitMessage);
       }
       return {
         success: true,
@@ -3040,8 +3041,8 @@ ${files.map((f) => `- ${f}`).join("\n")}`;
 
 // src/core/write/hints.ts
 import {
-  setCrankState as setCrankState2,
-  getCrankState as getCrankState2
+  setWriteState as setWriteState2,
+  getWriteState as getWriteState2
 } from "@velvetmonkey/vault-core";
 var moduleStateDb2 = null;
 function setHintsStateDb(stateDb2) {
@@ -3115,7 +3116,7 @@ async function buildRecencyIndex(vaultPath2, entities) {
       }
     }
   } catch (error) {
-    console.error(`[Crank] Error building recency index: ${error}`);
+    console.error(`[Flywheel] Error building recency index: ${error}`);
   }
   return {
     lastMentioned,
@@ -3158,16 +3159,16 @@ function loadRecencyFromStateDb() {
 }
 function saveRecencyToStateDb(index) {
   if (!moduleStateDb3) {
-    console.error("[Crank] No StateDb available for saving recency");
+    console.error("[Flywheel] No StateDb available for saving recency");
     return;
   }
   try {
     for (const [entityNameLower, timestamp] of index.lastMentioned) {
       recordEntityMention(moduleStateDb3, entityNameLower, new Date(timestamp));
     }
-    console.error(`[Crank] Saved ${index.lastMentioned.size} recency entries to StateDb`);
+    console.error(`[Flywheel] Saved ${index.lastMentioned.size} recency entries to StateDb`);
   } catch (e) {
-    console.error("[Crank] Failed to save recency to StateDb:", e);
+    console.error("[Flywheel] Failed to save recency to StateDb:", e);
   }
 }
 
@@ -4068,7 +4069,7 @@ function getCooccurrenceBoost(entityName, matchedEntities, cooccurrenceIndex2, r
 
 // src/core/write/wikilinks.ts
 var moduleStateDb4 = null;
-function setCrankStateDb(stateDb2) {
+function setWriteStateDb(stateDb2) {
   moduleStateDb4 = stateDb2;
   setGitStateDb(stateDb2);
   setHintsStateDb(stateDb2);
@@ -4113,21 +4114,21 @@ async function initializeEntityIndex(vaultPath2) {
           entityIndex = dbIndex;
           indexReady = true;
           lastLoadedAt = Date.now();
-          console.error(`[Crank] Loaded ${dbIndex._metadata.total_entities} entities from StateDb`);
+          console.error(`[Flywheel] Loaded ${dbIndex._metadata.total_entities} entities from StateDb`);
           return;
         }
       } catch (e) {
-        console.error("[Crank] Failed to load from StateDb:", e);
+        console.error("[Flywheel] Failed to load from StateDb:", e);
       }
     }
     await rebuildIndex(vaultPath2);
   } catch (error) {
     indexError2 = error instanceof Error ? error : new Error(String(error));
-    console.error(`[Crank] Failed to initialize entity index: ${indexError2.message}`);
+    console.error(`[Flywheel] Failed to initialize entity index: ${indexError2.message}`);
   }
 }
 async function rebuildIndex(vaultPath2) {
-  console.error(`[Crank] Scanning vault for entities...`);
+  console.error(`[Flywheel] Scanning vault for entities...`);
   const startTime = Date.now();
   entityIndex = await scanVaultEntities(vaultPath2, {
     excludeFolders: DEFAULT_EXCLUDE_FOLDERS
@@ -4135,13 +4136,13 @@ async function rebuildIndex(vaultPath2) {
   indexReady = true;
   lastLoadedAt = Date.now();
   const entityDuration = Date.now() - startTime;
-  console.error(`[Crank] Entity index built: ${entityIndex._metadata.total_entities} entities in ${entityDuration}ms`);
+  console.error(`[Flywheel] Entity index built: ${entityIndex._metadata.total_entities} entities in ${entityDuration}ms`);
   if (moduleStateDb4) {
     try {
       moduleStateDb4.replaceAllEntities(entityIndex);
-      console.error(`[Crank] Saved entities to StateDb`);
+      console.error(`[Flywheel] Saved entities to StateDb`);
     } catch (e) {
-      console.error(`[Crank] Failed to save entities to StateDb: ${e}`);
+      console.error(`[Flywheel] Failed to save entities to StateDb: ${e}`);
     }
   }
   const entities = getAllEntities(entityIndex);
@@ -4150,25 +4151,25 @@ async function rebuildIndex(vaultPath2) {
     const cooccurrenceStart = Date.now();
     cooccurrenceIndex = await mineCooccurrences(vaultPath2, entityNames);
     const cooccurrenceDuration = Date.now() - cooccurrenceStart;
-    console.error(`[Crank] Co-occurrence index built: ${cooccurrenceIndex._metadata.total_associations} associations in ${cooccurrenceDuration}ms`);
+    console.error(`[Flywheel] Co-occurrence index built: ${cooccurrenceIndex._metadata.total_associations} associations in ${cooccurrenceDuration}ms`);
   } catch (e) {
-    console.error(`[Crank] Failed to build co-occurrence index: ${e}`);
+    console.error(`[Flywheel] Failed to build co-occurrence index: ${e}`);
   }
   try {
     const cachedRecency = loadRecencyFromStateDb();
     const cacheAgeMs = cachedRecency ? Date.now() - cachedRecency.lastUpdated : Infinity;
     if (cachedRecency && cacheAgeMs < 60 * 60 * 1e3) {
       recencyIndex = cachedRecency;
-      console.error(`[Crank] Recency index loaded from StateDb (${recencyIndex.lastMentioned.size} entities)`);
+      console.error(`[Flywheel] Recency index loaded from StateDb (${recencyIndex.lastMentioned.size} entities)`);
     } else {
       const recencyStart = Date.now();
       recencyIndex = await buildRecencyIndex(vaultPath2, entities);
       const recencyDuration = Date.now() - recencyStart;
-      console.error(`[Crank] Recency index built: ${recencyIndex.lastMentioned.size} entities in ${recencyDuration}ms`);
+      console.error(`[Flywheel] Recency index built: ${recencyIndex.lastMentioned.size} entities in ${recencyDuration}ms`);
       saveRecencyToStateDb(recencyIndex);
     }
   } catch (e) {
-    console.error(`[Crank] Failed to build recency index: ${e}`);
+    console.error(`[Flywheel] Failed to build recency index: ${e}`);
   }
 }
 function isEntityIndexReady() {
@@ -4181,16 +4182,16 @@ function checkAndRefreshIfStale() {
     if (!metadata.entitiesBuiltAt) return;
     const dbBuiltAt = new Date(metadata.entitiesBuiltAt).getTime();
     if (dbBuiltAt > lastLoadedAt) {
-      console.error("[Crank] Entity index stale, reloading from StateDb...");
+      console.error("[Flywheel] Entity index stale, reloading from StateDb...");
       const dbIndex = getEntityIndexFromDb(moduleStateDb4);
       if (dbIndex._metadata.total_entities > 0) {
         entityIndex = dbIndex;
         lastLoadedAt = Date.now();
-        console.error(`[Crank] Reloaded ${dbIndex._metadata.total_entities} entities`);
+        console.error(`[Flywheel] Reloaded ${dbIndex._metadata.total_entities} entities`);
       }
     }
   } catch (e) {
-    console.error("[Crank] Failed to check for stale entities:", e);
+    console.error("[Flywheel] Failed to check for stale entities:", e);
   }
 }
 function sortEntitiesByPriority(entities, notePath) {
@@ -4210,7 +4211,7 @@ function sortEntitiesByPriority(entities, notePath) {
 }
 function processWikilinks(content, notePath) {
   if (!isEntityIndexReady() || !entityIndex) {
-    console.error("[Crank:DEBUG] Entity index not ready, entities:", entityIndex?._metadata?.total_entities ?? 0);
+    console.error("[Flywheel:DEBUG] Entity index not ready, entities:", entityIndex?._metadata?.total_entities ?? 0);
     return {
       content,
       linksAdded: 0,
@@ -4218,7 +4219,7 @@ function processWikilinks(content, notePath) {
     };
   }
   const entities = getAllEntities(entityIndex);
-  console.error(`[Crank:DEBUG] Processing wikilinks with ${entities.length} entities`);
+  console.error(`[Flywheel:DEBUG] Processing wikilinks with ${entities.length} entities`);
   const sortedEntities = sortEntitiesByPriority(entities, notePath);
   const resolved = resolveAliasWikilinks(content, sortedEntities, {
     caseInsensitive: true
@@ -4818,9 +4819,9 @@ async function initializeLogger2(vaultPath2) {
   try {
     const sessionId = generateSessionId2();
     setSessionId2(sessionId);
-    logger2 = await createLoggerFromConfig2(vaultPath2, "crank");
+    logger2 = await createLoggerFromConfig2(vaultPath2, "write");
   } catch (error) {
-    console.error(`[Crank] Failed to initialize logger: ${error}`);
+    console.error(`[Flywheel] Failed to initialize logger: ${error}`);
     logger2 = null;
   }
 }
@@ -6140,7 +6141,7 @@ 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.',
+    '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" })',
     {
       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)"),
@@ -7411,7 +7412,7 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath) {
     "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',
+      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)"),
@@ -7984,7 +7985,7 @@ function registerVaultSchemaTools(server2, getIndex, getVaultPath) {
     "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',
+      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",
@@ -8554,7 +8555,7 @@ function registerNoteIntelligenceTools(server2, getIndex, getVaultPath) {
     "note_intelligence",
     {
       title: "Note Intelligence",
-      description: 'Analyze a note for patterns, suggestions, and consistency. Use analysis to pick the mode:\n- "prose_patterns": Find "Key: Value" or "Key: [[wikilink]]" patterns in prose\n- "suggest_frontmatter": Suggest YAML frontmatter from detected prose patterns\n- "suggest_wikilinks": Find frontmatter values that could be wikilinks\n- "cross_layer": Check consistency between frontmatter and prose references\n- "compute": Auto-compute derived fields (word_count, link_count, etc.)\n- "all": Run all analyses and return combined result',
+      description: 'Analyze a note for patterns, suggestions, and consistency. Use analysis to pick the mode:\n- "prose_patterns": Find "Key: Value" or "Key: [[wikilink]]" patterns in prose\n- "suggest_frontmatter": Suggest YAML frontmatter from detected prose patterns\n- "suggest_wikilinks": Find frontmatter values that could be wikilinks\n- "cross_layer": Check consistency between frontmatter and prose references\n- "compute": Auto-compute derived fields (word_count, link_count, etc.)\n- "all": Run all analyses and return combined result\n\nExample: note_intelligence({ path: "projects/alpha.md", analysis: "wikilinks" })\nExample: note_intelligence({ path: "projects/alpha.md", analysis: "compute", fields: ["word_count", "link_count"] })',
       inputSchema: {
         analysis: z10.enum([
           "prose_patterns",
@@ -9031,7 +9032,9 @@ async function createNoteFromTemplate(vaultPath2, notePath, config) {
 function registerMutationTools(server2, vaultPath2, getConfig = () => ({})) {
   server2.tool(
     "vault_add_to_section",
-    "Add content to a specific section in a markdown note. Set create_if_missing=true to auto-create the note from template if it doesn't exist (enables 1-call daily capture).",
+    `Add content to a specific section in a markdown note. Set create_if_missing=true to auto-create the note from template if it doesn't exist (enables 1-call daily capture).
+
+Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", content: "Met with team about Q1", format: "timestamp-bullet", create_if_missing: true })`,
     {
       path: z11.string().describe('Vault-relative path to the note (e.g., "daily-notes/2026-01-28.md")'),
       section: z11.string().describe('Heading text to add to (e.g., "Log" or "## Log")'),
@@ -9069,7 +9072,7 @@ function registerMutationTools(server2, vaultPath2, getConfig = () => ({})) {
           vaultPath: vaultPath2,
           notePath,
           commit,
-          commitPrefix: "[Crank:Add]",
+          commitPrefix: "[Flywheel:Add]",
           section,
           actionDescription: "add content",
           scoping: agent_id || session_id ? { agent_id, session_id } : void 0
@@ -9144,7 +9147,7 @@ function registerMutationTools(server2, vaultPath2, getConfig = () => ({})) {
           vaultPath: vaultPath2,
           notePath,
           commit,
-          commitPrefix: "[Crank:Remove]",
+          commitPrefix: "[Flywheel:Remove]",
           section,
           actionDescription: "remove content",
           scoping: agent_id || session_id ? { agent_id, session_id } : void 0
@@ -9195,7 +9198,7 @@ function registerMutationTools(server2, vaultPath2, getConfig = () => ({})) {
           vaultPath: vaultPath2,
           notePath,
           commit,
-          commitPrefix: "[Crank:Replace]",
+          commitPrefix: "[Flywheel:Replace]",
           section,
           actionDescription: "replace content",
           scoping: agent_id || session_id ? { agent_id, session_id } : void 0
@@ -9295,7 +9298,7 @@ function toggleTask(content, lineNumber) {
 function registerTaskTools(server2, vaultPath2) {
   server2.tool(
     "vault_toggle_task",
-    "Toggle a task checkbox between checked and unchecked",
+    'Toggle a task checkbox between checked and unchecked.\n\nExample: vault_toggle_task({ path: "daily/2026-02-15.md", task: "review PR", section: "Tasks" })',
     {
       path: z12.string().describe("Vault-relative path to the note"),
       task: z12.string().describe("Task text to find (partial match supported)"),
@@ -9338,7 +9341,7 @@ function registerTaskTools(server2, vaultPath2) {
           finalFrontmatter = injectMutationMetadata(frontmatter, { agent_id, session_id });
         }
         await writeVaultFile(vaultPath2, notePath, toggleResult.content, finalFrontmatter);
-        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Crank:Task]");
+        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Task]");
         const newStatus = toggleResult.newState ? "completed" : "incomplete";
         const checkbox = toggleResult.newState ? "[x]" : "[ ]";
         return formatMcpResult(
@@ -9355,7 +9358,7 @@ function registerTaskTools(server2, vaultPath2) {
   );
   server2.tool(
     "vault_add_task",
-    "Add a new task to a section in a markdown note",
+    'Add a new task to a section in a markdown note.\n\nExample: vault_add_task({ path: "daily/2026-02-15.md", section: "Tasks", task: "Write unit tests for auth module" })',
     {
       path: z12.string().describe("Vault-relative path to the note"),
       section: z12.string().describe("Section to add the task to"),
@@ -9379,7 +9382,7 @@ function registerTaskTools(server2, vaultPath2) {
           vaultPath: vaultPath2,
           notePath,
           commit,
-          commitPrefix: "[Crank:Task]",
+          commitPrefix: "[Flywheel:Task]",
           section,
           actionDescription: "add task",
           scoping: agent_id || session_id ? { agent_id, session_id } : void 0
@@ -9433,7 +9436,9 @@ import { z as z13 } from "zod";
 function registerFrontmatterTools(server2, vaultPath2) {
   server2.tool(
     "vault_update_frontmatter",
-    "Update frontmatter fields in a note (merge with existing). Set only_if_missing=true to only add fields that don't already exist (absorbed vault_add_frontmatter_field).",
+    `Update frontmatter fields in a note (merge with existing). Set only_if_missing=true to only add fields that don't already exist (absorbed vault_add_frontmatter_field).
+
+Example: vault_update_frontmatter({ path: "projects/alpha.md", frontmatter: { status: "active", priority: 1 }, only_if_missing: true })`,
     {
       path: z13.string().describe("Vault-relative path to the note"),
       frontmatter: z13.record(z13.any()).describe("Frontmatter fields to update (JSON object)"),
@@ -9446,7 +9451,7 @@ function registerFrontmatterTools(server2, vaultPath2) {
           vaultPath: vaultPath2,
           notePath,
           commit,
-          commitPrefix: "[Crank:FM]",
+          commitPrefix: "[Flywheel:FM]",
           actionDescription: "update frontmatter"
         },
         async (ctx) => {
@@ -9494,7 +9499,7 @@ import path18 from "path";
 function registerNoteTools(server2, vaultPath2, getIndex) {
   server2.tool(
     "vault_create_note",
-    "Create a new note in the vault with optional frontmatter and content",
+    'Create a new note in the vault with optional frontmatter and content.\n\nExample: vault_create_note({ path: "people/Jane Smith.md", content: "# Jane Smith\\n\\nProduct manager at Acme.", frontmatter: { type: "person", company: "Acme" } })',
     {
       path: z14.string().describe('Vault-relative path for the new note (e.g., "daily-notes/2026-01-28.md")'),
       content: z14.string().default("").describe("Initial content for the note"),
@@ -9559,7 +9564,7 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
           finalFrontmatter = injectMutationMetadata(frontmatter, { agent_id, session_id });
         }
         await writeVaultFile(vaultPath2, notePath, processedContent, finalFrontmatter);
-        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Crank:Create]");
+        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Create]");
         const infoLines = [wikilinkInfo, suggestInfo].filter(Boolean);
         const previewLines = [
           `Frontmatter fields: ${Object.keys(frontmatter).join(", ") || "none"}`,
@@ -9639,7 +9644,7 @@ ${sources}`;
         }
         const fullPath = path18.join(vaultPath2, notePath);
         await fs18.unlink(fullPath);
-        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Crank:Delete]");
+        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Delete]");
         const message = backlinkWarning ? `Deleted note: ${notePath}
 
 Warning: ${backlinkWarning}` : `Deleted note: ${notePath}`;
@@ -9843,7 +9848,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
         let lockAgeMs;
         if (commit) {
           const filesToCommit = [newPath, ...backlinkUpdates.map((b) => b.path)];
-          const gitResult = await commitChange(vaultPath2, filesToCommit.join(", "), `[Crank:Move] ${oldPath} \u2192 ${newPath}`);
+          const gitResult = await commitChange(vaultPath2, filesToCommit.join(", "), `[Flywheel:Move] ${oldPath} \u2192 ${newPath}`);
           if (gitResult.success && gitResult.hash) {
             gitCommit = gitResult.hash;
             undoAvailable = gitResult.undoAvailable;
@@ -9854,7 +9859,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
           }
         }
         initializeEntityIndex(vaultPath2).catch((err) => {
-          console.error(`[Crank] Entity cache rebuild failed: ${err}`);
+          console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
         });
         const previewLines = [
           `Moved: ${oldPath} \u2192 ${newPath}`
@@ -9918,7 +9923,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
         }
         const sanitizedTitle = newTitle.replace(/[<>:"/\\|?*]/g, "");
         if (sanitizedTitle !== newTitle) {
-          console.error(`[Crank] Title sanitized: "${newTitle}" \u2192 "${sanitizedTitle}"`);
+          console.error(`[Flywheel] Title sanitized: "${newTitle}" \u2192 "${sanitizedTitle}"`);
         }
         const fullPath = path19.join(vaultPath2, notePath);
         const dir = path19.dirname(notePath);
@@ -9983,7 +9988,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
         let lockAgeMs;
         if (commit) {
           const filesToCommit = [newPath, ...backlinkUpdates.map((b) => b.path)];
-          const gitResult = await commitChange(vaultPath2, filesToCommit.join(", "), `[Crank:Rename] ${oldTitle} \u2192 ${sanitizedTitle}`);
+          const gitResult = await commitChange(vaultPath2, filesToCommit.join(", "), `[Flywheel:Rename] ${oldTitle} \u2192 ${sanitizedTitle}`);
           if (gitResult.success && gitResult.hash) {
             gitCommit = gitResult.hash;
             undoAvailable = gitResult.undoAvailable;
@@ -9994,7 +9999,7 @@ function registerMoveNoteTools(server2, vaultPath2) {
           }
         }
         initializeEntityIndex(vaultPath2).catch((err) => {
-          console.error(`[Crank] Entity cache rebuild failed: ${err}`);
+          console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
         });
         const previewLines = [
           `Renamed: "${oldTitle}" \u2192 "${sanitizedTitle}"`
@@ -10036,7 +10041,7 @@ import { z as z16 } from "zod";
 function registerSystemTools2(server2, vaultPath2) {
   server2.tool(
     "vault_undo_last_mutation",
-    "Undo the last git commit (typically the last Crank mutation). Performs a soft reset.",
+    "Undo the last git commit (typically the last Flywheel mutation). Performs a soft reset.",
     {
       confirm: z16.boolean().default(false).describe("Must be true to confirm undo operation"),
       hash: z16.string().optional().describe("Expected commit hash. If provided, undo only proceeds if HEAD matches this hash. Prevents accidentally undoing the wrong commit.")
@@ -10095,15 +10100,15 @@ Actual HEAD: ${currentHead.hash} "${currentHead.message}"`
             return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
           }
         }
-        const lastCrankCommit = getLastCrankCommit();
+        const lastMutationCommit = getLastMutationCommit();
         const lastCommit = await getLastCommit(vaultPath2);
-        if (lastCrankCommit && lastCommit) {
-          if (lastCommit.hash !== lastCrankCommit.hash) {
+        if (lastMutationCommit && lastCommit) {
+          if (lastCommit.hash !== lastMutationCommit.hash) {
             const result2 = {
               success: false,
-              message: `Cannot undo: HEAD (${lastCommit.hash.substring(0, 7)}) doesn't match last Crank commit (${lastCrankCommit.hash.substring(0, 7)}). Another process may have committed since your mutation.`,
+              message: `Cannot undo: HEAD (${lastCommit.hash.substring(0, 7)}) doesn't match last Flywheel commit (${lastMutationCommit.hash.substring(0, 7)}). Another process may have committed since your mutation.`,
               path: "",
-              preview: `Expected: ${lastCrankCommit.hash.substring(0, 7)} "${lastCrankCommit.message}"
+              preview: `Expected: ${lastMutationCommit.hash.substring(0, 7)} "${lastMutationCommit.message}"
 Actual HEAD: ${lastCommit.hash.substring(0, 7)} "${lastCommit.message}"`
             };
             return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
@@ -10118,7 +10123,7 @@ Actual HEAD: ${lastCommit.hash.substring(0, 7)} "${lastCommit.message}"`
           };
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
-        clearLastCrankCommit();
+        clearLastMutationCommit();
         const result = {
           success: true,
           message: undoResult.message,
@@ -11471,6 +11476,109 @@ function registerPolicyTools(server2, vaultPath2) {
   );
 }
 
+// src/resources/vault.ts
+function registerVaultResources(server2, getIndex) {
+  server2.registerResource(
+    "vault-stats",
+    "vault://stats",
+    {
+      title: "Vault Statistics",
+      description: "Overview of vault size, tags, links, and orphan count",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const index = getIndex();
+      if (!index) {
+        return {
+          contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ error: "Index not ready" }) }]
+        };
+      }
+      const noteCount = index.notes.size;
+      const tagCount = index.tags.size;
+      let totalLinks = 0;
+      for (const note of index.notes.values()) {
+        totalLinks += note.outlinks.length;
+      }
+      let orphanCount = 0;
+      for (const note of index.notes.values()) {
+        const normalizedTitle = note.title.toLowerCase();
+        const backlinks = index.backlinks.get(normalizedTitle);
+        if (!backlinks || backlinks.length === 0) {
+          orphanCount++;
+        }
+      }
+      const stats = {
+        note_count: noteCount,
+        tag_count: tagCount,
+        total_links: totalLinks,
+        orphan_count: orphanCount,
+        index_built_at: index.builtAt.toISOString()
+      };
+      return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(stats, null, 2) }]
+      };
+    }
+  );
+  server2.registerResource(
+    "vault-schema",
+    "vault://schema",
+    {
+      title: "Vault Schema",
+      description: "Frontmatter field summary: field names, types, frequency",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const index = getIndex();
+      if (!index) {
+        return {
+          contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ error: "Index not ready" }) }]
+        };
+      }
+      const schema = getFrontmatterSchema(index);
+      const compact = {
+        total_notes: schema.total_notes,
+        notes_with_frontmatter: schema.notes_with_frontmatter,
+        field_count: schema.field_count,
+        fields: schema.fields.map((f) => ({
+          name: f.name,
+          types: f.types,
+          count: f.count,
+          examples: f.examples.slice(0, 3)
+        }))
+      };
+      return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(compact, null, 2) }]
+      };
+    }
+  );
+  server2.registerResource(
+    "vault-recent",
+    "vault://recent",
+    {
+      title: "Recently Modified Notes",
+      description: "Last 10 modified notes in the vault",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const index = getIndex();
+      if (!index) {
+        return {
+          contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ error: "Index not ready" }) }]
+        };
+      }
+      const notes = Array.from(index.notes.values()).sort((a, b) => b.modified.getTime() - a.modified.getTime()).slice(0, 10).map((n) => ({
+        path: n.path,
+        title: n.title,
+        modified: n.modified.toISOString(),
+        tags: n.tags
+      }));
+      return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ recent_notes: notes }, null, 2) }]
+      };
+    }
+  );
+}
+
 // src/index.ts
 var vaultPath = process.env.PROJECT_PATH || process.env.VAULT_PATH || findVaultRoot();
 var vaultIndex;
@@ -11661,6 +11769,7 @@ registerNoteTools(server, vaultPath, () => vaultIndex);
 registerMoveNoteTools(server, vaultPath);
 registerSystemTools2(server, vaultPath);
 registerPolicyTools(server, vaultPath);
+registerVaultResources(server, () => vaultIndex ?? null);
 console.error(`[Memory] Registered ${_registeredCount} tools, skipped ${_skippedCount}`);
 async function main() {
   console.error(`[Memory] Starting Flywheel Memory server...`);
@@ -11670,7 +11779,7 @@ async function main() {
     stateDb = openStateDb(vaultPath);
     console.error("[Memory] StateDb initialized");
     setFTS5Database(stateDb.db);
-    setCrankStateDb(stateDb);
+    setWriteStateDb(stateDb);
     await initializeEntityIndex(vaultPath);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -11817,6 +11926,9 @@ async function runPostIndexWork(index) {
     } else {
       const debounceMs = parseInt(process.env.FLYWHEEL_DEBOUNCE_MS || "60000");
       console.error(`[Memory] File watcher v1 enabled (debounce: ${debounceMs}ms)`);
+      if (debounceMs >= 6e4) {
+        console.error("[Memory] Warning: Legacy watcher using high debounce (60s). Set FLYWHEEL_WATCH_V2=true for 200ms responsiveness.");
+      }
       const legacyWatcher = chokidar2.watch(vaultPath, {
         ignored: /(^|[\/\\])\../,
         persistent: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-memory",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "MCP server that gives Claude full read/write access to your Obsidian vault. 36 tools for search, backlinks, graph queries, and mutations.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^2.0.7",
+    "@velvetmonkey/vault-core": "^2.0.9",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",
     "gray-matter": "^4.0.3",