seekstone 0.12.0 → 0.12.2

package/README.md

@@ -1,10 +1,10 @@
 # seekstone
 
-**The Obsidian MCP server for Claude — search and edit your vault without burning context.**
+**The Obsidian MCP server that needs no plugin, no running Obsidian app — and doesn't blow your context window.**
 
 Seekstone is an Obsidian MCP server that gives Claude (and any [Model Context Protocol](https://modelcontextprotocol.io) client) direct read and write access to your Obsidian vault. No Obsidian app needs to be running, no plugins are required, and nothing leaves your machine.
 
-It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin. The practical difference: a search that returns ~1.75 MB and ~459,000 tokens via the REST plugin returns **~3 KB and ~800 tokens** via Seekstone — a **~575× reduction**. Claude can search and read your entire note library without burning most of its context window on a single tool call.
+It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference: searches return in **single-digit milliseconds** with **~2 KB payloads** that stay flat as your vault grows — a broad query that costs tens of megabytes of context through a REST-proxy server (up to **95 MB** at 10k notes) costs ~2 KB through Seekstone, up to a **~47,000× reduction**. Benchmarked against 7 other Obsidian MCP servers across committed 1k/5k/10k-note vaults — [fully reproducible](https://github.com/shaqmughal/seekstone/tree/main/packages/harness), full results at [seekstone.dev/benchmarks](https://seekstone.dev/benchmarks).
 
 (Previously also published as `obsidian-mcp-seekstone` — that alias is deprecated; existing installs keep working, but install `seekstone` going forward.)
 
@@ -16,6 +16,12 @@ It reads your vault **directly from disk** instead of routing through the Obsidi
 
 Choose the method that suits you best.
 
+### Using an AI agent? Paste this prompt
+
+If you use Claude Code, Cursor, or another coding agent, paste this prompt and the agent does the install:
+
+> Install the **seekstone** MCP server for this editor. Run `npx -y seekstone init --client code --write` (use `desktop`, `cursor`, or `vscode` for other clients). It auto-detects my Obsidian vault; if it lists several, ask me which one and re-run with `--vault "<path>"`. Relay any errors to me, then tell me to restart this session so the seekstone tools load.
+
 ### Option 1 — One-click (Claude Desktop, no terminal needed)
 
 Download `seekstone.mcpb` from [GitHub Releases](https://github.com/shaqmughal/seekstone/releases/latest), double-click it in Claude Desktop, and pick your Obsidian vault folder when prompted. No JSON editing, no terminal, no Node.js setup required.
@@ -28,7 +34,7 @@ Run the setup helper and let Seekstone find your vault automatically:
 npx -y seekstone init
 ```
 
-Seekstone reads Obsidian's own vault registry to detect your vault, validates it, and either prints the config to paste or patches Claude Desktop directly:
+Seekstone reads Obsidian's own vault registry to detect your vault, validates it, and either prints the config to paste or patches the client config directly:
 
 ```bash
 # Auto-detect vault, print config to paste
@@ -40,8 +46,10 @@ npx -y seekstone init --write
 # Specify vault explicitly if you have multiple
 npx -y seekstone init --vault "/path/to/vault"
 
-# Generate the Claude Code command instead
-npx -y seekstone init --client code
+# Auto-configure Claude Code / Cursor / VS Code in one step
+npx -y seekstone init --client code --write
+npx -y seekstone init --client cursor --write
+npx -y seekstone init --client vscode --write
 ```
 
 ### Option 3 — Manual config (Claude Desktop)
@@ -84,17 +92,27 @@ One-click via the [Install in VS Code](https://vscode.dev/redirect?url=vscode:mc
 code --add-mcp '{"name":"seekstone","command":"npx","args":["-y","seekstone"],"env":{"SEEKSTONE_VAULT":"/absolute/path/to/your/vault"}}'
 ```
 
+Or auto-detect and write the workspace config:
+
+```bash
+npx -y seekstone init --client vscode --write
+```
+
 Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their own MCP config file.
 
 ---
 
 ## Tools
 
+18 tools: 10 read, 8 write.
+
 ### Read
 
 | Tool | Description |
 |---|---|
-| `search` | Full-text search. Returns ranked excerpts (default ~120 chars, tunable via `excerptLength`), not full notes. Fuzzy, prefix, and phrase queries. |
+| `search` | Full-text search. Returns ranked excerpts (default ~120 chars, tunable via `excerptLength`), not full notes. Fuzzy and prefix matching. |
+| `query_notes` | Structured metadata query. Filter by frontmatter key/value predicates (`eq`, `ne`, `contains`, `exists`, `missing`, `gt`/`gte`/`lt`/`lte`), tag, folder, modified time, and size; sort and select the fields you need. Returns compact rows, not note content. |
+| `context_pack` | Answer-ready context for a natural-language question in one call, hard-capped at a byte budget (default 2 KB): ranked excerpts, linked neighbor notes with one-line summaries, and follow-up source paths — replaces a search → read → get_backlinks round-trip loop. |
 | `read_note` | Read the full content of a note by vault-relative path. Supports returning a single section, block, or line range. |
 | `list_notes` | List notes, optionally filtered by folder prefix or tag. |
 | `list_tags` | List all tags in the vault sorted by usage count (or alphabetically). |
@@ -107,15 +125,17 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 
 | Tool | Description |
 |---|---|
-| `create_note` | Create a note (optional frontmatter + body); parent dirs created automatically. |
-| `delete_note` | Permanently delete a note. |
-| `move_note` | Move/rename a note; destination dirs created automatically. |
+| `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. |
 | `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. |
-| `replace_in_note` | Replace the first occurrence of a word or phrase in the note body. |
+| `replace_in_note` | Find and replace text in the note body — literal or regex, whole-word, case sensitivity, optional `limit` (replaces **all** occurrences by default), dry-run preview. |
 | `append_periodic_note` | Append to today's periodic note, creating it from a template if it doesn't yet exist. |
 
+The content-editing tools (`append_note`, `patch_note`, `patch_frontmatter`, `replace_in_note`, `append_periodic_note`, and `create_note` with `overwrite: true`) support optional **compare-and-swap**: pass the `contentHash` you got from `read_note` as `prevHash` and the write fails cleanly if the note changed underneath you, instead of silently discarding the concurrent edit.
+
 ---
 
 ## Configuration
@@ -126,6 +146,15 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 | `SEEKSTONE_LOG_LEVEL` | no | `error` \| `warn` \| `info` (default) \| `debug`. |
 | `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_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. |
+
+---
+
+## Write safety
+
+Giving an AI write access to your notes deserves more than "trust us." Seekstone ships the [Write-Safety Contract](https://github.com/shaqmughal/seekstone/blob/main/docs/WRITE-SAFETY.md): **eight named guarantees, each linked to the code that enforces it and the test that proves it**, verified byte-by-byte in CI on every commit and release — zero network, vault sandbox, byte-identical frontmatter on body edits, atomic writes, no-clobber creates, recoverable deletes, optional compare-and-swap, and write scoping / read-only mode.
 
 ---
 
@@ -135,7 +164,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 No — Seekstone reads the vault folder from disk directly.
 
 **Do I need the Local REST API plugin?**
-No — Seekstone bypasses it entirely (that's where the 575× reduction comes from).
+No — Seekstone bypasses it entirely (that's the source of the up-to-~47,000× payload reduction).
 
 **How does `seekstone init` find my vault automatically?**
 It reads Obsidian's own vault registry (`obsidian.json`) — the same file Obsidian uses to track your known vaults. One vault → auto-selected. Multiple → lists them and asks you to pick with `--vault`.
@@ -144,13 +173,13 @@ It reads Obsidian's own vault registry (`obsidian.json`) — the same file Obsid
 An MCP Bundle — a zip containing the server and its manifest. Claude Desktop installs it with a double-click, no terminal required.
 
 **Which AI clients does it support?**
-Any MCP-over-stdio client: Claude Desktop, Claude Code, Cursor, Windsurf, Continue, and others.
+Any MCP-over-stdio client: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Continue, and others.
 
 **Does it work on Windows?**
 Yes — tested on macOS, Linux, and Windows in CI on every commit.
 
 **Is it safe?**
-No network calls, no telemetry. The vault path is sandboxed — no tool reads or writes outside it.
+No network calls, no telemetry. The vault path is sandboxed — no tool reads or writes outside it. Writes are covered by the tested Write-Safety Contract above, and `SEEKSTONE_READ_ONLY=1` removes the write tools entirely.
 
 ---
 
@@ -163,4 +192,4 @@ No network calls, no telemetry. The vault path is sandboxed — no tool reads or
 
 ## License
 
-MIT © Shaq Mughal · [GitHub](https://github.com/shaqmughal/seekstone) · [Issues](https://github.com/shaqmughal/seekstone/issues)
+MIT © Shaq Mughal · [seekstone.dev](https://seekstone.dev) · [GitHub](https://github.com/shaqmughal/seekstone) · [Issues](https://github.com/shaqmughal/seekstone/issues)

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);
@@ -565,7 +572,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 +618,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 {
@@ -643,7 +647,7 @@ async function createNote(ctx2, rawInput) {
   let raw = "";
   if (input.frontmatter && Object.keys(input.frontmatter).length > 0) {
     raw = `---
-${stringifyYaml(input.frontmatter)}---
+${stringifyYaml(input.frontmatter, { lineWidth: 0 })}---
 `;
   }
   raw += input.content ?? "";
@@ -659,7 +663,7 @@ ${stringifyYaml(input.frontmatter)}---
 
 // 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 +711,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 +720,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 +742,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 +750,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 +775,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 +865,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
@@ -976,10 +969,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 +1028,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 +1045,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 +1101,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,7 +1111,6 @@ 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 { z as z12 } from "zod";
 var PatchFrontmatterInput = z12.object({
@@ -1137,10 +1123,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);
@@ -1158,7 +1141,7 @@ async function patchFrontmatter(ctx2, input) {
       }
     }
     newContent = `---
-${doc.toString()}---
+${doc.toString({ lineWidth: 0 })}---
 ${original}`;
   } else {
     const opensWithCRLF = original.startsWith("---\r\n");
@@ -1183,7 +1166,7 @@ ${original}`;
     }
     const head = opensWithCRLF ? "---\r\n" : "---\n";
     const tail = opensWithCRLF ? "---\r\n" : "---\n";
-    newContent = `${head}${doc.toString()}${tail}${fm.body}`;
+    newContent = `${head}${doc.toString({ lineWidth: 0 })}${tail}${fm.body}`;
   }
   await atomicWrite(absPath, newContent);
   const cached = ctx2.notes.get(input.path);
@@ -1203,7 +1186,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 +1214,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 +1229,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 +1286,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 +1332,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 +1352,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 +1360,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 +1413,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 +1425,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 +1453,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 +1631,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 +1647,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);
@@ -1766,7 +1737,6 @@ async function readNote(ctx2, input) {
 
 // src/tools/replace_in_note.ts
 import { readFile as readFile8 } from "fs/promises";
-import { join as join12 } from "path";
 import { z as z17 } from "zod";
 var ReplaceInNoteInput = z17.object({
   path: z17.string().describe("Vault-relative path to the note."),
@@ -1791,10 +1761,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 {
@@ -2076,7 +2043,7 @@ 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 join4, 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 +2085,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,
@@ -2207,7 +2174,7 @@ 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 path, { dirname as dirname4, join as join5 } from "path";
 function parseInitArgs(argv) {
   const opts = { write: false, client: "desktop" };
   for (let i = 0; i < argv.length; i++) {
@@ -2250,7 +2217,7 @@ function cursorConfigPath(platform, env) {
   return j(env.home ?? "", ".cursor", "mcp.json");
 }
 function vscodeMcpConfigPath(cwd) {
-  return join14(cwd, ".vscode", "mcp.json");
+  return join5(cwd, ".vscode", "mcp.json");
 }
 function obsidianRegistryPath(platform, env) {
   if (platform === "win32") {
@@ -2312,7 +2279,7 @@ async function validateVault(vaultPath) {
     return { ok: false, error: `Path does not exist: ${vaultPath}` };
   }
   try {
-    await access5(join14(vaultPath, ".obsidian"));
+    await access5(join5(vaultPath, ".obsidian"));
   } catch {
     return {
       ok: false,
@@ -2332,7 +2299,7 @@ async function countMarkdown(root) {
     }
     for (const e of entries) {
       if (e.name.startsWith(".")) continue;
-      const full = join14(dir, e.name);
+      const full = join5(dir, e.name);
       if (e.isDirectory()) await walk(full);
       else if (e.name.endsWith(".md")) count++;
     }
@@ -3052,7 +3019,7 @@ 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 { join as join6, 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 +3028,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 readFile11(join6(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
@@ -3096,7 +3063,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 +3071,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 +3083,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.12.0" : "0.0.0-dev";
+var VERSION = true ? "0.12.2" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -3146,11 +3113,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 });