@velvetmonkey/flywheel-memory 2.0.59 → 2.0.60

package/dist/index.js

@@ -13184,7 +13184,7 @@ function ensureSectionExists(content, section, notePath) {
   return { error: errorResult(notePath, message) };
 }
 async function withVaultFile(options, operation) {
-  const { vaultPath: vaultPath2, notePath, commit, commitPrefix, section, actionDescription, scoping } = options;
+  const { vaultPath: vaultPath2, notePath, commit, commitPrefix, section, actionDescription, scoping, dryRun } = options;
   try {
     const existsError = await ensureFileExists(vaultPath2, notePath);
     if (existsError) {
@@ -13219,6 +13219,17 @@ async function withVaultFile(options, operation) {
     if ("error" in result) {
       return formatMcpResult(result.error);
     }
+    const { opResult, frontmatter, lineEnding } = result;
+    if (dryRun) {
+      const dryResult = successResult(notePath, `[dry run] ${opResult.message}`, {}, {
+        preview: opResult.preview,
+        warnings: opResult.warnings,
+        outputIssues: opResult.outputIssues,
+        normalizationChanges: opResult.normalizationChanges,
+        dryRun: true
+      });
+      return formatMcpResult(dryResult);
+    }
     const fullPath = path21.join(vaultPath2, notePath);
     const statBefore = await fs19.stat(fullPath);
     if (statBefore.mtimeMs !== result.mtimeMs) {
@@ -13228,7 +13239,6 @@ async function withVaultFile(options, operation) {
         return formatMcpResult(result.error);
       }
     }
-    const { opResult, frontmatter, lineEnding } = result;
     let finalFrontmatter = opResult.updatedFrontmatter ?? frontmatter;
     if (scoping && (scoping.agent_id || scoping.session_id)) {
       finalFrontmatter = injectMutationMetadata(finalFrontmatter, scoping);
@@ -13256,7 +13266,7 @@ async function withVaultFile(options, operation) {
   }
 }
 async function withVaultFrontmatter(options, operation) {
-  const { vaultPath: vaultPath2, notePath, commit, commitPrefix, actionDescription } = options;
+  const { vaultPath: vaultPath2, notePath, commit, commitPrefix, actionDescription, dryRun } = options;
   try {
     const existsError = await ensureFileExists(vaultPath2, notePath);
     if (existsError) {
@@ -13265,6 +13275,13 @@ async function withVaultFrontmatter(options, operation) {
     const { content, frontmatter, lineEnding } = await readVaultFile(vaultPath2, notePath);
     const ctx = { content, frontmatter, lineEnding, vaultPath: vaultPath2, notePath };
     const opResult = await operation(ctx);
+    if (dryRun) {
+      const result2 = successResult(notePath, `[dry run] ${opResult.message}`, {}, {
+        preview: opResult.preview,
+        dryRun: true
+      });
+      return formatMcpResult(result2);
+    }
     await writeVaultFile(vaultPath2, notePath, content, opResult.updatedFrontmatter, lineEnding);
     const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, commitPrefix);
     const result = successResult(notePath, opResult.message, gitInfo, {
@@ -13360,10 +13377,11 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
       normalize: z11.boolean().default(true).describe("Auto-fix common issues before formatting (replace \u2022 with -, trim excessive whitespace, etc.)"),
       guardrails: z11.enum(["warn", "strict", "off"]).default("warn").describe('Output validation mode: "warn" returns issues but proceeds, "strict" blocks on errors, "off" disables'),
       linkedEntities: z11.array(z11.string()).optional().describe("Entity names already linked in the content. When skipWikilinks=true, these are tracked for feedback without re-processing the content."),
+      dry_run: z11.boolean().optional().default(false).describe("Preview changes without writing to disk"),
       agent_id: z11.string().optional().describe('Agent identifier for multi-agent scoping (e.g., "claude-opus", "planning-agent")'),
       session_id: z11.string().optional().describe('Session identifier for conversation scoping (e.g., "sess-abc123")')
     },
-    async ({ path: notePath, section, content, create_if_missing, position, format, commit, skipWikilinks, preserveListNesting, bumpHeadings, suggestOutgoingLinks, maxSuggestions, validate, normalize, guardrails, linkedEntities, agent_id, session_id }) => {
+    async ({ path: notePath, section, content, create_if_missing, position, format, commit, skipWikilinks, preserveListNesting, bumpHeadings, suggestOutgoingLinks, maxSuggestions, validate, normalize, guardrails, linkedEntities, dry_run, agent_id, session_id }) => {
       let noteCreated = false;
       let templateUsed;
       if (create_if_missing) {
@@ -13385,7 +13403,8 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
           commitPrefix: "[Flywheel:Add]",
           section,
           actionDescription: "add content",
-          scoping: agent_id || session_id ? { agent_id, session_id } : void 0
+          scoping: agent_id || session_id ? { agent_id, session_id } : void 0,
+          dryRun: dry_run
         },
         async (ctx) => {
           const validationResult = runValidationPipeline(content, format, {
@@ -13454,10 +13473,11 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
       mode: z11.enum(["first", "last", "all"]).default("first").describe("Which matches to remove"),
       useRegex: z11.boolean().default(false).describe("Treat pattern as regex"),
       commit: z11.boolean().default(false).describe("If true, commit this change to git (creates undo point)"),
+      dry_run: z11.boolean().optional().default(false).describe("Preview changes without writing to disk"),
       agent_id: z11.string().optional().describe("Agent identifier for multi-agent scoping"),
       session_id: z11.string().optional().describe("Session identifier for conversation scoping")
     },
-    async ({ path: notePath, section, pattern, mode, useRegex, commit, agent_id, session_id }) => {
+    async ({ path: notePath, section, pattern, mode, useRegex, commit, dry_run, agent_id, session_id }) => {
       return withVaultFile(
         {
           vaultPath: vaultPath2,
@@ -13466,7 +13486,8 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
           commitPrefix: "[Flywheel:Remove]",
           section,
           actionDescription: "remove content",
-          scoping: agent_id || session_id ? { agent_id, session_id } : void 0
+          scoping: agent_id || session_id ? { agent_id, session_id } : void 0,
+          dryRun: dry_run
         },
         async (ctx) => {
           const removeResult = removeFromSection(
@@ -13505,10 +13526,11 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
       validate: z11.boolean().default(true).describe("Check input for common issues (double timestamps, non-markdown bullets, etc.)"),
       normalize: z11.boolean().default(true).describe("Auto-fix common issues before formatting (replace \u2022 with -, trim excessive whitespace, etc.)"),
       guardrails: z11.enum(["warn", "strict", "off"]).default("warn").describe('Output validation mode: "warn" returns issues but proceeds, "strict" blocks on errors, "off" disables'),
+      dry_run: z11.boolean().optional().default(false).describe("Preview changes without writing to disk"),
       agent_id: z11.string().optional().describe("Agent identifier for multi-agent scoping"),
       session_id: z11.string().optional().describe("Session identifier for conversation scoping")
     },
-    async ({ path: notePath, section, search, replacement, mode, useRegex, commit, skipWikilinks, suggestOutgoingLinks, maxSuggestions, validate, normalize, guardrails, agent_id, session_id }) => {
+    async ({ path: notePath, section, search, replacement, mode, useRegex, commit, skipWikilinks, suggestOutgoingLinks, maxSuggestions, validate, normalize, guardrails, dry_run, agent_id, session_id }) => {
       return withVaultFile(
         {
           vaultPath: vaultPath2,
@@ -13517,7 +13539,8 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
           commitPrefix: "[Flywheel:Replace]",
           section,
           actionDescription: "replace content",
-          scoping: agent_id || session_id ? { agent_id, session_id } : void 0
+          scoping: agent_id || session_id ? { agent_id, session_id } : void 0,
+          dryRun: dry_run
         },
         async (ctx) => {
           const validationResult = runValidationPipeline(replacement, "plain", {
@@ -13633,10 +13656,11 @@ function registerTaskTools(server2, vaultPath2) {
       task: z12.string().describe("Task text to find (partial match supported)"),
       section: z12.string().optional().describe("Optional: limit search to this section"),
       commit: z12.boolean().default(false).describe("If true, commit this change to git (creates undo point)"),
+      dry_run: z12.boolean().optional().default(false).describe("Preview changes without writing to disk"),
       agent_id: z12.string().optional().describe("Agent identifier for multi-agent scoping"),
       session_id: z12.string().optional().describe("Session identifier for conversation scoping")
     },
-    async ({ path: notePath, task, section, commit, agent_id, session_id }) => {
+    async ({ path: notePath, task, section, commit, dry_run, agent_id, session_id }) => {
       try {
         const existsError = await ensureFileExists(vaultPath2, notePath);
         if (existsError) {
@@ -13665,6 +13689,16 @@ function registerTaskTools(server2, vaultPath2) {
         if (!toggleResult) {
           return formatMcpResult(errorResult(notePath, "Failed to toggle task"));
         }
+        const newStatus = toggleResult.newState ? "completed" : "incomplete";
+        const checkbox = toggleResult.newState ? "[x]" : "[ ]";
+        if (dry_run) {
+          return formatMcpResult(
+            successResult(notePath, `[dry run] Toggled task to ${newStatus} in ${notePath}`, {}, {
+              preview: `${checkbox} ${matchingTask.text}`,
+              dryRun: true
+            })
+          );
+        }
         let finalFrontmatter = frontmatter;
         if (agent_id || session_id) {
           finalFrontmatter = injectMutationMetadata(frontmatter, { agent_id, session_id });
@@ -13673,8 +13707,6 @@ function registerTaskTools(server2, vaultPath2) {
         await updateTaskCacheForFile(vaultPath2, notePath).catch(() => {
         });
         const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Task]");
-        const newStatus = toggleResult.newState ? "completed" : "incomplete";
-        const checkbox = toggleResult.newState ? "[x]" : "[ ]";
         return formatMcpResult(
           successResult(notePath, `Toggled task to ${newStatus} in ${notePath}`, gitInfo, {
             preview: `${checkbox} ${matchingTask.text}`
@@ -13704,10 +13736,11 @@ function registerTaskTools(server2, vaultPath2) {
       validate: z12.boolean().default(true).describe("Check input for common issues"),
       normalize: z12.boolean().default(true).describe("Auto-fix common issues before formatting"),
       guardrails: z12.enum(["warn", "strict", "off"]).default("warn").describe("Output validation mode"),
+      dry_run: z12.boolean().optional().default(false).describe("Preview changes without writing to disk"),
       agent_id: z12.string().optional().describe("Agent identifier for multi-agent scoping"),
       session_id: z12.string().optional().describe("Session identifier for conversation scoping")
     },
-    async ({ path: notePath, section, task, position, completed, commit, skipWikilinks, suggestOutgoingLinks, maxSuggestions, preserveListNesting, validate, normalize, guardrails, agent_id, session_id }) => {
+    async ({ path: notePath, section, task, position, completed, commit, skipWikilinks, suggestOutgoingLinks, maxSuggestions, preserveListNesting, validate, normalize, guardrails, dry_run, agent_id, session_id }) => {
       return withVaultFile(
         {
           vaultPath: vaultPath2,
@@ -13716,7 +13749,8 @@ function registerTaskTools(server2, vaultPath2) {
           commitPrefix: "[Flywheel:Task]",
           section,
           actionDescription: "add task",
-          scoping: agent_id || session_id ? { agent_id, session_id } : void 0
+          scoping: agent_id || session_id ? { agent_id, session_id } : void 0,
+          dryRun: dry_run
         },
         async (ctx) => {
           const validationResult = runValidationPipeline(task.trim(), "task", {
@@ -13774,16 +13808,18 @@ Example: vault_update_frontmatter({ path: "projects/alpha.md", frontmatter: { st
       path: z13.string().describe("Vault-relative path to the note"),
       frontmatter: z13.record(z13.any()).describe("Frontmatter fields to update (JSON object)"),
       only_if_missing: z13.boolean().default(false).describe("If true, only add fields that don't already exist in the frontmatter (skip existing keys)"),
-      commit: z13.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
+      commit: z13.boolean().default(false).describe("If true, commit this change to git (creates undo point)"),
+      dry_run: z13.boolean().optional().default(false).describe("Preview changes without writing to disk")
     },
-    async ({ path: notePath, frontmatter: updates, only_if_missing, commit }) => {
+    async ({ path: notePath, frontmatter: updates, only_if_missing, commit, dry_run }) => {
       return withVaultFrontmatter(
         {
           vaultPath: vaultPath2,
           notePath,
           commit,
           commitPrefix: "[Flywheel:FM]",
-          actionDescription: "update frontmatter"
+          actionDescription: "update frontmatter",
+          dryRun: dry_run
         },
         async (ctx) => {
           let effectiveUpdates;
@@ -13841,10 +13877,11 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
       skipWikilinks: z14.boolean().default(false).describe("If true, skip auto-wikilink application (wikilinks are applied by default)"),
       suggestOutgoingLinks: z14.boolean().default(true).describe('Append suggested outgoing wikilinks based on content (e.g., "\u2192 [[AI]], [[Philosophy]]").'),
       maxSuggestions: z14.number().min(1).max(10).default(5).describe("Maximum number of suggested wikilinks to append (1-10, default: 5)"),
+      dry_run: z14.boolean().optional().default(false).describe("Preview changes without writing to disk"),
       agent_id: z14.string().optional().describe("Agent identifier for multi-agent scoping"),
       session_id: z14.string().optional().describe("Session identifier for conversation scoping")
     },
-    async ({ path: notePath, content, template, frontmatter, overwrite, commit, skipWikilinks, suggestOutgoingLinks, maxSuggestions, agent_id, session_id }) => {
+    async ({ path: notePath, content, template, frontmatter, overwrite, commit, skipWikilinks, suggestOutgoingLinks, maxSuggestions, dry_run, agent_id, session_id }) => {
       try {
         if (!validatePath(vaultPath2, notePath)) {
           return formatMcpResult(errorResult(notePath, "Invalid path: path traversal not allowed"));
@@ -13922,8 +13959,6 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
         if (agent_id || session_id) {
           finalFrontmatter = injectMutationMetadata(effectiveFrontmatter, { agent_id, session_id });
         }
-        await writeVaultFile(vaultPath2, notePath, processedContent, finalFrontmatter);
-        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Create]");
         const infoLines = [wikilinkInfo, suggestInfo].filter(Boolean);
         const previewLines = [
           `Frontmatter fields: ${Object.keys(effectiveFrontmatter).join(", ") || "none"}`,
@@ -13946,6 +13981,17 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
             previewLines.push('Tip: Add aliases to frontmatter for flexible wikilink matching (e.g., aliases: ["Short Name"])');
           }
         }
+        if (dry_run) {
+          return formatMcpResult(
+            successResult(notePath, `[dry run] Would create note: ${notePath}`, {}, {
+              preview: previewLines.join("\n"),
+              warnings: warnings.length > 0 ? warnings : void 0,
+              dryRun: true
+            })
+          );
+        }
+        await writeVaultFile(vaultPath2, notePath, processedContent, finalFrontmatter);
+        const gitInfo = await handleGitCommit(vaultPath2, notePath, commit, "[Flywheel:Create]");
         return formatMcpResult(
           successResult(notePath, `Created note: ${notePath}`, gitInfo, {
             preview: previewLines.join("\n"),
@@ -13965,9 +14011,10 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
     {
       path: z14.string().describe("Vault-relative path to the note to delete"),
       confirm: z14.boolean().default(false).describe("Must be true to confirm deletion"),
-      commit: z14.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
+      commit: z14.boolean().default(false).describe("If true, commit this change to git (creates undo point)"),
+      dry_run: z14.boolean().optional().default(false).describe("Preview what would be deleted without actually deleting")
     },
-    async ({ path: notePath, confirm, commit }) => {
+    async ({ path: notePath, confirm, commit, dry_run }) => {
       try {
         if (!validatePath(vaultPath2, notePath)) {
           return formatMcpResult(errorResult(notePath, "Invalid path: path traversal not allowed"));
@@ -13993,6 +14040,19 @@ ${sources}`;
           } catch {
           }
         }
+        if (dry_run) {
+          const previewLines = [`Would delete: ${notePath}`];
+          if (backlinkWarning) {
+            previewLines.push("");
+            previewLines.push("Warning: " + backlinkWarning);
+          }
+          return formatMcpResult(
+            successResult(notePath, `[dry run] Would delete note: ${notePath}`, {}, {
+              preview: previewLines.join("\n"),
+              dryRun: true
+            })
+          );
+        }
         if (!confirm) {
           const previewLines = ["Deletion requires explicit confirmation (confirm=true)"];
           if (backlinkWarning) {
@@ -14127,9 +14187,10 @@ function registerMoveNoteTools(server2, vaultPath2) {
       oldPath: z15.string().describe('Vault-relative path to move from (e.g., "inbox/note.md")'),
       newPath: z15.string().describe('Vault-relative path to move to (e.g., "projects/note.md")'),
       updateBacklinks: z15.boolean().default(true).describe("If true (default), updates all backlinks pointing to this note"),
-      commit: z15.boolean().default(false).describe("If true, commit all changes to git")
+      commit: z15.boolean().default(false).describe("If true, commit all changes to git"),
+      dry_run: z15.boolean().optional().default(false).describe("Preview what would change without moving any files")
     },
-    async ({ oldPath, newPath, updateBacklinks, commit }) => {
+    async ({ oldPath, newPath, updateBacklinks, commit, dry_run }) => {
       try {
         if (!validatePath(vaultPath2, oldPath)) {
           const result2 = {
@@ -14175,29 +14236,60 @@ function registerMoveNoteTools(server2, vaultPath2) {
         const oldTitle = getTitleFromPath(oldPath);
         const newTitle = getTitleFromPath(newPath);
         let backlinkCount = 0;
-        let updatedBacklinks = 0;
         const backlinkUpdates = [];
         if (updateBacklinks && oldTitle.toLowerCase() !== newTitle.toLowerCase()) {
-          const allOldTitles = [oldTitle, ...aliases];
           const backlinks = await findBacklinks(vaultPath2, oldTitle, aliases);
           backlinkCount = backlinks.reduce((sum, b) => sum + b.links.length, 0);
-          for (const backlink of backlinks) {
-            if (backlink.path === oldPath) continue;
-            const updateResult = await updateBacklinksInFile(
-              vaultPath2,
-              backlink.path,
-              allOldTitles,
-              newTitle
-            );
-            if (updateResult.updated) {
-              updatedBacklinks += updateResult.linksUpdated;
+          if (dry_run) {
+            for (const backlink of backlinks) {
+              if (backlink.path === oldPath) continue;
               backlinkUpdates.push({
                 path: backlink.path,
-                linksUpdated: updateResult.linksUpdated
+                linksUpdated: backlink.links.length
               });
             }
+          } else {
+            const allOldTitles = [oldTitle, ...aliases];
+            for (const backlink of backlinks) {
+              if (backlink.path === oldPath) continue;
+              const updateResult = await updateBacklinksInFile(
+                vaultPath2,
+                backlink.path,
+                allOldTitles,
+                newTitle
+              );
+              if (updateResult.updated) {
+                backlinkUpdates.push({
+                  path: backlink.path,
+                  linksUpdated: updateResult.linksUpdated
+                });
+              }
+            }
           }
         }
+        const updatedBacklinks = backlinkUpdates.reduce((sum, b) => sum + b.linksUpdated, 0);
+        const previewLines = [
+          `${dry_run ? "Would move" : "Moved"}: ${oldPath} \u2192 ${newPath}`
+        ];
+        if (backlinkCount > 0) {
+          previewLines.push(`Backlinks found: ${backlinkCount}`);
+          previewLines.push(`Backlinks ${dry_run ? "to update" : "updated"}: ${updatedBacklinks}`);
+          if (backlinkUpdates.length > 0) {
+            previewLines.push(`Files ${dry_run ? "to modify" : "modified"}: ${backlinkUpdates.map((b) => b.path).join(", ")}`);
+          }
+        } else {
+          previewLines.push("No backlinks found");
+        }
+        if (dry_run) {
+          const result2 = {
+            success: true,
+            message: `[dry run] Would move note: ${oldPath} \u2192 ${newPath}`,
+            path: newPath,
+            preview: previewLines.join("\n"),
+            dryRun: true
+          };
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+        }
         const destDir = path24.dirname(newFullPath);
         await fs22.mkdir(destDir, { recursive: true });
         await fs22.rename(oldFullPath, newFullPath);
@@ -14220,18 +14312,6 @@ function registerMoveNoteTools(server2, vaultPath2) {
         initializeEntityIndex(vaultPath2).catch((err) => {
           console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
         });
-        const previewLines = [
-          `Moved: ${oldPath} \u2192 ${newPath}`
-        ];
-        if (backlinkCount > 0) {
-          previewLines.push(`Backlinks found: ${backlinkCount}`);
-          previewLines.push(`Backlinks updated: ${updatedBacklinks}`);
-          if (backlinkUpdates.length > 0) {
-            previewLines.push(`Files modified: ${backlinkUpdates.map((b) => b.path).join(", ")}`);
-          }
-        } else {
-          previewLines.push("No backlinks found");
-        }
         const result = {
           success: true,
           message: `Moved note: ${oldPath} \u2192 ${newPath}`,
@@ -14260,9 +14340,10 @@ function registerMoveNoteTools(server2, vaultPath2) {
       path: z15.string().describe("Vault-relative path to the note to rename"),
       newTitle: z15.string().describe("New title for the note (without .md extension)"),
       updateBacklinks: z15.boolean().default(true).describe("If true (default), updates all backlinks pointing to this note"),
-      commit: z15.boolean().default(false).describe("If true, commit all changes to git")
+      commit: z15.boolean().default(false).describe("If true, commit all changes to git"),
+      dry_run: z15.boolean().optional().default(false).describe("Preview what would change without renaming any files")
     },
-    async ({ path: notePath, newTitle, updateBacklinks, commit }) => {
+    async ({ path: notePath, newTitle, updateBacklinks, commit, dry_run }) => {
       try {
         if (!validatePath(vaultPath2, notePath)) {
           const result2 = {
@@ -14315,29 +14396,60 @@ function registerMoveNoteTools(server2, vaultPath2) {
         const aliases = extractAliases2(parsed.data);
         const oldTitle = getTitleFromPath(notePath);
         let backlinkCount = 0;
-        let updatedBacklinks = 0;
         const backlinkUpdates = [];
         if (updateBacklinks && oldTitle.toLowerCase() !== sanitizedTitle.toLowerCase()) {
-          const allOldTitles = [oldTitle, ...aliases];
           const backlinks = await findBacklinks(vaultPath2, oldTitle, aliases);
           backlinkCount = backlinks.reduce((sum, b) => sum + b.links.length, 0);
-          for (const backlink of backlinks) {
-            if (backlink.path === notePath) continue;
-            const updateResult = await updateBacklinksInFile(
-              vaultPath2,
-              backlink.path,
-              allOldTitles,
-              sanitizedTitle
-            );
-            if (updateResult.updated) {
-              updatedBacklinks += updateResult.linksUpdated;
+          if (dry_run) {
+            for (const backlink of backlinks) {
+              if (backlink.path === notePath) continue;
               backlinkUpdates.push({
                 path: backlink.path,
-                linksUpdated: updateResult.linksUpdated
+                linksUpdated: backlink.links.length
               });
             }
+          } else {
+            const allOldTitles = [oldTitle, ...aliases];
+            for (const backlink of backlinks) {
+              if (backlink.path === notePath) continue;
+              const updateResult = await updateBacklinksInFile(
+                vaultPath2,
+                backlink.path,
+                allOldTitles,
+                sanitizedTitle
+              );
+              if (updateResult.updated) {
+                backlinkUpdates.push({
+                  path: backlink.path,
+                  linksUpdated: updateResult.linksUpdated
+                });
+              }
+            }
           }
         }
+        const updatedBacklinks = backlinkUpdates.reduce((sum, b) => sum + b.linksUpdated, 0);
+        const previewLines = [
+          `${dry_run ? "Would rename" : "Renamed"}: "${oldTitle}" \u2192 "${sanitizedTitle}"`
+        ];
+        if (backlinkCount > 0) {
+          previewLines.push(`Backlinks found: ${backlinkCount}`);
+          previewLines.push(`Backlinks ${dry_run ? "to update" : "updated"}: ${updatedBacklinks}`);
+          if (backlinkUpdates.length > 0) {
+            previewLines.push(`Files ${dry_run ? "to modify" : "modified"}: ${backlinkUpdates.map((b) => b.path).join(", ")}`);
+          }
+        } else {
+          previewLines.push("No backlinks found");
+        }
+        if (dry_run) {
+          const result2 = {
+            success: true,
+            message: `[dry run] Would rename note: ${oldTitle} \u2192 ${sanitizedTitle}`,
+            path: newPath,
+            preview: previewLines.join("\n"),
+            dryRun: true
+          };
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+        }
         if (fullPath !== newFullPath) {
           await fs22.rename(fullPath, newFullPath);
         }
@@ -14360,18 +14472,6 @@ function registerMoveNoteTools(server2, vaultPath2) {
         initializeEntityIndex(vaultPath2).catch((err) => {
           console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
         });
-        const previewLines = [
-          `Renamed: "${oldTitle}" \u2192 "${sanitizedTitle}"`
-        ];
-        if (backlinkCount > 0) {
-          previewLines.push(`Backlinks found: ${backlinkCount}`);
-          previewLines.push(`Backlinks updated: ${updatedBacklinks}`);
-          if (backlinkUpdates.length > 0) {
-            previewLines.push(`Files modified: ${backlinkUpdates.map((b) => b.path).join(", ")}`);
-          }
-        } else {
-          previewLines.push("No backlinks found");
-        }
         const result = {
           success: true,
           message: `Renamed note: ${oldTitle} \u2192 ${sanitizedTitle}`,
@@ -14405,9 +14505,10 @@ function registerMergeTools(server2, vaultPath2) {
     "Merge a source entity note into a target entity note: adds alias, appends content, updates wikilinks, deletes source",
     {
       source_path: z16.string().describe("Vault-relative path of the note to merge FROM (will be deleted)"),
-      target_path: z16.string().describe("Vault-relative path of the note to merge INTO (receives alias + content)")
+      target_path: z16.string().describe("Vault-relative path of the note to merge INTO (receives alias + content)"),
+      dry_run: z16.boolean().optional().default(false).describe("Preview merge plan without modifying any files")
     },
-    async ({ source_path, target_path }) => {
+    async ({ source_path, target_path, dry_run }) => {
       try {
         if (!validatePath(vaultPath2, source_path)) {
           const result2 = {
@@ -14478,18 +14579,46 @@ ${trimmedSource}`;
         const backlinks = await findBacklinks(vaultPath2, sourceTitle, sourceAliases);
         let totalBacklinksUpdated = 0;
         const modifiedFiles = [];
-        for (const backlink of backlinks) {
-          if (backlink.path === source_path || backlink.path === target_path) continue;
-          const updateResult = await updateBacklinksInFile(
-            vaultPath2,
-            backlink.path,
-            allSourceTitles,
-            targetTitle
-          );
-          if (updateResult.updated) {
-            totalBacklinksUpdated += updateResult.linksUpdated;
+        if (dry_run) {
+          for (const backlink of backlinks) {
+            if (backlink.path === source_path || backlink.path === target_path) continue;
+            totalBacklinksUpdated += backlink.links.length;
             modifiedFiles.push(backlink.path);
           }
+        } else {
+          for (const backlink of backlinks) {
+            if (backlink.path === source_path || backlink.path === target_path) continue;
+            const updateResult = await updateBacklinksInFile(
+              vaultPath2,
+              backlink.path,
+              allSourceTitles,
+              targetTitle
+            );
+            if (updateResult.updated) {
+              totalBacklinksUpdated += updateResult.linksUpdated;
+              modifiedFiles.push(backlink.path);
+            }
+          }
+        }
+        const previewLines = [
+          `${dry_run ? "Would merge" : "Merged"}: "${sourceTitle}" \u2192 "${targetTitle}"`,
+          `Aliases ${dry_run ? "to add" : "added"}: ${allNewAliases.join(", ")}`,
+          `Source content ${dry_run ? "to append" : "appended"}: ${trimmedSource.length > 10 ? "yes" : "no"}`,
+          `Backlinks ${dry_run ? "to update" : "updated"}: ${totalBacklinksUpdated}`
+        ];
+        if (modifiedFiles.length > 0) {
+          previewLines.push(`Files ${dry_run ? "to modify" : "modified"}: ${modifiedFiles.join(", ")}`);
+        }
+        if (dry_run) {
+          const result2 = {
+            success: true,
+            message: `[dry run] Would merge "${sourceTitle}" into "${targetTitle}"`,
+            path: target_path,
+            preview: previewLines.join("\n"),
+            backlinks_updated: totalBacklinksUpdated,
+            dryRun: true
+          };
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
         await writeVaultFile(vaultPath2, target_path, targetContent, targetFrontmatter);
         const fullSourcePath = `${vaultPath2}/${source_path}`;
@@ -14497,15 +14626,6 @@ ${trimmedSource}`;
         initializeEntityIndex(vaultPath2).catch((err) => {
           console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
         });
-        const previewLines = [
-          `Merged: "${sourceTitle}" \u2192 "${targetTitle}"`,
-          `Aliases added: ${allNewAliases.join(", ")}`,
-          `Source content appended: ${trimmedSource.length > 10 ? "yes" : "no"}`,
-          `Backlinks updated: ${totalBacklinksUpdated}`
-        ];
-        if (modifiedFiles.length > 0) {
-          previewLines.push(`Files modified: ${modifiedFiles.join(", ")}`);
-        }
         const result = {
           success: true,
           message: `Merged "${sourceTitle}" into "${targetTitle}"`,
@@ -14529,9 +14649,10 @@ ${trimmedSource}`;
     "Absorb an entity name as an alias of a target note: adds alias to target frontmatter and rewrites all [[source]] links to [[target|source]]. Lighter than merge_entities \u2014 no source note required, no content append, no deletion.",
     {
       source_name: z16.string().describe('The entity name to absorb (e.g. "Foo")'),
-      target_path: z16.string().describe('Vault-relative path of the target entity note (e.g. "entities/Bar.md")')
+      target_path: z16.string().describe('Vault-relative path of the target entity note (e.g. "entities/Bar.md")'),
+      dry_run: z16.boolean().optional().default(false).describe("Preview what would change without modifying any files")
     },
-    async ({ source_name, target_path }) => {
+    async ({ source_name, target_path, dry_run }) => {
       try {
         if (!validatePath(vaultPath2, target_path)) {
           const result2 = {
@@ -14562,58 +14683,67 @@ ${trimmedSource}`;
           deduped.add(source_name);
         }
         targetFrontmatter.aliases = Array.from(deduped);
-        await writeVaultFile(vaultPath2, target_path, targetContent, targetFrontmatter);
         const backlinks = await findBacklinks(vaultPath2, source_name, []);
         let totalBacklinksUpdated = 0;
         const modifiedFiles = [];
-        for (const backlink of backlinks) {
-          if (backlink.path === target_path) continue;
-          let fileData;
-          try {
-            fileData = await readVaultFile(vaultPath2, backlink.path);
-          } catch {
-            continue;
+        if (dry_run) {
+          for (const backlink of backlinks) {
+            if (backlink.path === target_path) continue;
+            totalBacklinksUpdated += backlink.links.length;
+            modifiedFiles.push(backlink.path);
           }
-          let content = fileData.content;
-          let linksUpdated = 0;
-          const pattern = new RegExp(
-            `\\[\\[${escapeRegex(source_name)}(\\|[^\\]]+)?\\]\\]`,
-            "gi"
-          );
-          content = content.replace(pattern, (_match, displayPart) => {
-            linksUpdated++;
-            if (displayPart) {
-              return `[[${targetTitle}${displayPart}]]`;
+        } else {
+          await writeVaultFile(vaultPath2, target_path, targetContent, targetFrontmatter);
+          for (const backlink of backlinks) {
+            if (backlink.path === target_path) continue;
+            let fileData;
+            try {
+              fileData = await readVaultFile(vaultPath2, backlink.path);
+            } catch {
+              continue;
             }
-            if (source_name.toLowerCase() === targetTitle.toLowerCase()) {
-              return `[[${targetTitle}]]`;
+            let content = fileData.content;
+            let linksUpdated = 0;
+            const pattern = new RegExp(
+              `\\[\\[${escapeRegex(source_name)}(\\|[^\\]]+)?\\]\\]`,
+              "gi"
+            );
+            content = content.replace(pattern, (_match, displayPart) => {
+              linksUpdated++;
+              if (displayPart) {
+                return `[[${targetTitle}${displayPart}]]`;
+              }
+              if (source_name.toLowerCase() === targetTitle.toLowerCase()) {
+                return `[[${targetTitle}]]`;
+              }
+              return `[[${targetTitle}|${source_name}]]`;
+            });
+            if (linksUpdated > 0) {
+              await writeVaultFile(vaultPath2, backlink.path, content, fileData.frontmatter);
+              totalBacklinksUpdated += linksUpdated;
+              modifiedFiles.push(backlink.path);
             }
-            return `[[${targetTitle}|${source_name}]]`;
-          });
-          if (linksUpdated > 0) {
-            await writeVaultFile(vaultPath2, backlink.path, content, fileData.frontmatter);
-            totalBacklinksUpdated += linksUpdated;
-            modifiedFiles.push(backlink.path);
           }
+          initializeEntityIndex(vaultPath2).catch((err) => {
+            console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
+          });
         }
-        initializeEntityIndex(vaultPath2).catch((err) => {
-          console.error(`[Flywheel] Entity cache rebuild failed: ${err}`);
-        });
         const aliasAdded = source_name.toLowerCase() !== targetTitle.toLowerCase();
         const previewLines = [
-          `Absorbed: "${source_name}" \u2192 "${targetTitle}"`,
-          `Alias added: ${aliasAdded ? source_name : "no (matches target title)"}`,
-          `Backlinks updated: ${totalBacklinksUpdated}`
+          `${dry_run ? "Would absorb" : "Absorbed"}: "${source_name}" \u2192 "${targetTitle}"`,
+          `Alias ${dry_run ? "to add" : "added"}: ${aliasAdded ? source_name : "no (matches target title)"}`,
+          `Backlinks ${dry_run ? "to update" : "updated"}: ${totalBacklinksUpdated}`
         ];
         if (modifiedFiles.length > 0) {
-          previewLines.push(`Files modified: ${modifiedFiles.join(", ")}`);
+          previewLines.push(`Files ${dry_run ? "to modify" : "modified"}: ${modifiedFiles.join(", ")}`);
         }
         const result = {
           success: true,
-          message: `Absorbed "${source_name}" as alias of "${targetTitle}"`,
+          message: dry_run ? `[dry run] Would absorb "${source_name}" as alias of "${targetTitle}"` : `Absorbed "${source_name}" as alias of "${targetTitle}"`,
           path: target_path,
           preview: previewLines.join("\n"),
-          backlinks_updated: totalBacklinksUpdated
+          backlinks_updated: totalBacklinksUpdated,
+          ...dry_run ? { dryRun: true } : {}
         };
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {

package/package.json

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