seekstone 0.2.1 → 0.4.0

package/dist/index.js

@@ -30,7 +30,7 @@ Usage:
   seekstone --help     Print this help and exit
 
 "seekstone init" options:
-  --vault <path>       Vault to use (default: $SEEKSTONE_VAULT)
+  --vault <path>       Vault to use (auto-detected from Obsidian if omitted; fallback: $SEEKSTONE_VAULT)
   --client <name>      desktop (default) | code
   --write              Patch the Claude Desktop config in place (backs it up first)
 
@@ -155,6 +155,25 @@ import { z as z2 } from "zod";
 import { basename, extname } from "path";
 
 // ../core/src/extract.ts
+var LINK_WITH_LINES_RE_SRC = /(!?\[\[)([^\]|#\n]+)(#[^\]|\n]+)?(\|[^\]\n]+)?(\]\])/.source;
+function extractLinksWithLines(raw) {
+  const out = [];
+  const lines = raw.split("\n");
+  for (const [lineIdx, lineText] of lines.entries()) {
+    for (const m of lineText.matchAll(new RegExp(LINK_WITH_LINES_RE_SRC, "g"))) {
+      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
+      });
+    }
+  }
+  return out;
+}
 var INLINE_TAG_RE = /(?:^|[^\w\]/])#([A-Za-z_][\w/-]*)/g;
 function extractInlineTags(body) {
   const out = [];
@@ -253,14 +272,102 @@ async function deleteNote(ctx2, input) {
   return { path: input.path };
 }
 
-// src/tools/list_notes.ts
+// src/tools/get_backlinks.ts
+import { join as join4 } from "path";
 import { z as z4 } from "zod";
-var ListNotesInput = z4.object({
-  folder: z4.string().optional().describe(
+var GetBacklinksInput = z4.object({
+  path: z4.string().describe("Vault-relative path to the target note."),
+  includeContext: z4.boolean().optional().describe("Include a short excerpt (~200 chars) from the linking line. Default true."),
+  limit: z4.number().int().min(1).max(500).optional().describe("Max backlinks to return. Default 50.")
+});
+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}`);
+  }
+  const includeContext = input.includeContext ?? true;
+  const limit = input.limit ?? 50;
+  const refs = ctx2.backlinks.get(input.path) ?? [];
+  const total = refs.length;
+  const limited = refs.slice(0, limit);
+  const backlinks2 = [];
+  for (const ref of limited) {
+    const entry = { path: ref.path, line: ref.line, linkType: ref.linkType };
+    if (includeContext) {
+      const srcNote = ctx2.notes.get(ref.path);
+      if (srcNote !== void 0) {
+        const rawLines = srcNote.raw.split("\n");
+        const lineText = rawLines[ref.line - 1];
+        if (lineText !== void 0) {
+          entry.excerpt = lineText.length > EXCERPT_MAX ? `${lineText.slice(0, EXCERPT_MAX)}\u2026` : lineText;
+        }
+      }
+    }
+    backlinks2.push(entry);
+  }
+  return { target: input.path, backlinks: backlinks2, total };
+}
+
+// src/tools/get_links.ts
+import { join as join5 } from "path";
+import { z as z5 } from "zod";
+
+// src/index/resolve.ts
+function resolveLink(target, notes2) {
+  if (notes2.has(target)) return target;
+  const withMd = `${target}.md`;
+  if (notes2.has(withMd)) return withMd;
+  const targetLower = target.toLowerCase();
+  const targetBase = (target.split("/").pop() ?? target).toLowerCase();
+  for (const path2 of notes2.keys()) {
+    const pathNoExt = path2.replace(/\.md$/i, "");
+    if (pathNoExt.toLowerCase() === targetLower) return path2;
+    const pathBase = (pathNoExt.split("/").pop() ?? pathNoExt).toLowerCase();
+    if (pathBase === targetBase) return path2;
+  }
+  return void 0;
+}
+
+// src/tools/get_links.ts
+var GetLinksInput = z5.object({
+  path: z5.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}`);
+  }
+  const note = ctx2.notes.get(input.path);
+  if (note === void 0) throw new Error(`Note not found: ${input.path}`);
+  const rawLinks = extractLinksWithLines(note.raw);
+  const seen = /* @__PURE__ */ new Set();
+  const links = [];
+  for (const link of rawLinks) {
+    if (seen.has(link.target)) continue;
+    seen.add(link.target);
+    const resolvedPath = resolveLink(link.target, ctx2.notes);
+    const entry = {
+      raw: link.raw,
+      resolved: resolvedPath !== void 0,
+      linkType: link.linkType,
+      line: link.line
+    };
+    if (resolvedPath !== void 0) entry.target = resolvedPath;
+    links.push(entry);
+  }
+  links.sort((a, b) => a.line - b.line);
+  return { path: input.path, links };
+}
+
+// src/tools/list_notes.ts
+import { z as z6 } from "zod";
+var ListNotesInput = z6.object({
+  folder: z6.string().optional().describe(
     'Vault-relative folder prefix to list. Omit for all notes. Example: "Daily Notes/2026".'
   ),
-  tag: z4.string().optional().describe("Filter by tag. Include or omit the leading #."),
-  limit: z4.number().int().min(1).max(500).default(100).describe("Maximum number of results.")
+  tag: z6.string().optional().describe("Filter by tag. Include or omit the leading #."),
+  limit: z6.number().int().min(1).max(500).default(100).describe("Maximum number of results.")
 });
 function listNotes(ctx2, input) {
   const tag = input.tag?.replace(/^#/, "");
@@ -282,18 +389,49 @@ function listNotes(ctx2, input) {
   return results.sort((a, b) => a.path.localeCompare(b.path));
 }
 
+// src/tools/list_tags.ts
+import { z as z7 } from "zod";
+var ListTagsInput = z7.object({
+  pattern: z7.string().optional().describe('Substring filter on tag name. Example: "work" matches "work" and "area/work".'),
+  minCount: z7.number().int().min(1).optional().describe("Only return tags used in at least this many notes."),
+  sort: z7.enum(["count", "name"]).default("count").describe("Sort by usage count descending (default) or alphabetically.")
+});
+function listTags(ctx2, input) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const note of ctx2.notes.values()) {
+    for (const tag of note.tags.split(" ").filter(Boolean)) {
+      counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+  }
+  const tags = [];
+  for (const [tag, count] of counts) {
+    if (input.pattern !== void 0 && !tag.includes(input.pattern)) continue;
+    if (input.minCount !== void 0 && count < input.minCount) continue;
+    const slashIdx = tag.lastIndexOf("/");
+    const entry = { tag, count };
+    if (slashIdx !== -1) entry.parent = tag.slice(0, slashIdx);
+    tags.push(entry);
+  }
+  if (input.sort === "name") {
+    tags.sort((a, b) => a.tag.localeCompare(b.tag));
+  } else {
+    tags.sort((a, b) => b.count - a.count || a.tag.localeCompare(b.tag));
+  }
+  return { tags, total: tags.length };
+}
+
 // src/tools/move_note.ts
 import { access as access2, mkdir as mkdir2, rename } from "fs/promises";
-import { dirname as dirname2, join as join4 } from "path";
-import { z as z5 } from "zod";
-var MoveNoteInput = z5.object({
-  from: z5.string().describe("Vault-relative path of the note to move."),
-  to: z5.string().describe("Vault-relative destination path."),
-  overwrite: z5.boolean().default(false).describe("Overwrite the destination if it exists. Defaults to false.")
+import { dirname as dirname2, join as join6 } from "path";
+import { z as z8 } from "zod";
+var MoveNoteInput = z8.object({
+  from: z8.string().describe("Vault-relative path of the note to move."),
+  to: z8.string().describe("Vault-relative destination path."),
+  overwrite: z8.boolean().default(false).describe("Overwrite the destination if it exists. Defaults to false.")
 });
 async function moveNote(ctx2, input) {
-  const absFrom = join4(ctx2.vaultRoot, input.from);
-  const absTo = join4(ctx2.vaultRoot, input.to);
+  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}`);
   try {
@@ -322,23 +460,93 @@ async function moveNote(ctx2, input) {
   return { from: input.from, to: input.to };
 }
 
+// src/tools/outline_note.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join7 } from "path";
+
+// ../core/src/outline.ts
+var HEADING_RE = /^(#{1,6})\s+(.+)/;
+var BLOCK_REF_RE = /\^([a-zA-Z0-9-]+)$/;
+function buildOutline(raw, options = {}) {
+  const { includeBlocks = true, includeSizes = false } = options;
+  const fm = parseFrontmatter(raw);
+  const totalBytes = Buffer.byteLength(raw, "utf8");
+  const headings = [];
+  const blocks = [];
+  let charOffset = 0;
+  for (const [i, line] of raw.split("\n").entries()) {
+    const lineCharOffset = charOffset;
+    const lineNum = i + 1;
+    if (charOffset >= fm.bodyStart) {
+      const hm = HEADING_RE.exec(line);
+      if (hm) {
+        headings.push({
+          text: (hm[2] ?? "").trim(),
+          level: (hm[1] ?? "").length,
+          line: lineNum,
+          byteOffset: lineCharOffset
+        });
+      }
+      if (includeBlocks) {
+        const trimmed = line.trimEnd();
+        const bm = BLOCK_REF_RE.exec(trimmed);
+        if (bm) {
+          const caretPos = trimmed.lastIndexOf("^");
+          blocks.push({
+            id: bm[1] ?? "",
+            line: lineNum,
+            byteOffset: lineCharOffset + caretPos
+          });
+        }
+      }
+    }
+    charOffset += line.length + 1;
+  }
+  if (includeSizes) {
+    for (const [i, heading] of headings.entries()) {
+      const next = headings[i + 1];
+      heading.byteLength = (next?.byteOffset ?? raw.length) - heading.byteOffset;
+    }
+  }
+  return { headings, blocks, frontmatterKeys: fm.keys, totalBytes };
+}
+
+// src/tools/outline_note.ts
+import { z as z9 } from "zod";
+var OutlineNoteInput = z9.object({
+  path: z9.string().describe("Vault-relative path to the note."),
+  includeBlocks: z9.boolean().default(true).describe("Include block-reference anchors (^id). Default true."),
+  includeSizes: z9.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 raw = await readFile2(absPath, "utf8");
+  return buildOutline(raw, {
+    includeBlocks: input.includeBlocks,
+    includeSizes: input.includeSizes
+  });
+}
+
 // src/tools/patch_frontmatter.ts
-import { readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
-import { join as join5 } from "path";
+import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { join as join8 } from "path";
 import { parseDocument } from "yaml";
-import { z as z6 } from "zod";
-var PatchFrontmatterInput = z6.object({
-  path: z6.string().describe("Vault-relative path to the note."),
-  patch: z6.record(z6.string(), z6.unknown()).describe(
+import { z as z10 } from "zod";
+var PatchFrontmatterInput = z10.object({
+  path: z10.string().describe("Vault-relative path to the note."),
+  patch: z10.record(z10.string(), z10.unknown()).describe(
     "Key-value pairs to set in the frontmatter. Existing keys not in the patch are unchanged. Pass null as a value to remove a key."
   )
 });
 async function patchFrontmatter(ctx2, input) {
-  const absPath = join5(ctx2.vaultRoot, input.path);
+  const absPath = join8(ctx2.vaultRoot, input.path);
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
-  const original = await readFile2(absPath, "utf8");
+  const original = await readFile3(absPath, "utf8");
   const fm = parseFrontmatter(original);
   const keysChanged = [];
   const keysAdded = [];
@@ -390,28 +598,258 @@ ${original}`;
   return { path: input.path, keysChanged, keysAdded, keysRemoved };
 }
 
+// src/tools/patch_note.ts
+import { readFile as readFile4, rename as rename2, writeFile as writeFile4 } from "fs/promises";
+import { join as join9 } from "path";
+import { z as z11 } from "zod";
+var PatchNoteInput = z11.object({
+  path: z11.string().describe("Vault-relative path to the note."),
+  target: z11.union([
+    z11.object({ heading: z11.string().describe("Heading text (without # markers).") }),
+    z11.object({ block: z11.string().describe("Block reference ID (without the ^ prefix).") })
+  ]).describe("Target section. Provide exactly one of heading or block."),
+  operation: z11.enum(["append", "prepend", "replace"]).describe(
+    "append: insert after section content. prepend: insert after heading line. replace: swap section content."
+  ),
+  content: z11.string().min(1).describe("Content to insert or replace with."),
+  createIfMissing: z11.boolean().default(false).describe(
+    "If the heading target is not found, append a new heading (level 2) + content. Only valid for heading targets."
+  )
+});
+function lineEnd(raw, offset) {
+  const nl = raw.indexOf("\n", offset);
+  return nl === -1 ? raw.length : nl + 1;
+}
+function lineStart(raw, offset) {
+  if (offset === 0) return 0;
+  const prev = raw.lastIndexOf("\n", offset - 1);
+  return prev === -1 ? 0 : prev + 1;
+}
+async function atomicWrite(absPath, content) {
+  const tmpPath = `${absPath}.seekstone-patch-tmp`;
+  await writeFile4(tmpPath, content, "utf8");
+  await rename2(tmpPath, absPath);
+}
+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 raw = await readFile4(absPath, "utf8");
+  const fm = parseFrontmatter(raw);
+  const originalFmRegion = raw.slice(0, fm.bodyStart);
+  const outline = buildOutline(raw, { includeBlocks: true });
+  let contentStart;
+  let contentEnd;
+  let resolvedAt;
+  if ("heading" in input.target) {
+    const targetText = input.target.heading;
+    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 contentNl = input.content.endsWith("\n") ? "" : "\n";
+        const newContent2 = `${raw}${sep3}## ${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;
+        return {
+          path: input.path,
+          bytesWritten: Buffer.byteLength(newContent2, "utf8"),
+          targetResolvedAt: {
+            line: newContent2.slice(0, headingOffset).split("\n").length,
+            byteOffset: headingOffset
+          },
+          frontmatterUnchanged: true
+        };
+      }
+      throw new Error(
+        JSON.stringify({
+          error: "heading_not_found",
+          target: targetText,
+          available: outline.headings.map((h) => h.text)
+        })
+      );
+    }
+    const headingLineEnd = lineEnd(raw, heading.byteOffset);
+    const nextSibling = outline.headings.find(
+      (h) => h.byteOffset > heading.byteOffset && h.level <= heading.level
+    );
+    contentStart = headingLineEnd;
+    contentEnd = nextSibling?.byteOffset ?? raw.length;
+    resolvedAt = { line: heading.line, byteOffset: heading.byteOffset };
+  } else {
+    const targetId = input.target.block;
+    const block = outline.blocks.find((b) => b.id === targetId);
+    if (!block) {
+      throw new Error(
+        JSON.stringify({
+          error: "block_not_found",
+          target: targetId,
+          available: outline.blocks.map((b) => b.id)
+        })
+      );
+    }
+    contentStart = lineStart(raw, block.byteOffset);
+    contentEnd = lineEnd(raw, block.byteOffset);
+    resolvedAt = { line: block.line, byteOffset: block.byteOffset };
+  }
+  const before = raw.slice(0, contentStart);
+  const section = raw.slice(contentStart, contentEnd);
+  const after = raw.slice(contentEnd);
+  let newContent;
+  switch (input.operation) {
+    case "prepend": {
+      const sep3 = input.content.endsWith("\n") ? "" : "\n";
+      newContent = `${before}${input.content}${sep3}${section}${after}`;
+      break;
+    }
+    case "append": {
+      const sectionNl = section.endsWith("\n") ? "" : "\n";
+      const contentNl = input.content.endsWith("\n") ? "" : "\n";
+      newContent = `${before}${section}${sectionNl}${input.content}${contentNl}${after}`;
+      break;
+    }
+    case "replace": {
+      const contentNl = input.content.endsWith("\n") ? "" : "\n";
+      newContent = `${before}${input.content}${contentNl}${after}`;
+      break;
+    }
+    default:
+      throw new Error(`Unknown operation: ${String(input.operation)}`);
+  }
+  await atomicWrite(absPath, newContent);
+  await verifyFrontmatter(absPath, originalFmRegion);
+  updateCache(ctx2, input.path, newContent, fm.bodyStart);
+  return {
+    path: input.path,
+    bytesWritten: Buffer.byteLength(newContent, "utf8"),
+    targetResolvedAt: resolvedAt,
+    frontmatterUnchanged: true
+  };
+}
+async function verifyFrontmatter(absPath, originalFmRegion) {
+  const written = await readFile4(absPath, "utf8");
+  if (written.slice(0, originalFmRegion.length) !== originalFmRegion) {
+    throw new Error("Write-safety violation: frontmatter region changed unexpectedly");
+  }
+}
+function updateCache(ctx2, path2, newContent, bodyStart) {
+  const cached = ctx2.notes.get(path2);
+  if (cached) {
+    cached.body = newContent.slice(bodyStart);
+    cached.raw = newContent;
+    cached.sizeBytes = Buffer.byteLength(newContent, "utf8");
+  }
+}
+
 // src/tools/read_note.ts
-import { readFile as readFile3 } from "fs/promises";
-import { join as join6 } from "path";
-import { z as z7 } from "zod";
-var ReadNoteInput = z7.object({
-  path: z7.string().describe('Vault-relative path to the note, e.g. "Daily Notes/2026-05-29.md".')
+import { readFile as readFile5 } from "fs/promises";
+import { join as join10 } from "path";
+import { z as z12 } from "zod";
+var ReadNoteInput = z12.object({
+  path: z12.string().describe('Vault-relative path to the note, e.g. "Daily Notes/2026-05-29.md".'),
+  section: z12.string().optional().describe("Return only this heading section (heading text, # prefix optional)."),
+  block: z12.string().optional().describe("Return only the block anchored by this id (^ prefix optional)."),
+  lines: z12.object({
+    from: z12.number().int().min(1).describe("First line (1-indexed, inclusive)."),
+    to: z12.number().int().min(1).optional().describe("Last line (1-indexed, inclusive). Defaults to end of file.")
+  }).optional().describe("Return only this line range (1-indexed, inclusive)."),
+  includeFrontmatter: z12.boolean().optional().describe(
+    "Include frontmatter in span results. Default false for section/block spans. No effect on lines or whole-note reads."
+  )
+}).refine((v) => [v.section, v.block, v.lines].filter((x) => x !== void 0).length <= 1, {
+  message: "At most one of section, block, or lines may be specified."
 });
 async function readNote(ctx2, input) {
-  const absPath = join6(ctx2.vaultRoot, input.path);
+  const absPath = join10(ctx2.vaultRoot, input.path);
   if (!absPath.startsWith(ctx2.vaultRoot)) {
     throw new Error(`Path outside vault: ${input.path}`);
   }
-  const content = await readFile3(absPath, "utf8");
+  const raw = await readFile5(absPath, "utf8");
+  const noteBytes = Buffer.byteLength(raw, "utf8");
+  if (input.section === void 0 && input.block === void 0 && input.lines === void 0) {
+    return { path: input.path, content: raw, bytesReturned: noteBytes, noteBytes };
+  }
+  const fm = parseFrontmatter(raw);
+  const outline = buildOutline(raw, { includeBlocks: true });
+  let charStart;
+  let charEnd;
+  if (input.section !== void 0) {
+    const target = input.section.replace(/^#+\s*/, "").trim();
+    const heading = outline.headings.find((h) => h.text === target);
+    if (!heading) {
+      throw new Error(
+        JSON.stringify({
+          error: "section_not_found",
+          target,
+          available: outline.headings.map((h) => h.text)
+        })
+      );
+    }
+    const nextSibling = outline.headings.find(
+      (h) => h.byteOffset > heading.byteOffset && h.level <= heading.level
+    );
+    charStart = heading.byteOffset;
+    charEnd = nextSibling?.byteOffset ?? raw.length;
+  } else if (input.block !== void 0) {
+    const targetId = input.block.replace(/^\^/, "");
+    const block = outline.blocks.find((b) => b.id === targetId);
+    if (!block) {
+      throw new Error(
+        JSON.stringify({
+          error: "block_not_found",
+          target: targetId,
+          available: outline.blocks.map((b) => b.id)
+        })
+      );
+    }
+    const lineS = block.byteOffset === 0 ? 0 : raw.lastIndexOf("\n", block.byteOffset - 1) + 1;
+    const nlAfter = raw.indexOf("\n", block.byteOffset);
+    const lineE = nlAfter === -1 ? raw.length : nlAfter + 1;
+    charStart = lineS;
+    charEnd = lineE;
+  } else {
+    const linesRange = input.lines;
+    if (linesRange === void 0) throw new Error("internal: unreachable");
+    const { from, to } = linesRange;
+    const rawLines = raw.split("\n");
+    const fromIdx = from - 1;
+    const toIdxInclusive = to !== void 0 ? Math.min(to - 1, rawLines.length - 1) : rawLines.length - 1;
+    let offset = 0;
+    charStart = 0;
+    charEnd = raw.length;
+    for (const [i, line] of rawLines.entries()) {
+      if (i === fromIdx) charStart = offset;
+      offset += line.length + 1;
+      if (i === toIdxInclusive) {
+        charEnd = Math.min(offset, raw.length);
+        break;
+      }
+    }
+  }
+  let content;
+  if (input.includeFrontmatter === true && input.lines === void 0) {
+    const fmRegion = raw.slice(0, fm.bodyStart);
+    const spanContent = raw.slice(charStart, charEnd);
+    content = charStart < fm.bodyStart ? spanContent : `${fmRegion}${spanContent}`;
+  } else {
+    content = raw.slice(charStart, charEnd);
+  }
   return {
     path: input.path,
     content,
-    sizeBytes: Buffer.byteLength(content, "utf8")
+    bytesReturned: Buffer.byteLength(content, "utf8"),
+    noteBytes,
+    span: { charStart, charEnd }
   };
 }
 
 // src/tools/search.ts
-import { z as z8 } from "zod";
+import { z as z13 } from "zod";
 
 // src/index/excerpt.ts
 function extractExcerpt(text, terms, maxLen = 200) {
@@ -438,11 +876,11 @@ function truncate(s, max) {
 }
 
 // src/tools/search.ts
-var SearchInput = z8.object({
-  query: z8.string().min(1).describe("Search query. Supports fuzzy matching and prefix search."),
-  limit: z8.number().int().min(1).max(50).default(10).describe("Maximum number of results to return."),
-  folder: z8.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
-  tag: z8.string().optional().describe("Restrict results to notes containing this tag.")
+var SearchInput = z13.object({
+  query: z13.string().min(1).describe("Search query. Supports fuzzy matching and prefix search."),
+  limit: z13.number().int().min(1).max(50).default(10).describe("Maximum number of results to return."),
+  folder: z13.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
+  tag: z13.string().optional().describe("Restrict results to notes containing this tag.")
 });
 function search(ctx2, input) {
   const results = ctx2.index.search(input.query, {
@@ -476,7 +914,18 @@ function search(ctx2, input) {
 }
 
 // src/dispatch.ts
-var META_KEYS = ["path", "from", "to", "folder", "tag", "limit", "overwrite"];
+var META_KEYS = [
+  "path",
+  "from",
+  "to",
+  "folder",
+  "tag",
+  "limit",
+  "overwrite",
+  "pattern",
+  "minCount",
+  "sort"
+];
 function safeMeta(args) {
   if (typeof args !== "object" || args === null) return {};
   const a = args;
@@ -524,13 +973,18 @@ async function run(ctx2, name, args) {
     case "read_note": {
       const input = ReadNoteInput.parse(args);
       const result = await readNote(ctx2, input);
-      return { content: [{ type: "text", text: result.content }] };
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
     case "list_notes": {
       const input = ListNotesInput.parse(args);
       const entries = listNotes(ctx2, input);
       return { content: [{ type: "text", text: JSON.stringify(entries, null, 2) }] };
     }
+    case "list_tags": {
+      const input = ListTagsInput.parse(args);
+      const result = listTags(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
     case "create_note": {
       const input = CreateNoteInput.parse(args);
       const result = await createNote(ctx2, input);
@@ -562,18 +1016,38 @@ async function run(ctx2, name, args) {
       const result = await patchFrontmatter(ctx2, input);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
+    case "outline_note": {
+      const input = OutlineNoteInput.parse(args);
+      const result = await outlineNote(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    case "patch_note": {
+      const input = PatchNoteInput.parse(args);
+      const result = await patchNote(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    case "get_backlinks": {
+      const input = GetBacklinksInput.parse(args);
+      const result = getBacklinks(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    case "get_links": {
+      const input = GetLinksInput.parse(args);
+      const result = getLinks(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
 }
 
 // src/index/build.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { basename as basename2, extname as extname3 } from "path";
 
 // ../core/src/walk.ts
 import { stat } from "fs/promises";
-import { extname as extname2, join as join7, relative, sep } from "path";
+import { extname as extname2, join as join11, relative, sep } 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"]);
@@ -650,7 +1124,7 @@ async function buildIndex(vaultRoot2) {
   await Promise.all(
     noteEntries.map(async (entry) => {
       try {
-        const raw = await readFile4(entry.absPath, "utf8");
+        const raw = await readFile6(entry.absPath, "utf8");
         const fm = parseFrontmatter(raw);
         const inlineTags = extractInlineTags(fm.body);
         const fmTags = frontmatterTags(fm.data);
@@ -673,12 +1147,37 @@ async function buildIndex(vaultRoot2) {
     })
   );
   index2.addAll(docs);
-  return { index: index2, notes: notes2, buildMs: Date.now() - t0 };
+  const backlinks2 = buildBacklinks(notes2);
+  return { index: index2, notes: notes2, backlinks: backlinks2, buildMs: Date.now() - t0 };
+}
+function buildBacklinks(notes2) {
+  const result = /* @__PURE__ */ new Map();
+  for (const [srcPath, doc] of notes2) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const link of extractLinksWithLines(doc.raw)) {
+      const resolved = resolveLink(link.target, notes2);
+      if (resolved === void 0) continue;
+      const dedupeKey = `${srcPath}\0${resolved}`;
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      let arr = result.get(resolved);
+      if (arr === void 0) {
+        arr = [];
+        result.set(resolved, arr);
+      }
+      arr.push({ path: srcPath, line: link.line, linkType: link.linkType });
+    }
+  }
+  for (const arr of result.values()) {
+    arr.sort((a, b) => a.path.localeCompare(b.path));
+  }
+  return result;
 }
 
 // src/init.ts
-import { access as access3, copyFile, mkdir as mkdir3, readFile as readFile5, readdir, stat as stat2, writeFile as writeFile4 } from "fs/promises";
-import path, { dirname as dirname3, join as join8 } from "path";
+import { execFileSync } from "child_process";
+import { access as access3, copyFile, mkdir as mkdir3, readFile as readFile7, readdir, stat as stat2, writeFile as writeFile5 } from "fs/promises";
+import path, { dirname as dirname3, join as join12 } from "path";
 function parseInitArgs(argv) {
   const opts = { write: false, client: "desktop" };
   for (let i = 0; i < argv.length; i++) {
@@ -715,6 +1214,43 @@ function claudeDesktopConfigPath(platform, env) {
   }
   return j(home, ".config", "Claude", "claude_desktop_config.json");
 }
+function obsidianRegistryPath(platform, env) {
+  if (platform === "win32") {
+    const j2 = path.win32.join;
+    const base = env.appData ?? j2(env.home ?? "", "AppData", "Roaming");
+    return j2(base, "obsidian", "obsidian.json");
+  }
+  const j = path.posix.join;
+  const home = env.home ?? "";
+  if (platform === "darwin") {
+    return j(home, "Library", "Application Support", "obsidian", "obsidian.json");
+  }
+  return j(home, ".config", "obsidian", "obsidian.json");
+}
+function parseObsidianVaults(json) {
+  let data;
+  try {
+    data = JSON.parse(json);
+  } catch {
+    return [];
+  }
+  if (!data || typeof data !== "object") return [];
+  const raw = data.vaults;
+  if (!raw || typeof raw !== "object") return [];
+  const entries = [];
+  for (const v of Object.values(raw)) {
+    if (v && typeof v === "object") {
+      const entry = v;
+      if (typeof entry.path === "string") {
+        entries.push({ path: entry.path, open: entry.open === true });
+      }
+    }
+  }
+  return entries.sort((a, b) => {
+    if (a.open !== b.open) return a.open ? -1 : 1;
+    return a.path.localeCompare(b.path);
+  });
+}
 function mergeSeekstoneConfig(existing, vaultPath) {
   const base = existing ? structuredClone(existing) : {};
   const servers = { ...base.mcpServers ?? {} };
@@ -729,7 +1265,7 @@ async function validateVault(vaultPath) {
     return { ok: false, error: `Path does not exist: ${vaultPath}` };
   }
   try {
-    await access3(join8(vaultPath, ".obsidian"));
+    await access3(join12(vaultPath, ".obsidian"));
   } catch {
     return {
       ok: false,
@@ -749,7 +1285,7 @@ async function countMarkdown(root) {
     }
     for (const e of entries) {
       if (e.name.startsWith(".")) continue;
-      const full = join8(dir, e.name);
+      const full = join12(dir, e.name);
       if (e.isDirectory()) await walk(full);
       else if (e.name.endsWith(".md")) count++;
     }
@@ -758,16 +1294,45 @@ async function countMarkdown(root) {
   return count;
 }
 async function runInit(opts, deps) {
-  const vaultPath = opts.vault ?? deps.env.SEEKSTONE_VAULT;
+  const rf = deps.readFile ?? readFile7;
+  let vaultPath = opts.vault ?? deps.env.SEEKSTONE_VAULT;
   if (!vaultPath) {
-    return {
-      ok: false,
-      exitCode: 1,
-      output: [
-        "No vault specified. Pass --vault <path> or set SEEKSTONE_VAULT.",
-        'Example: seekstone init --vault "/Users/you/Obsidian/My Vault"'
-      ]
-    };
+    const registryPath = obsidianRegistryPath(deps.platform, {
+      home: deps.env.HOME,
+      appData: deps.env.APPDATA
+    });
+    let vaults = [];
+    try {
+      vaults = parseObsidianVaults(await rf(registryPath, "utf8"));
+    } catch {
+    }
+    if (vaults.length === 0) {
+      return {
+        ok: false,
+        exitCode: 1,
+        output: [
+          "No vault specified. Pass --vault <path> or set SEEKSTONE_VAULT.",
+          'Example: seekstone init --vault "/Users/you/Obsidian/My Vault"'
+        ]
+      };
+    }
+    if (vaults.length === 1) {
+      const [first] = vaults;
+      vaultPath = first?.path ?? "";
+    } else {
+      const list = vaults.map((v, i) => `  ${i + 1}. ${v.path}${v.open ? " (currently open)" : ""}`).join("\n");
+      return {
+        ok: false,
+        exitCode: 1,
+        output: [
+          "Multiple Obsidian vaults found. Re-run with --vault to pick one:",
+          "",
+          list,
+          "",
+          'Example: seekstone init --vault "/path/to/vault"'
+        ]
+      };
+    }
   }
   const check = await validateVault(vaultPath);
   if (!check.ok) {
@@ -779,6 +1344,42 @@ async function runInit(opts, deps) {
     ""
   ];
   if (opts.client === "code") {
+    if (opts.write) {
+      const spawn = deps.spawnClaudeMcp ?? ((args) => {
+        try {
+          execFileSync("claude", args, { stdio: "inherit" });
+          return { ok: true };
+        } catch (err) {
+          return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+      });
+      const mcpArgs = [
+        "mcp",
+        "add",
+        "seekstone",
+        "--env",
+        `SEEKSTONE_VAULT=${vaultPath}`,
+        "--",
+        "npx",
+        "-y",
+        "seekstone"
+      ];
+      const result = spawn(mcpArgs);
+      if (result.ok) {
+        out.push("\u2713 seekstone added to Claude Code.", "", "Restart Claude Code to load seekstone.");
+        return { ok: true, exitCode: 0, output: out, ranClaudeMcpAdd: true };
+      }
+      out.push(
+        "\u26A0 Could not run `claude mcp add` automatically.",
+        result.error ? `  ${result.error}` : "",
+        "",
+        "Run this command manually instead:",
+        "",
+        `  ${mcpAddCommand(vaultPath)}`,
+        ""
+      );
+      return { ok: false, exitCode: 1, output: out };
+    }
     out.push("Add to Claude Code by running:", "", `  ${mcpAddCommand(vaultPath)}`, "");
     return { ok: true, exitCode: 0, output: out };
   }
@@ -805,7 +1406,7 @@ async function runInit(opts, deps) {
   let existing = null;
   let existingRaw = null;
   try {
-    existingRaw = await readFile5(configPath, "utf8");
+    existingRaw = await rf(configPath, "utf8");
     existing = JSON.parse(existingRaw);
   } catch (err) {
     if (existingRaw !== null) {
@@ -827,7 +1428,7 @@ async function runInit(opts, deps) {
     backupPath = `${configPath}.backup-${deps.timestamp}`;
     await copyFile(configPath, backupPath);
   }
-  await writeFile4(configPath, `${JSON.stringify(merged, null, 2)}
+  await writeFile5(configPath, `${JSON.stringify(merged, null, 2)}
 `, "utf8");
   out.push(
     `\u2713 Patched ${configPath}`,
@@ -899,7 +1500,7 @@ function createLogger(opts = {}) {
       );
     }
   }
-  function writeFile5(record) {
+  function writeFile6(record) {
     if (!fileOk || filePath === void 0) return;
     const line = `${JSON.stringify(record)}
 `;
@@ -921,7 +1522,7 @@ function createLogger(opts = {}) {
     const f = fields ?? {};
     stderr(`${lvl.toUpperCase().padEnd(5)} ${ts} ${msg}${fmtFields(f)}
 `);
-    writeFile5({ t: ts, level: lvl, msg, ...f });
+    writeFile6({ t: ts, level: lvl, msg, ...f });
   }
   return {
     level,
@@ -933,22 +1534,55 @@ function createLogger(opts = {}) {
 }
 
 // src/watcher.ts
-import { readFile as readFile6 } from "fs/promises";
-import { join as join9, relative as relative2, sep as sep2 } from "path";
+import { readFile as readFile8 } from "fs/promises";
+import { join as join13, relative as relative2, sep as sep2 } from "path";
 import chokidar from "chokidar";
+function removeNoteBacklinks(ctx2, relPath) {
+  const oldDoc = ctx2.notes.get(relPath);
+  if (oldDoc === void 0) return;
+  for (const link of extractLinksWithLines(oldDoc.raw)) {
+    const resolved = resolveLink(link.target, ctx2.notes);
+    if (resolved === void 0) continue;
+    const arr = ctx2.backlinks.get(resolved);
+    if (arr === void 0) continue;
+    const filtered = arr.filter((r) => r.path !== relPath);
+    ctx2.backlinks.set(resolved, filtered);
+  }
+}
+function addNoteBacklinks(ctx2, relPath, raw) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const link of extractLinksWithLines(raw)) {
+    const resolved = resolveLink(link.target, ctx2.notes);
+    if (resolved === void 0) continue;
+    const dedupeKey = `${relPath}\0${resolved}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    let arr = ctx2.backlinks.get(resolved);
+    if (arr === void 0) {
+      arr = [];
+      ctx2.backlinks.set(resolved, arr);
+    }
+    const ref = { path: relPath, line: link.line, linkType: link.linkType };
+    arr.push(ref);
+    arr.sort((a, b) => a.path.localeCompare(b.path));
+  }
+}
 function startWatcher(ctx2, log2, opts) {
   const usePolling = opts?.usePolling ?? process.env.SEEKSTONE_WATCH_POLL === "1";
   const toRel = (abs) => relative2(ctx2.vaultRoot, abs).split(sep2).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile6(join9(ctx2.vaultRoot, relPath), "utf8");
+      const raw = await readFile8(join13(ctx2.vaultRoot, relPath), "utf8");
+      removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
+      addNoteBacklinks(ctx2, relPath, raw);
       log2?.debug("index updated", { path: relPath, op });
     } catch {
     }
   }
   function remove(relPath) {
     if (ctx2.notes.has(relPath)) {
+      removeNoteBacklinks(ctx2, relPath);
       ctx2.index.discard(relPath);
       ctx2.notes.delete(relPath);
       log2?.debug("index removed", { path: relPath, op: "delete" });
@@ -966,7 +1600,11 @@ function startWatcher(ctx2, log2, opts) {
     binaryInterval: 100,
     // Skip dot-dirs (.obsidian, .git, .trash, …) regardless of where the vault
     // lives — matched on the path relative to the vault root.
-    ignored: (p) => relative2(ctx2.vaultRoot, p).split(sep2).some((seg) => seg.startsWith("."))
+    ignored: (p) => {
+      const rel = relative2(ctx2.vaultRoot, p);
+      if (!rel || rel === ".") return false;
+      return rel.split(sep2).filter(Boolean).some((seg) => seg.startsWith("."));
+    }
   });
   watcher2.on("add", onUpsert("add")).on("change", onUpsert("change")).on("unlink", (abs) => {
     const relPath = toRel(abs);
@@ -982,7 +1620,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.2.1" : "0.0.0-dev";
+var VERSION = true ? "0.4.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -1011,9 +1649,9 @@ if (!vaultRoot) {
   process.exit(1);
 }
 log.info("building index", { vault: vaultRoot });
-var { index, notes, buildMs } = await buildIndex(vaultRoot);
+var { index, notes, backlinks, buildMs } = await buildIndex(vaultRoot);
 log.info("index ready", { notes: notes.size, buildMs });
-var ctx = { vaultRoot, index, notes };
+var ctx = { vaultRoot, index, notes, backlinks };
 var watcher = startWatcher(ctx, log);
 process.on("exit", watcher.stop);
 var server = new Server({ name: "seekstone", version: "0.1.0" }, { capabilities: { tools: {} } });
@@ -1035,13 +1673,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "read_note",
-      description: "Read the full content of a specific note by its vault-relative path. Use search first to find the right path.",
+      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, and total note size so payload savings are measurable. Use search or outline_note first to find the right path and section names.",
       inputSchema: {
         type: "object",
         properties: {
           path: {
             type: "string",
             description: 'Vault-relative path, e.g. "Daily Notes/2026-05-29.md".'
+          },
+          section: {
+            type: "string",
+            description: "Return only this heading section (heading text, # prefix optional). First match wins."
+          },
+          block: {
+            type: "string",
+            description: "Return only the line anchored by this block id (^ prefix optional)."
+          },
+          lines: {
+            type: "object",
+            description: "Return only this line range (1-indexed, inclusive).",
+            properties: {
+              from: { type: "number", description: "First line (1-indexed)." },
+              to: {
+                type: "number",
+                description: "Last line (1-indexed, inclusive). Defaults to EOF."
+              }
+            },
+            required: ["from"]
+          },
+          includeFrontmatter: {
+            type: "boolean",
+            description: "Prepend frontmatter to section/block span results. Default false for spans."
           }
         },
         required: ["path"]
@@ -1060,6 +1722,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: []
       }
     },
+    {
+      name: "list_tags",
+      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",
+        properties: {
+          pattern: {
+            type: "string",
+            description: 'Substring filter on tag name. Example: "work" matches "work" and "area/work".'
+          },
+          minCount: {
+            type: "number",
+            description: "Only return tags used in at least this many notes."
+          },
+          sort: {
+            type: "string",
+            enum: ["count", "name"],
+            description: "Sort by usage count descending (default) or alphabetically."
+          }
+        },
+        required: []
+      }
+    },
     {
       name: "create_note",
       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.",
@@ -1138,6 +1823,80 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         required: ["path", "patch"]
       }
+    },
+    {
+      name: "outline_note",
+      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",
+        properties: {
+          path: { type: "string", description: "Vault-relative path to the note." },
+          includeBlocks: {
+            type: "boolean",
+            description: "Include block-reference anchors (^id). Default true."
+          },
+          includeSizes: {
+            type: "boolean",
+            description: "Include per-section character length in each heading entry. Default false."
+          }
+        },
+        required: ["path"]
+      }
+    },
+    {
+      name: "patch_note",
+      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",
+        properties: {
+          path: { type: "string", description: "Vault-relative path to the note." },
+          target: {
+            type: "object",
+            description: 'Exactly one of: { heading: "Section Title" } or { block: "block-id" } (without the ^ prefix).'
+          },
+          operation: {
+            type: "string",
+            enum: ["append", "prepend", "replace"],
+            description: "append: insert after section content. prepend: insert after heading line. replace: swap section content."
+          },
+          content: { type: "string", description: "Content to insert or replace with." },
+          createIfMissing: {
+            type: "boolean",
+            description: "If the heading target is not found, append a new heading (level 2) + content. Only valid for heading targets. Default false."
+          }
+        },
+        required: ["path", "target", "operation", "content"]
+      }
+    },
+    {
+      name: "get_backlinks",
+      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",
+        properties: {
+          path: { type: "string", description: "Vault-relative path to the target note." },
+          includeContext: {
+            type: "boolean",
+            description: "Include a short excerpt (~200 chars) from the linking line. Default true."
+          },
+          limit: {
+            type: "number",
+            description: "Max backlinks to return (1\u2013500). Default 50."
+          }
+        },
+        required: ["path"]
+      }
+    },
+    {
+      name: "get_links",
+      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",
+        properties: {
+          path: { type: "string", description: "Vault-relative path to the note." }
+        },
+        required: ["path"]
+      }
     }
   ]
 }));
@@ -1147,7 +1906,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 var transport = new StdioServerTransport();
 await server.connect(transport);
-log.info("ready", { tools: 8, transport: "stdio" });
+log.info("ready", { tools: 13, transport: "stdio" });
 process.stderr.write(
   `seekstone: add to Claude Desktop:
 ${JSON.stringify(