seekstone 0.12.1 → 0.13.0

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { resolve as resolve2 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -75,7 +76,6 @@ Docs: https://github.com/shaqmughal/seekstone`;
 
 // src/tools/append_note.ts
 import { readFile } from "fs/promises";
-import { join } from "path";
 
 // ../core/src/frontmatter.ts
 import { parse as parseYaml } from "yaml";
@@ -200,6 +200,16 @@ function assertWritable(policy2, relPath) {
   }
 }
 
+// src/vault-path.ts
+import { resolve, sep } from "path";
+function resolveVaultPath(vaultRoot2, inputPath) {
+  const abs = resolve(vaultRoot2, inputPath);
+  if (abs !== vaultRoot2 && !abs.startsWith(vaultRoot2 + sep)) {
+    throw new Error(`Path outside vault: ${inputPath}`);
+  }
+  return abs;
+}
+
 // src/tools/append_note.ts
 var AppendNoteInput = z.object({
   path: z.string().describe("Vault-relative path to the note."),
@@ -211,10 +221,7 @@ var AppendNoteInput = z.object({
   )
 });
 async function appendNote(ctx2, input) {
-  const absPath = join(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   assertWritable(ctx2.policy, input.path);
   const original = await readFile(absPath, "utf8");
   if (input.prevHash !== void 0) assertHashMatch(original, input.prevHash, input.path);
@@ -239,25 +246,64 @@ async function appendNote(ctx2, input) {
 }
 
 // ../core/src/extract.ts
+import { parseDocument, visit } from "yaml";
 var LINK_WITH_LINES_RE = /(!?\[\[)([^\]|#\n]{1,512})(#[^\]|\n]{1,512})?(\|[^\]\n]{1,512})?(\]\])/g;
 function extractLinksWithLines(raw) {
+  const fm = parseFrontmatter(raw);
+  if (!fm.present || fm.bodyStart === 0) return linksFromLines(raw, 1);
+  const fmRegion = raw.slice(0, fm.bodyStart);
+  const out = frontmatterLinks(fmRegion, fm.malformed);
+  const bodyFirstLine = countNewlines(fmRegion) + 1;
+  linksFromLinesInto(out, fm.body, bodyFirstLine);
+  return out;
+}
+function linksFromLines(text, firstLine) {
   const out = [];
-  const lines = raw.split("\n");
+  linksFromLinesInto(out, text, firstLine);
+  return out;
+}
+function linksFromLinesInto(out, text, firstLine) {
+  const lines = text.split("\n");
   for (const [lineIdx, lineText] of lines.entries()) {
-    for (const m of lineText.matchAll(LINK_WITH_LINES_RE)) {
-      const prefix = m[1] ?? "";
-      out.push({
-        raw: m[0] ?? "",
-        target: (m[2] ?? "").trim(),
-        fragment: m[3] ? m[3].slice(1).trim() : null,
-        alias: m[4] ? m[4].slice(1).trim() : null,
-        linkType: prefix.startsWith("!") ? "embed" : "wikilink",
-        line: lineIdx + 1
-      });
-    }
+    matchLinksInto(out, lineText, firstLine + lineIdx);
+  }
+}
+function matchLinksInto(out, text, line) {
+  for (const m of text.matchAll(LINK_WITH_LINES_RE)) {
+    const prefix = m[1] ?? "";
+    out.push({
+      raw: m[0] ?? "",
+      target: (m[2] ?? "").trim(),
+      fragment: m[3] ? m[3].slice(1).trim() : null,
+      alias: m[4] ? m[4].slice(1).trim() : null,
+      linkType: prefix.startsWith("!") ? "embed" : "wikilink",
+      line
+    });
   }
+}
+function frontmatterLinks(fmRegion, malformed) {
+  if (malformed) return linksFromLines(fmRegion, 1);
+  const yamlStart = fmRegion.indexOf("\n") + 1;
+  const closeLen = fmRegion.endsWith("---\r\n") ? 5 : 4;
+  const yamlText = fmRegion.slice(yamlStart, fmRegion.length - closeLen);
+  const doc = parseDocument(yamlText);
+  if (doc.errors.length > 0) return linksFromLines(fmRegion, 1);
+  const out = [];
+  visit(doc, {
+    Scalar(key, node) {
+      if (key === "key") return;
+      if (typeof node.value !== "string" || node.range == null) return;
+      const line = 2 + countNewlines(yamlText.slice(0, node.range[0]));
+      matchLinksInto(out, node.value, line);
+    }
+  });
   return out;
 }
+function countNewlines(text) {
+  let n = 0;
+  for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) n++;
+  return n;
+}
 var INLINE_TAG_RE = /(?:^|[^\w\]/])#([A-Za-z_][\w/-]*)/g;
 function extractInlineTags(body) {
   const out = [];
@@ -565,7 +611,7 @@ function contextPack(ctx2, input) {
 
 // src/tools/create_note.ts
 import { access, mkdir, readFile as readFile2 } from "fs/promises";
-import { dirname, join as join2 } from "path";
+import { dirname } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import { z as z4 } from "zod";
 
@@ -611,10 +657,7 @@ var CreateNoteInput = z4.object({
 });
 async function createNote(ctx2, rawInput) {
   const input = CreateNoteInput.parse(rawInput);
-  const absPath = join2(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   assertWritable(ctx2.policy, input.path);
   if (!input.overwrite) {
     try {
@@ -659,7 +702,7 @@ ${stringifyYaml(input.frontmatter, { lineWidth: 0 })}---
 
 // src/tools/delete_note.ts
 import { access as access2, mkdir as mkdir2, rename as rename2, rm } from "fs/promises";
-import { basename as basename2, extname as extname2, join as join3 } from "path";
+import { basename as basename2, extname as extname2, join } from "path";
 import { z as z5 } from "zod";
 
 // src/index/backlinks.ts
@@ -707,7 +750,7 @@ async function freeTrashPath(vaultRoot2, noteBase) {
   let candidate = `.trash/${noteBase}`;
   for (; ; ) {
     try {
-      await access2(join3(vaultRoot2, candidate));
+      await access2(join(vaultRoot2, candidate));
     } catch {
       return candidate;
     }
@@ -716,19 +759,16 @@ async function freeTrashPath(vaultRoot2, noteBase) {
 }
 async function deleteNote(ctx2, rawInput) {
   const input = DeleteNoteInput.parse(rawInput);
-  const absPath = join3(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   assertWritable(ctx2.policy, input.path);
   let trashedTo;
   if (input.permanent) {
     await rm(absPath);
   } else {
     await access2(absPath);
-    await mkdir2(join3(ctx2.vaultRoot, ".trash"), { recursive: true });
+    await mkdir2(join(ctx2.vaultRoot, ".trash"), { recursive: true });
     trashedTo = await freeTrashPath(ctx2.vaultRoot, basename2(input.path));
-    await rename2(absPath, join3(ctx2.vaultRoot, trashedTo));
+    await rename2(absPath, join(ctx2.vaultRoot, trashedTo));
   }
   removeNoteBacklinks(ctx2, input.path);
   if (ctx2.notes.has(input.path)) {
@@ -741,7 +781,6 @@ async function deleteNote(ctx2, rawInput) {
 }
 
 // src/tools/get_backlinks.ts
-import { join as join4 } from "path";
 import { z as z6 } from "zod";
 var GetBacklinksInput = z6.object({
   path: z6.string().describe("Vault-relative path to the target note."),
@@ -750,10 +789,7 @@ var GetBacklinksInput = z6.object({
 });
 var EXCERPT_MAX = 200;
 function getBacklinks(ctx2, input) {
-  const absPath = join4(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  resolveVaultPath(ctx2.vaultRoot, input.path);
   const includeContext = input.includeContext ?? true;
   const limit = input.limit ?? 50;
   const refs = ctx2.backlinks.get(input.path) ?? [];
@@ -778,16 +814,12 @@ function getBacklinks(ctx2, input) {
 }
 
 // src/tools/get_links.ts
-import { join as join5 } from "path";
 import { z as z7 } from "zod";
 var GetLinksInput = z7.object({
   path: z7.string().describe("Vault-relative path to the note.")
 });
 function getLinks(ctx2, input) {
-  const absPath = join5(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  resolveVaultPath(ctx2.vaultRoot, input.path);
   const note = ctx2.notes.get(input.path);
   if (note === void 0) throw new Error(`Note not found: ${input.path}`);
   const rawLinks = extractLinksWithLines(note.raw);
@@ -872,7 +904,7 @@ function listTags(ctx2, input) {
 
 // src/tools/move_note.ts
 import { access as access3, mkdir as mkdir3, rename as rename3 } from "fs/promises";
-import { dirname as dirname2, join as join6 } from "path";
+import { dirname as dirname2, join as join2 } from "path";
 import { z as z10 } from "zod";
 
 // src/tools/rewrite_links.ts
@@ -880,6 +912,16 @@ import { posix } from "path";
 var WIKI_RE = /(!?)\[\[([^\]|#\n]{1,512})(#[^\]|\n]{1,512})?(\|[^\]\n]{1,512})?\]\]/g;
 var MD_RE = /(!?)\[([^\]\n]*)\]\(([^)\n]+)\)/g;
 var FENCE_RE = /^\s*(```|~~~)/;
+function mapUnfencedLines(raw, fn) {
+  let inFence = false;
+  return raw.split("\n").map((line) => {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      return line;
+    }
+    return inFence ? line : fn(line);
+  }).join("\n");
+}
 function wikiTargetFor(newPath, postNotes) {
   const noExt = newPath.replace(/\.md$/i, "");
   const base = noExt.split("/").pop() ?? noExt;
@@ -939,16 +981,8 @@ function rewriteNoteLinks(raw, sourcePath, oldPath, newPath, preNotes, postNotes
     const target = needsWrap ? `<${next}${fragment}>` : `${next}${fragment}`;
     return `${bang}[${text}](${target})`;
   });
-  let inFence = false;
-  const lines = raw.split("\n").map((line) => {
-    if (FENCE_RE.test(line)) {
-      inFence = !inFence;
-      return line;
-    }
-    if (inFence) return line;
-    return rewriteMdLine(rewriteWikiLine(line));
-  });
-  return { content: lines.join("\n"), count };
+  const content = mapUnfencedLines(raw, (line) => rewriteMdLine(rewriteWikiLine(line)));
+  return { content, count };
 }
 function hasMarkdownLinkTo(raw, sourcePath, targetPath) {
   if (!raw.includes("](")) return false;
@@ -976,10 +1010,8 @@ var MoveNoteInput = z10.object({
 });
 async function moveNote(ctx2, rawInput) {
   const input = MoveNoteInput.parse(rawInput);
-  const absFrom = join6(ctx2.vaultRoot, input.from);
-  const absTo = join6(ctx2.vaultRoot, input.to);
-  if (!absFrom.startsWith(ctx2.vaultRoot)) throw new Error(`Path outside vault: ${input.from}`);
-  if (!absTo.startsWith(ctx2.vaultRoot)) throw new Error(`Path outside vault: ${input.to}`);
+  const absFrom = resolveVaultPath(ctx2.vaultRoot, input.from);
+  const absTo = resolveVaultPath(ctx2.vaultRoot, input.to);
   assertWritable(ctx2.policy, input.from);
   assertWritable(ctx2.policy, input.to);
   try {
@@ -1037,7 +1069,7 @@ async function moveNote(ctx2, rawInput) {
     );
     removeNoteBacklinks(ctx2, path2);
     if (count > 0) {
-      await atomicWrite(join6(ctx2.vaultRoot, path2), content);
+      await atomicWrite(join2(ctx2.vaultRoot, path2), content);
       upsertDoc(ctx2, buildDoc(path2, content));
       notesRewritten++;
       linksRewritten += count;
@@ -1054,7 +1086,6 @@ async function moveNote(ctx2, rawInput) {
 
 // src/tools/outline_note.ts
 import { readFile as readFile3 } from "fs/promises";
-import { join as join7 } from "path";
 
 // ../core/src/outline.ts
 var HEADING_RE = /^(#{1,6})\s+(.+)/;
@@ -1111,10 +1142,7 @@ var OutlineNoteInput = z11.object({
   includeSizes: z11.boolean().default(false).describe("Include per-section character length in each heading entry. Default false.")
 });
 async function outlineNote(ctx2, input) {
-  const absPath = join7(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   const raw = await readFile3(absPath, "utf8");
   return buildOutline(raw, {
     includeBlocks: input.includeBlocks,
@@ -1124,8 +1152,7 @@ async function outlineNote(ctx2, input) {
 
 // src/tools/patch_frontmatter.ts
 import { readFile as readFile4 } from "fs/promises";
-import { join as join8 } from "path";
-import { parseDocument } from "yaml";
+import { parseDocument as parseDocument2 } from "yaml";
 import { z as z12 } from "zod";
 var PatchFrontmatterInput = z12.object({
   path: z12.string().describe("Vault-relative path to the note."),
@@ -1137,10 +1164,7 @@ var PatchFrontmatterInput = z12.object({
   )
 });
 async function patchFrontmatter(ctx2, input) {
-  const absPath = join8(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   assertWritable(ctx2.policy, input.path);
   const original = await readFile4(absPath, "utf8");
   if (input.prevHash !== void 0) assertHashMatch(original, input.prevHash, input.path);
@@ -1150,7 +1174,7 @@ async function patchFrontmatter(ctx2, input) {
   const keysRemoved = [];
   let newContent;
   if (!fm.present) {
-    const doc = parseDocument("");
+    const doc = parseDocument2("");
     for (const [k, v] of Object.entries(input.patch)) {
       if (v !== null) {
         doc.set(k, v);
@@ -1165,7 +1189,7 @@ ${original}`;
     const openLen = opensWithCRLF ? 5 : 4;
     const closeLen = opensWithCRLF ? 7 : 5;
     const yamlText = original.slice(openLen, fm.bodyStart - closeLen);
-    const doc = parseDocument(yamlText, { keepSourceTokens: true });
+    const doc = parseDocument2(yamlText, { keepSourceTokens: true });
     for (const [k, v] of Object.entries(input.patch)) {
       const existing = doc.has(k);
       if (v === null) {
@@ -1203,7 +1227,6 @@ ${original}`;
 
 // src/tools/patch_note.ts
 import { readFile as readFile5 } from "fs/promises";
-import { join as join9 } from "path";
 import { z as z13 } from "zod";
 var PatchNoteInput = z13.object({
   path: z13.string().describe("Vault-relative path to the note."),
@@ -1232,10 +1255,7 @@ function lineStart(raw, offset) {
   return prev === -1 ? 0 : prev + 1;
 }
 async function patchNote(ctx2, input) {
-  const absPath = join9(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   assertWritable(ctx2.policy, input.path);
   const raw = await readFile5(absPath, "utf8");
   if (input.prevHash !== void 0) assertHashMatch(raw, input.prevHash, input.path);
@@ -1250,15 +1270,15 @@ async function patchNote(ctx2, input) {
     const heading = outline.headings.find((h) => h.text.toLowerCase() === targetText.toLowerCase());
     if (!heading) {
       if (input.createIfMissing) {
-        const sep3 = raw.endsWith("\n\n") ? "" : raw.endsWith("\n") ? "\n" : "\n\n";
+        const sep4 = raw.endsWith("\n\n") ? "" : raw.endsWith("\n") ? "\n" : "\n\n";
         const contentNl = input.content.endsWith("\n") ? "" : "\n";
-        const newContent2 = `${raw}${sep3}## ${targetText}
+        const newContent2 = `${raw}${sep4}## ${targetText}
 
 ${input.content}${contentNl}`;
         await atomicWrite(absPath, newContent2);
         await verifyFrontmatter(absPath, originalFmRegion);
         updateCache(ctx2, input.path, newContent2, fm.bodyStart);
-        const headingOffset = raw.length + sep3.length;
+        const headingOffset = raw.length + sep4.length;
         return {
           path: input.path,
           bytesWritten: Buffer.byteLength(newContent2, "utf8"),
@@ -1307,8 +1327,8 @@ ${input.content}${contentNl}`;
   let newContent;
   switch (input.operation) {
     case "prepend": {
-      const sep3 = input.content.endsWith("\n") ? "" : "\n";
-      newContent = `${before}${input.content}${sep3}${section}${after}`;
+      const sep4 = input.content.endsWith("\n") ? "" : "\n";
+      newContent = `${before}${input.content}${sep4}${section}${after}`;
       break;
     }
     case "append": {
@@ -1353,7 +1373,7 @@ function updateCache(ctx2, path2, newContent, bodyStart) {
 
 // src/tools/periodic_note.ts
 import { access as access4, mkdir as mkdir4, readFile as readFile6 } from "fs/promises";
-import { dirname as dirname3, join as join10 } from "path";
+import { dirname as dirname3, join as join3 } from "path";
 import { z as z14 } from "zod";
 var PERIOD = z14.enum(["daily", "weekly", "monthly", "quarterly", "yearly"]);
 var DEFAULTS = {
@@ -1373,7 +1393,7 @@ async function readJson(absPath) {
 async function resolveConfig(vaultRoot2, period) {
   const defaults = DEFAULTS[period];
   if (period === "daily") {
-    const cfg2 = await readJson(join10(vaultRoot2, ".obsidian", "daily-notes.json"));
+    const cfg2 = await readJson(join3(vaultRoot2, ".obsidian", "daily-notes.json"));
     return {
       folder: cfg2?.folder ?? defaults.folder,
       format: cfg2?.format ?? defaults.format,
@@ -1381,7 +1401,7 @@ async function resolveConfig(vaultRoot2, period) {
     };
   }
   const cfg = await readJson(
-    join10(vaultRoot2, ".obsidian", "plugins", "periodic-notes", "data.json")
+    join3(vaultRoot2, ".obsidian", "plugins", "periodic-notes", "data.json")
   );
   const entry = cfg?.[period];
   return {
@@ -1434,8 +1454,7 @@ async function getPeriodicNote(ctx2, rawInput) {
   const date = input.date ? new Date(input.date) : /* @__PURE__ */ new Date();
   const cfg = await resolveConfig(ctx2.vaultRoot, input.period);
   const path2 = resolveNotePath(cfg, date);
-  const abs = join10(ctx2.vaultRoot, path2);
-  if (!abs.startsWith(ctx2.vaultRoot)) throw new Error(`Path outside vault: ${path2}`);
+  const abs = resolveVaultPath(ctx2.vaultRoot, path2);
   let existed = false;
   try {
     await access4(abs);
@@ -1447,15 +1466,13 @@ async function getPeriodicNote(ctx2, rawInput) {
   assertWritable(ctx2.policy, path2);
   let body = "";
   if (cfg.template) {
-    const templateAbs = join10(
-      ctx2.vaultRoot,
-      cfg.template.endsWith(".md") ? cfg.template : `${cfg.template}.md`
-    );
-    if (templateAbs.startsWith(ctx2.vaultRoot)) {
-      try {
-        body = await readFile6(templateAbs, "utf8");
-      } catch {
-      }
+    try {
+      const templateAbs = resolveVaultPath(
+        ctx2.vaultRoot,
+        cfg.template.endsWith(".md") ? cfg.template : `${cfg.template}.md`
+      );
+      body = await readFile6(templateAbs, "utf8");
+    } catch {
     }
   }
   await mkdir4(dirname3(abs), { recursive: true });
@@ -1477,8 +1494,7 @@ async function appendPeriodicNote(ctx2, rawInput) {
   const date = input.date ? new Date(input.date) : /* @__PURE__ */ new Date();
   const cfg = await resolveConfig(ctx2.vaultRoot, input.period);
   const path2 = resolveNotePath(cfg, date);
-  const abs = join10(ctx2.vaultRoot, path2);
-  if (!abs.startsWith(ctx2.vaultRoot)) throw new Error(`Path outside vault: ${path2}`);
+  const abs = resolveVaultPath(ctx2.vaultRoot, path2);
   assertWritable(ctx2.policy, path2);
   let original = "";
   try {
@@ -1656,7 +1672,6 @@ function queryNotes(ctx2, input) {
 
 // src/tools/read_note.ts
 import { readFile as readFile7 } from "fs/promises";
-import { join as join11 } from "path";
 import { z as z16 } from "zod";
 var ReadNoteInput = z16.object({
   path: z16.string().describe('Vault-relative path to the note, e.g. "Daily Notes/2026-05-29.md".'),
@@ -1673,10 +1688,7 @@ var ReadNoteInput = z16.object({
   message: "At most one of section, block, or lines may be specified."
 });
 async function readNote(ctx2, input) {
-  const absPath = join11(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   const raw = await readFile7(absPath, "utf8");
   const noteBytes = Buffer.byteLength(raw, "utf8");
   const hash = contentHash(raw);
@@ -1764,20 +1776,142 @@ async function readNote(ctx2, input) {
   };
 }
 
-// src/tools/replace_in_note.ts
+// src/tools/rename_heading.ts
 import { readFile as readFile8 } from "fs/promises";
-import { join as join12 } from "path";
+import { join as join4 } from "path";
 import { z as z17 } from "zod";
-var ReplaceInNoteInput = z17.object({
-  path: z17.string().describe("Vault-relative path to the note."),
-  find: z17.string().min(1).max(1e3).describe("Text or pattern to find (max 1000 chars; bounds regex-mode pattern size)."),
-  replace: z17.string().describe("Replacement text. Supports $1, $2, \u2026 backreferences in regex mode."),
-  regex: z17.boolean().default(false).describe("Treat find as a regular expression."),
-  caseSensitive: z17.boolean().default(false).describe("Case-sensitive matching."),
-  wholeWord: z17.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
-  limit: z17.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
-  dryRun: z17.boolean().default(false).describe("If true, report matches without writing anything."),
+var RenameHeadingInput = z17.object({
+  path: z17.string().describe("Vault-relative path of the note containing the heading."),
+  oldHeading: z17.string().min(1).describe(
+    "Current heading text, without # markers. Matched case-insensitively; if the note has duplicate headings the first one wins, mirroring Obsidian link resolution."
+  ),
+  newHeading: z17.string().min(1).refine((s) => !/[\n[\]|#]/.test(s), {
+    message: 'newHeading must not contain newlines, "[", "]", "|", or "#" \u2014 those break [[note#heading]] link syntax.'
+  }).describe("New heading text, without # markers."),
   prevHash: z17.string().optional().describe(
+    "Optional compare-and-swap guard: the contentHash from a prior read of this note. Fails with hash_conflict if the note changed since."
+  )
+});
+var HEADING_LINK_RE = /(!?)\[\[([^\]|#\n]{0,512})(#[^\]|\n]{1,512})(\|[^\]\n]{1,512})?\]\]/g;
+function rewriteHeadingLinks(raw, oldHeading, newHeading, matchesTarget) {
+  const oldLower = oldHeading.toLowerCase();
+  let count = 0;
+  const content = mapUnfencedLines(
+    raw,
+    (line) => line.replace(
+      HEADING_LINK_RE,
+      (full, bang, target, frag, alias) => {
+        const fragText = frag.slice(1);
+        if (fragText.startsWith("^") || fragText.includes("#")) return full;
+        if (fragText.trim().toLowerCase() !== oldLower) return full;
+        if (!matchesTarget(target.trim())) return full;
+        count++;
+        return `${bang}[[${target}#${newHeading}${alias ?? ""}]]`;
+      }
+    )
+  );
+  return { content, count };
+}
+async function renameHeading(ctx2, rawInput) {
+  const input = RenameHeadingInput.parse(rawInput);
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
+  assertWritable(ctx2.policy, input.path);
+  let raw;
+  try {
+    raw = await readFile8(absPath, "utf8");
+  } catch {
+    throw new Error(`Note not found: ${input.path}`);
+  }
+  if (input.prevHash !== void 0) assertHashMatch(raw, input.prevHash, input.path);
+  const outline = buildOutline(raw, { includeBlocks: false });
+  const heading = outline.headings.find(
+    (h) => h.text.toLowerCase() === input.oldHeading.toLowerCase()
+  );
+  if (!heading) {
+    throw new Error(
+      JSON.stringify({
+        error: "heading_not_found",
+        target: input.oldHeading,
+        available: outline.headings.map((h) => h.text)
+      })
+    );
+  }
+  const nl = raw.indexOf("\n", heading.byteOffset);
+  const lineEnd2 = nl === -1 ? raw.length : nl;
+  const lineText = raw.slice(heading.byteOffset, lineEnd2);
+  const markerPrefix = /^#{1,6}\s+/.exec(lineText)?.[0] ?? "";
+  const trailing = /\s*$/.exec(lineText)?.[0] ?? "";
+  const newLineText = `${markerPrefix}${input.newHeading}${trailing}`;
+  let newRaw = raw.slice(0, heading.byteOffset) + newLineText + raw.slice(lineEnd2);
+  const fm = parseFrontmatter(newRaw);
+  const bodyRegion = newRaw.slice(fm.bodyStart);
+  const selfRewrite = rewriteHeadingLinks(
+    bodyRegion,
+    input.oldHeading,
+    input.newHeading,
+    (target) => target === "" || resolveLink(target, ctx2.notes) === input.path
+  );
+  newRaw = newRaw.slice(0, fm.bodyStart) + selfRewrite.content;
+  const originalFmRegion = raw.slice(0, fm.bodyStart);
+  await atomicWrite(absPath, newRaw);
+  const written = await readFile8(absPath, "utf8");
+  if (written.slice(0, originalFmRegion.length) !== originalFmRegion) {
+    throw new Error("Write-safety violation: frontmatter region changed unexpectedly");
+  }
+  removeNoteBacklinks(ctx2, input.path);
+  upsertDoc(ctx2, buildDoc(input.path, newRaw));
+  addNoteBacklinks(ctx2, input.path, newRaw);
+  let notesRewritten = selfRewrite.count > 0 ? 1 : 0;
+  let linksRewritten = selfRewrite.count;
+  const skipped = [];
+  const candidates = /* @__PURE__ */ new Set();
+  for (const ref of ctx2.backlinks.get(input.path) ?? []) candidates.add(ref.path);
+  candidates.delete(input.path);
+  for (const path2 of [...candidates].sort()) {
+    const doc = ctx2.notes.get(path2);
+    if (doc === void 0) continue;
+    const { content, count } = rewriteHeadingLinks(
+      doc.raw,
+      input.oldHeading,
+      input.newHeading,
+      (target) => target !== "" && resolveLink(target, ctx2.notes) === input.path
+    );
+    if (count === 0) continue;
+    if (!isWritable(ctx2.policy, path2)) {
+      skipped.push(path2);
+      continue;
+    }
+    await atomicWrite(join4(ctx2.vaultRoot, path2), content);
+    upsertDoc(ctx2, buildDoc(path2, content));
+    notesRewritten++;
+    linksRewritten += count;
+  }
+  const result = {
+    path: input.path,
+    oldHeading: input.oldHeading,
+    newHeading: input.newHeading,
+    line: heading.line,
+    notesRewritten,
+    linksRewritten,
+    contentHash: contentHash(newRaw)
+  };
+  if (skipped.length > 0) result.skipped = skipped;
+  return result;
+}
+
+// src/tools/replace_in_note.ts
+import { readFile as readFile9 } from "fs/promises";
+import { z as z18 } from "zod";
+var ReplaceInNoteInput = z18.object({
+  path: z18.string().describe("Vault-relative path to the note."),
+  find: z18.string().min(1).max(1e3).describe("Text or pattern to find (max 1000 chars; bounds regex-mode pattern size)."),
+  replace: z18.string().describe("Replacement text. Supports $1, $2, \u2026 backreferences in regex mode."),
+  regex: z18.boolean().default(false).describe("Treat find as a regular expression."),
+  caseSensitive: z18.boolean().default(false).describe("Case-sensitive matching."),
+  wholeWord: z18.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
+  limit: z18.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
+  dryRun: z18.boolean().default(false).describe("If true, report matches without writing anything."),
+  prevHash: z18.string().optional().describe(
     "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
   )
 });
@@ -1791,10 +1925,7 @@ function buildRegex(find, opts) {
   return new RegExp(pattern, flags);
 }
 async function replaceInNote(ctx2, input) {
-  const absPath = join12(ctx2.vaultRoot, input.path);
-  if (!absPath.startsWith(ctx2.vaultRoot)) {
-    throw new Error(`Path outside vault: ${input.path}`);
-  }
+  const absPath = resolveVaultPath(ctx2.vaultRoot, input.path);
   assertWritable(ctx2.policy, input.path);
   let re;
   try {
@@ -1806,7 +1937,7 @@ async function replaceInNote(ctx2, input) {
   } catch (err) {
     throw new Error(`Invalid regex: ${err instanceof Error ? err.message : String(err)}`);
   }
-  const raw = await readFile8(absPath, "utf8");
+  const raw = await readFile9(absPath, "utf8");
   if (input.prevHash !== void 0) assertHashMatch(raw, input.prevHash, input.path);
   const fm = parseFrontmatter(raw);
   const originalFmRegion = raw.slice(0, fm.bodyStart);
@@ -1838,7 +1969,7 @@ async function replaceInNote(ctx2, input) {
   newBody += body.slice(lastIndex);
   const newContent = `${originalFmRegion}${newBody}`;
   await atomicWrite(absPath, newContent);
-  const written = await readFile8(absPath, "utf8");
+  const written = await readFile9(absPath, "utf8");
   if (written.slice(0, originalFmRegion.length) !== originalFmRegion) {
     throw new Error("Write-safety violation: frontmatter region changed unexpectedly");
   }
@@ -1863,6 +1994,7 @@ var WRITE_TOOLS = /* @__PURE__ */ new Set([
   "create_note",
   "delete_note",
   "move_note",
+  "rename_heading",
   "append_note",
   "patch_frontmatter",
   "patch_note",
@@ -2006,6 +2138,15 @@ async function run(ctx2, name, args) {
       }
       return { content: [{ type: "text", text }] };
     }
+    case "rename_heading": {
+      const input = RenameHeadingInput.parse(args);
+      const result = await renameHeading(ctx2, input);
+      let text = `Renamed heading "${result.oldHeading}" \u2192 "${result.newHeading}" in ${result.path} (line ${result.line}). Rewrote ${result.linksRewritten} link${result.linksRewritten === 1 ? "" : "s"} in ${result.notesRewritten} note${result.notesRewritten === 1 ? "" : "s"}. contentHash: ${result.contentHash}`;
+      if (result.skipped?.length) {
+        text += ` Skipped (outside SEEKSTONE_WRITE_PATHS): ${result.skipped.join(", ")}.`;
+      }
+      return { content: [{ type: "text", text }] };
+    }
     case "append_note": {
       const input = AppendNoteInput.parse(args);
       const result = await appendNote(ctx2, input);
@@ -2071,12 +2212,12 @@ async function run(ctx2, name, args) {
 }
 
 // src/index/build.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { basename as basename3, extname as extname4 } from "path";
 
 // ../core/src/walk.ts
 import { stat } from "fs/promises";
-import { extname as extname3, join as join13, relative, sep } from "path";
+import { extname as extname3, join as join5, relative, sep as sep2 } from "path";
 import fg from "fast-glob";
 var IMAGE_EXTS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".heic"]);
 var VIDEO_EXTS = /* @__PURE__ */ new Set([".mp4", ".mov", ".webm", ".mkv", ".avi"]);
@@ -2118,7 +2259,7 @@ async function walkVault(vaultRoot2) {
     const stats = typeof m === "string" ? await stat(absPath) : m.stats;
     if (!stats) continue;
     const relPath = relative(vaultRoot2, absPath);
-    const topDir = relPath.split(sep)[0] ?? "";
+    const topDir = relPath.split(sep2)[0] ?? "";
     entries.push({
       absPath,
       relPath,
@@ -2153,7 +2294,7 @@ async function buildIndex(vaultRoot2) {
   await Promise.all(
     noteEntries.map(async (entry) => {
       try {
-        const raw = await readFile9(entry.absPath, "utf8");
+        const raw = await readFile10(entry.absPath, "utf8");
         const fm = parseFrontmatter(raw);
         const inlineTags = extractInlineTags(fm.body);
         const fmTags = frontmatterTags(fm.data);
@@ -2206,8 +2347,8 @@ function buildBacklinks(notes2) {
 
 // src/init.ts
 import { execFileSync } from "child_process";
-import { access as access5, copyFile, mkdir as mkdir5, readdir, readFile as readFile10, stat as stat2, writeFile as writeFile2 } from "fs/promises";
-import path, { dirname as dirname4, join as join14 } from "path";
+import { access as access5, copyFile, mkdir as mkdir5, readdir, readFile as readFile11, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import path, { dirname as dirname4, join as join6 } from "path";
 function parseInitArgs(argv) {
   const opts = { write: false, client: "desktop" };
   for (let i = 0; i < argv.length; i++) {
@@ -2250,7 +2391,7 @@ function cursorConfigPath(platform, env) {
   return j(env.home ?? "", ".cursor", "mcp.json");
 }
 function vscodeMcpConfigPath(cwd) {
-  return join14(cwd, ".vscode", "mcp.json");
+  return join6(cwd, ".vscode", "mcp.json");
 }
 function obsidianRegistryPath(platform, env) {
   if (platform === "win32") {
@@ -2312,7 +2453,7 @@ async function validateVault(vaultPath) {
     return { ok: false, error: `Path does not exist: ${vaultPath}` };
   }
   try {
-    await access5(join14(vaultPath, ".obsidian"));
+    await access5(join6(vaultPath, ".obsidian"));
   } catch {
     return {
       ok: false,
@@ -2332,7 +2473,7 @@ async function countMarkdown(root) {
     }
     for (const e of entries) {
       if (e.name.startsWith(".")) continue;
-      const full = join14(dir, e.name);
+      const full = join6(dir, e.name);
       if (e.isDirectory()) await walk(full);
       else if (e.name.endsWith(".md")) count++;
     }
@@ -2350,7 +2491,7 @@ async function runInit(opts, deps) {
       ]
     };
   }
-  const rf = deps.readFile ?? readFile10;
+  const rf = deps.readFile ?? readFile11;
   let vaultPath = opts.vault ?? deps.env.SEEKSTONE_VAULT;
   if (!vaultPath) {
     const registryPath = obsidianRegistryPath(deps.platform, {
@@ -2835,6 +2976,32 @@ var ALL_TOOLS = [
       required: ["from", "to"]
     }
   },
+  {
+    name: "rename_heading",
+    description: "Rename a heading in a note and rewrite every [[note#heading]] wikilink and embed across the vault so references keep working \u2014 aliases preserved, fenced code blocks left alone. Served from the warm backlink index, no vault scan. Heading matching is case-insensitive; with duplicate headings the first match wins, mirroring Obsidian link resolution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Vault-relative path of the note containing the heading."
+        },
+        oldHeading: {
+          type: "string",
+          description: "Current heading text, without # markers. Case-insensitive; first match wins."
+        },
+        newHeading: {
+          type: "string",
+          description: 'New heading text, without # markers. Must not contain newlines, "[", "]", "|", or "#".'
+        },
+        prevHash: {
+          type: "string",
+          description: "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
+        }
+      },
+      required: ["path", "oldHeading", "newHeading"]
+    }
+  },
   {
     name: "append_note",
     description: "Append text to a note body without touching the frontmatter. Safe for meeting notes, daily logs, and append-only workflows.",
@@ -3051,8 +3218,8 @@ function visibleTools(policy2) {
 
 // src/watcher.ts
 import { realpathSync } from "fs";
-import { readFile as readFile11 } from "fs/promises";
-import { join as join15, relative as relative2, sep as sep2 } from "path";
+import { readFile as readFile12 } from "fs/promises";
+import { join as join7, relative as relative2, sep as sep3 } from "path";
 import chokidar from "chokidar";
 function startWatcher(ctx2, log2, opts) {
   const usePolling = opts?.usePolling ?? process.env.SEEKSTONE_WATCH_POLL === "1";
@@ -3061,10 +3228,10 @@ function startWatcher(ctx2, log2, opts) {
     vaultRoot2 = realpathSync(ctx2.vaultRoot);
   } catch {
   }
-  const toRel = (abs) => relative2(vaultRoot2, abs).split(sep2).join("/");
+  const toRel = (abs) => relative2(vaultRoot2, abs).split(sep3).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile11(join15(vaultRoot2, relPath), "utf8");
+      const raw = await readFile12(join7(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
@@ -3096,7 +3263,7 @@ function startWatcher(ctx2, log2, opts) {
     ignored: (p) => {
       const rel = relative2(vaultRoot2, p);
       if (!rel || rel === ".") return false;
-      return rel.split(sep2).filter(Boolean).some((seg) => seg.startsWith(".") && seg !== "..");
+      return rel.split(sep3).filter(Boolean).some((seg) => seg.startsWith(".") && seg !== "..");
     }
   });
   watcher2.on("add", onUpsert("add")).on("change", onUpsert("change")).on("unlink", (abs) => {
@@ -3104,9 +3271,9 @@ function startWatcher(ctx2, log2, opts) {
     opts?.onRawEvent?.("unlink", abs, relPath);
     if (relPath.endsWith(".md")) remove(relPath);
   });
-  const ready = new Promise((resolve) => {
+  const ready = new Promise((resolve3) => {
     watcher2.once("ready", () => {
-      resolve();
+      resolve3();
     });
   });
   return {
@@ -3116,7 +3283,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.12.1" : "0.0.0-dev";
+var VERSION = true ? "0.13.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -3146,11 +3313,12 @@ if (intent === "init") {
 }
 var log = createLogger();
 installProcessGuards(log);
-var vaultRoot = process.env.SEEKSTONE_VAULT;
-if (!vaultRoot) {
+var rawVaultRoot = process.env.SEEKSTONE_VAULT;
+if (!rawVaultRoot) {
   log.error("SEEKSTONE_VAULT env var is required");
   process.exit(1);
 }
+var vaultRoot = resolve2(rawVaultRoot);
 var policy = parseWritePolicy(process.env);
 if (policy.readOnly) log.info("read-only mode", { env: "SEEKSTONE_READ_ONLY" });
 if (policy.writeGlobs) log.info("write paths scoped", { globs: policy.writeGlobs });