seekstone 0.12.2 → 0.13.1

package/README.md

@@ -104,7 +104,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 
 ## Tools
 
-18 tools: 10 read, 8 write.
+19 tools: 10 read, 9 write.
 
 ### Read
 
@@ -128,6 +128,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 | `create_note` | Create a note (optional frontmatter + body); parent dirs created automatically. Never clobbers an existing note unless you pass `overwrite: true`. |
 | `delete_note` | Move a note to the vault's `.trash/` folder (Obsidian-compatible, restorable). Pass `permanent: true` for an unrecoverable delete. |
 | `move_note` | Move/rename a note — wikilinks and markdown links in other notes that point at it are rewritten so nothing breaks; destination dirs created automatically. |
+| `rename_heading` | Rename a heading in a note — every `[[note#heading]]` wikilink and embed across the vault is rewritten so references keep working (aliases preserved, fenced code blocks left alone). |
 | `append_note` | Append to a note body without touching frontmatter. |
 | `patch_frontmatter` | Set/update/delete frontmatter keys without reordering existing keys or changing quote style. |
 | `patch_note` | Insert text immediately after a heading without touching frontmatter. |
@@ -147,7 +148,7 @@ The content-editing tools (`append_note`, `patch_note`, `patch_frontmatter`, `re
 | `SEEKSTONE_LOG_FILE` | no | Absolute path; when set, JSON-line logs are appended here (size-rotated). |
 | `SEEKSTONE_WATCH_POLL` | no | Set to `1` to stat-poll for changes instead of native OS events — reliable on network drives, WSL, containers. |
 | `SEEKSTONE_LOG_MAX_SIZE` | no | Log-rotation threshold for `SEEKSTONE_LOG_FILE` (e.g. `10mb`; default 5 MB). |
-| `SEEKSTONE_READ_ONLY` | no | Set to `1` to run read-only: the 8 write tools are unregistered entirely (and rejected if called anyway), so the session provably cannot modify your vault. |
+| `SEEKSTONE_READ_ONLY` | no | Set to `1` to run read-only: the 9 write tools are unregistered entirely (and rejected if called anyway), so the session provably cannot modify your vault. |
 | `SEEKSTONE_WRITE_PATHS` | no | Comma-separated vault-relative globs (e.g. `journal/**,inbox/*.md`). Writes are permitted only under matching paths; the rest of the vault stays read-only. |
 
 ---

package/dist/index.js

@@ -246,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 = [];
@@ -873,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;
@@ -932,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;
@@ -1111,7 +1152,7 @@ async function outlineNote(ctx2, input) {
 
 // src/tools/patch_frontmatter.ts
 import { readFile as readFile4 } from "fs/promises";
-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."),
@@ -1133,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);
@@ -1148,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) {
@@ -1735,19 +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 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."
   )
 });
@@ -1773,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);
@@ -1805,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");
   }
@@ -1830,6 +1994,7 @@ var WRITE_TOOLS = /* @__PURE__ */ new Set([
   "create_note",
   "delete_note",
   "move_note",
+  "rename_heading",
   "append_note",
   "patch_frontmatter",
   "patch_note",
@@ -1973,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);
@@ -2038,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 join4, relative, sep as sep2 } 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"]);
@@ -2120,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);
@@ -2173,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 join5 } 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++) {
@@ -2217,7 +2391,7 @@ function cursorConfigPath(platform, env) {
   return j(env.home ?? "", ".cursor", "mcp.json");
 }
 function vscodeMcpConfigPath(cwd) {
-  return join5(cwd, ".vscode", "mcp.json");
+  return join6(cwd, ".vscode", "mcp.json");
 }
 function obsidianRegistryPath(platform, env) {
   if (platform === "win32") {
@@ -2279,7 +2453,7 @@ async function validateVault(vaultPath) {
     return { ok: false, error: `Path does not exist: ${vaultPath}` };
   }
   try {
-    await access5(join5(vaultPath, ".obsidian"));
+    await access5(join6(vaultPath, ".obsidian"));
   } catch {
     return {
       ok: false,
@@ -2299,7 +2473,7 @@ async function countMarkdown(root) {
     }
     for (const e of entries) {
       if (e.name.startsWith(".")) continue;
-      const full = join5(dir, e.name);
+      const full = join6(dir, e.name);
       if (e.isDirectory()) await walk(full);
       else if (e.name.endsWith(".md")) count++;
     }
@@ -2317,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, {
@@ -2578,9 +2752,32 @@ function installProcessGuards(log2) {
 }
 
 // src/tool-list.ts
+var READ_ONLY_ANNOTATIONS = {
+  readOnlyHint: true,
+  openWorldHint: false
+};
+var ADDITIVE_WRITE_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var DESTRUCTIVE_WRITE_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var IDEMPOTENT_DESTRUCTIVE_WRITE_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,
+  openWorldHint: false
+};
 var ALL_TOOLS = [
   {
     name: "search",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "Full-text search across the vault. Returns ranked excerpts (~200 chars) \u2014 not full notes \u2014 to minimise context usage. Supports fuzzy matching and prefix search.",
     inputSchema: {
       type: "object",
@@ -2595,6 +2792,7 @@ var ALL_TOOLS = [
   },
   {
     name: "query_notes",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "Structured metadata query \u2014 filter notes by frontmatter key/value predicates, tag, folder, modified time, and size. Returns compact rows (path + title by default; opt into more via select), not note content. Use this instead of search when filtering by properties rather than text.",
     inputSchema: {
       type: "object",
@@ -2652,6 +2850,7 @@ var ALL_TOOLS = [
   },
   {
     name: "context_pack",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: 'Assemble everything needed to ANSWER a natural-language question in one call, under a strict byte budget (default 2048): ranked excerpts, linked neighbor notes (backlinks/outlinks) with one-line summaries, and follow-up source paths. Use search to locate notes and query_notes for metadata filters; use context_pack when you want answer-ready context without multiple round-trips. Empty excerpts with confidence "none" or "low" means the vault lacks coverage \u2014 do not infer content.',
     inputSchema: {
       type: "object",
@@ -2667,6 +2866,7 @@ var ALL_TOOLS = [
   },
   {
     name: "read_note",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "Read a note or a span of it \u2014 by heading section, block reference, or line range. Returns structured JSON with the content, bytes returned, total note size, and a contentHash to pass as prevHash to edit tools for compare-and-swap. Use search or outline_note first to find the right path and section names.",
     inputSchema: {
       type: "object",
@@ -2705,6 +2905,7 @@ var ALL_TOOLS = [
   },
   {
     name: "list_notes",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "List notes, optionally filtered by folder prefix or tag.",
     inputSchema: {
       type: "object",
@@ -2718,6 +2919,7 @@ var ALL_TOOLS = [
   },
   {
     name: "list_tags",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "List all tags in the vault with usage counts. Supports substring filtering, minimum count threshold, and sort order. Nested tags (e.g. area/work) include a parent field.",
     inputSchema: {
       type: "object",
@@ -2741,6 +2943,7 @@ var ALL_TOOLS = [
   },
   {
     name: "create_note",
+    annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
     description: "Create a new note at a vault-relative path. Optionally sets frontmatter and body content. Parent directories are created automatically. Fails if the note already exists unless overwrite is true (prevHash may guard the overwrite).",
     inputSchema: {
       type: "object",
@@ -2769,6 +2972,7 @@ var ALL_TOOLS = [
   },
   {
     name: "delete_note",
+    annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
     description: "Delete a note. By default it is moved to the vault .trash/ folder (recoverable by moving it back); pass permanent: true to remove it outright.",
     inputSchema: {
       type: "object",
@@ -2784,6 +2988,7 @@ var ALL_TOOLS = [
   },
   {
     name: "move_note",
+    annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
     description: "Move or rename a note to a new vault-relative path, rewriting wikilinks and markdown links in other notes that point at it so nothing breaks (links inside fenced code blocks are left alone). Parent directories at the destination are created automatically. Fails if the destination already exists unless overwrite is true.",
     inputSchema: {
       type: "object",
@@ -2802,8 +3007,36 @@ var ALL_TOOLS = [
       required: ["from", "to"]
     }
   },
+  {
+    name: "rename_heading",
+    annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
+    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",
+    annotations: ADDITIVE_WRITE_ANNOTATIONS,
     description: "Append text to a note body without touching the frontmatter. Safe for meeting notes, daily logs, and append-only workflows.",
     inputSchema: {
       type: "object",
@@ -2820,6 +3053,7 @@ var ALL_TOOLS = [
   },
   {
     name: "patch_frontmatter",
+    annotations: IDEMPOTENT_DESTRUCTIVE_WRITE_ANNOTATIONS,
     description: "Set, update, or delete frontmatter keys without reordering existing keys or changing quote style. Pass null as a value to delete a key.",
     inputSchema: {
       type: "object",
@@ -2840,6 +3074,7 @@ var ALL_TOOLS = [
   },
   {
     name: "outline_note",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "Return a note's structure \u2014 heading tree with offsets, block-reference anchors, and frontmatter key list \u2014 without returning any prose. Use this before section reads or patches to discover what sections exist at a fraction of the cost of reading the full note.",
     inputSchema: {
       type: "object",
@@ -2859,6 +3094,7 @@ var ALL_TOOLS = [
   },
   {
     name: "patch_note",
+    annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
     description: "Surgically edit a section of a note \u2014 targeted by heading or block reference \u2014 without rewriting the whole file. Operations: append (add after section), prepend (add after heading line), replace (swap section content). Frontmatter is never touched.",
     inputSchema: {
       type: "object",
@@ -2888,6 +3124,7 @@ var ALL_TOOLS = [
   },
   {
     name: "get_backlinks",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "Return every note that links to the target note, with the source line and an optional excerpt. Results come from the pre-built reverse-link index so this is a fast, pure index lookup. Sort order: source path ascending.",
     inputSchema: {
       type: "object",
@@ -2907,6 +3144,7 @@ var ALL_TOOLS = [
   },
   {
     name: "get_links",
+    annotations: READ_ONLY_ANNOTATIONS,
     description: "Return all outgoing wikilinks and embeds from a note. Each link is marked resolved (with target path) or unresolved. Duplicate targets are de-duplicated; results sorted by line number.",
     inputSchema: {
       type: "object",
@@ -2918,6 +3156,7 @@ var ALL_TOOLS = [
   },
   {
     name: "replace_in_note",
+    annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
     description: "Find and replace text within a note body. Supports literal and regex search, case sensitivity, whole-word matching, and a replacement limit. Frontmatter is never touched. Use dryRun to preview matches before writing.",
     inputSchema: {
       type: "object",
@@ -2958,6 +3197,7 @@ var ALL_TOOLS = [
   },
   {
     name: "get_periodic_note",
+    annotations: ADDITIVE_WRITE_ANNOTATIONS,
     description: "Get the path and existence status of a periodic note (daily, weekly, monthly, quarterly, or yearly) for a given date. Reads folder/format config from .obsidian/daily-notes.json (daily) or the periodic-notes plugin data.json. Optionally creates the note from the configured template if it is missing.",
     inputSchema: {
       type: "object",
@@ -2981,6 +3221,7 @@ var ALL_TOOLS = [
   },
   {
     name: "append_periodic_note",
+    annotations: ADDITIVE_WRITE_ANNOTATIONS,
     description: "Append text to a periodic note (daily, weekly, monthly, quarterly, or yearly). Preserves existing frontmatter exactly. Creates the note first (from template if configured) when createIfMissing is true (default).",
     inputSchema: {
       type: "object",
@@ -3018,8 +3259,8 @@ function visibleTools(policy2) {
 
 // src/watcher.ts
 import { realpathSync } from "fs";
-import { readFile as readFile11 } from "fs/promises";
-import { join as join6, relative as relative2, sep as sep3 } 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";
@@ -3031,7 +3272,7 @@ function startWatcher(ctx2, log2, opts) {
   const toRel = (abs) => relative2(vaultRoot2, abs).split(sep3).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile11(join6(vaultRoot2, relPath), "utf8");
+      const raw = await readFile12(join7(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
@@ -3083,7 +3324,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.12.2" : "0.0.0-dev";
+var VERSION = true ? "0.13.1" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}