seekstone 0.20.2 → 0.21.0

package/README.md

@@ -4,7 +4,7 @@
 
 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, and holds a warm full-text index in-process. The practical difference: keyword searches return in **single-digit milliseconds** (semantic search in **~26 ms**) 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).
+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: keyword searches return in **single-digit milliseconds** (semantic search in **~26 ms**) 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.)
 
@@ -104,7 +104,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 
 ## Tools
 
-21 tools: 11 read, 10 write.
+22 tools: 12 read, 10 write.
 
 ### Read
 
@@ -114,6 +114,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 | `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. Scopable by `folder`/`tag` and takes the same `mode` as `search`. |
 | `read_note` | Read the full content of a note by vault-relative path. Supports returning a single section, block, or line range. |
+| `read_notes` | Read up to 20 notes (or sections, blocks, line ranges) in one call under a total byte budget (default 16 KB). Over budget, each note is cut to a fair share and marked `truncated`; one bad path returns its own error without failing the batch. |
 | `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). |
 | `outline_note` | Return a note's heading and block structure without its full content. |
@@ -209,6 +210,9 @@ Any MCP-over-stdio client: Claude Desktop, Claude Code, Cursor, VS Code, Windsur
 **Does it work on Windows?**
 Yes — tested on macOS, Linux, and Windows in CI on every commit.
 
+**Does search handle typos?**
+Yes, small ones. Keyword search allows one typo per word of 3–7 letters and two for words of 8 or more, so `benchamrk` still finds "benchmark". One- and two-letter words must match exactly, and swapping two letters counts as two typos. It also matches word prefixes: `kuber` finds "Kubernetes". The `tag` filter on `search`, `context_pack`, `query_notes`, and `list_notes` works like Obsidian's: it ignores case and includes nested tags, so `project` matches `#Project/alpha`. A tag no note has returns an `unknown_tag` error listing the closest existing tags.
+
 **Is it safe?**
 No network calls while running, no telemetry (the optional semantic-search model is downloaded once by the explicit `fetch-model` subcommand, SHA-256-verified, before any serving starts — or shipped inside the `seekstone-semantic.mcpb` bundle and reassembled from disk at boot, verified against the same pinned hashes). 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.
 

package/dist/index.js

@@ -1038,6 +1038,73 @@ function resolveLink(target, notes2, maps) {
 // src/tools/search.ts
 import { z as z2 } from "zod";
 
+// src/index/tags.ts
+function normalizeTag(tag) {
+  return tag.replace(/^#/, "").toLowerCase();
+}
+function noteHasTag(noteTags, wanted) {
+  for (const t of noteTags.split(" ")) {
+    if (!t) continue;
+    const tag = t.toLowerCase();
+    if (tag === wanted || tag.startsWith(`${wanted}/`)) return true;
+  }
+  return false;
+}
+function editDistance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  let dist = b.length;
+  for (let i = 0; i < a.length; i++) {
+    let diag = i;
+    let left = i + 1;
+    const next = [left];
+    for (const [j, up] of row.slice(1).entries()) {
+      left = Math.min(up + 1, left + 1, diag + (a[i] === b[j] ? 0 : 1));
+      diag = up;
+      next.push(left);
+    }
+    row = next;
+    dist = left;
+  }
+  return dist;
+}
+var MAX_SUGGESTIONS = 3;
+function suggestTags(notes2, wanted) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const note of notes2) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const t of note.tags.split(" ")) {
+      if (!t) continue;
+      const parts = t.toLowerCase().split("/");
+      for (let i = 1; i <= parts.length; i++) seen.add(parts.slice(0, i).join("/"));
+    }
+    for (const tag of seen) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  }
+  const budget = Math.max(2, Math.ceil(wanted.length / 3));
+  const scored = [];
+  for (const [tag, count] of counts) {
+    const leaf = tag.slice(tag.lastIndexOf("/") + 1);
+    const dist = Math.min(editDistance(wanted, tag), editDistance(wanted, leaf));
+    if (dist <= budget) scored.push({ tag, dist, count });
+  }
+  scored.sort((a, b) => a.dist - b.dist || b.count - a.count || a.tag.localeCompare(b.tag));
+  return scored.slice(0, MAX_SUGGESTIONS).map((s) => s.tag);
+}
+function assertTagExists(notes2, tag) {
+  const wanted = normalizeTag(tag);
+  for (const note of notes2.values()) {
+    if (noteHasTag(note.tags, wanted)) return;
+  }
+  const didYouMean = suggestTags(notes2.values(), wanted);
+  throw new Error(
+    JSON.stringify({
+      error: "unknown_tag",
+      tag,
+      ...didYouMean.length > 0 ? { didYouMean } : {},
+      hint: "No note in the vault has this tag. Matching ignores case and includes nested child tags. Retry with a suggested tag, or call list_tags to see the tags that exist."
+    })
+  );
+}
+
 // src/semantic/excerpt.ts
 function chunkExcerpt(body, span, terms, maxLen) {
   const normalized = body.includes("\r") ? body.replace(/\r\n/g, "\n") : body;
@@ -1072,7 +1139,9 @@ var SearchInput = z2.object({
   ),
   limit: z2.number().int().min(1).max(50).default(10).describe("Maximum number of results to return."),
   folder: z2.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
-  tag: z2.string().optional().describe("Restrict results to notes containing this tag."),
+  tag: z2.string().optional().describe(
+    'Restrict results to notes with this tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  ),
   excerptLength: z2.number().int().min(20).max(2e3).optional().describe(
     "Max characters of match context per hit (default 120). Lower trims payload; higher gives more context."
   )
@@ -1084,6 +1153,11 @@ function basenameNoExt(path2) {
   return dot > 0 ? base.slice(0, dot) : base;
 }
 function retrieve(ctx2, input) {
+  const result = retrieveUnchecked(ctx2, input);
+  if (result.hits.length === 0 && input.tag) assertTagExists(ctx2.notes, input.tag);
+  return result;
+}
+function retrieveUnchecked(ctx2, input) {
   const mode = input.mode ?? "lexical";
   if (mode === "lexical") return lexicalSearch(ctx2, input);
   const semantic = requireSemantic(ctx2);
@@ -1177,12 +1251,7 @@ function filterNote(ctx2, input, path2) {
   if (input.folder && !path2.startsWith(input.folder)) return void 0;
   const note = ctx2.notes.get(path2);
   if (!note) return void 0;
-  if (input.tag) {
-    const noteTags = note.tags.split(" ");
-    if (!noteTags.some((t) => t === input.tag || t === input.tag?.replace(/^#/, ""))) {
-      return void 0;
-    }
-  }
+  if (input.tag && !noteHasTag(note.tags, normalizeTag(input.tag))) return void 0;
   return note;
 }
 function decorate(hit, title, tags) {
@@ -1199,7 +1268,9 @@ var ContextPackInput = z3.object({
     "lexical = keyword search (default). semantic = meaning-based search over local embeddings (requires SEEKSTONE_SEMANTIC=1 and a fetched model). hybrid = exact-title lookups go lexical, everything else semantic. A question asked in words the note does not use needs semantic or hybrid."
   ),
   folder: z3.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
-  tag: z3.string().optional().describe("Restrict results to notes containing this tag.")
+  tag: z3.string().optional().describe(
+    'Restrict results to notes with this tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  )
 });
 var MAX_CANDIDATES = 10;
 var NEIGHBOR_HITS = 3;
@@ -1647,18 +1718,17 @@ var ListNotesInput = z8.object({
   folder: z8.string().optional().describe(
     'Vault-relative folder prefix to list. Omit for all notes. Example: "Daily Notes/2026".'
   ),
-  tag: z8.string().optional().describe("Filter by tag. Include or omit the leading #."),
+  tag: z8.string().optional().describe(
+    'Filter by tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  ),
   limit: z8.number().int().min(1).max(500).default(100).describe("Maximum number of results.")
 });
 function listNotes(ctx2, input) {
-  const tag = input.tag?.replace(/^#/, "");
+  const tag = input.tag === void 0 ? void 0 : normalizeTag(input.tag);
   const results = [];
   for (const [path2, note] of ctx2.notes) {
     if (input.folder && !path2.startsWith(input.folder)) continue;
-    if (tag) {
-      const noteTags = note.tags.split(" ").filter(Boolean);
-      if (!noteTags.includes(tag)) continue;
-    }
+    if (tag && !noteHasTag(note.tags, tag)) continue;
     results.push({
       path: path2,
       title: note.title,
@@ -1667,6 +1737,7 @@ function listNotes(ctx2, input) {
     });
     if (results.length >= input.limit) break;
   }
+  if (results.length === 0 && input.tag) assertTagExists(ctx2.notes, input.tag);
   return results.sort((a, b) => a.path.localeCompare(b.path));
 }
 
@@ -2403,7 +2474,9 @@ var ISO_DATE = z16.string().refine((s) => !Number.isNaN(Date.parse(s)), { messag
 var QueryNotesInput = z16.object({
   where: z16.array(Predicate).max(20).default([]).describe("Frontmatter predicates. All must match (AND)."),
   folder: z16.string().optional().describe("Restrict to notes under this vault-relative folder prefix."),
-  tag: z16.string().optional().describe("Restrict to notes with this tag (# prefix optional)."),
+  tag: z16.string().optional().describe(
+    'Restrict to notes with this tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  ),
   modifiedAfter: ISO_DATE.optional().describe(
     "Only notes modified at or after this ISO 8601 date/time."
   ),
@@ -2468,14 +2541,14 @@ function matches(fm, p) {
   }
 }
 function queryNotes(ctx2, input) {
-  const tag = input.tag?.replace(/^#/, "");
+  const tag = input.tag === void 0 ? void 0 : normalizeTag(input.tag);
   const after = input.modifiedAfter ? Date.parse(input.modifiedAfter) : void 0;
   const before = input.modifiedBefore ? Date.parse(input.modifiedBefore) : void 0;
   const fmKeys = input.select.filter((s) => s !== "mtime" && s !== "size" && s !== "tags");
   const hits = [];
   for (const [path2, note] of ctx2.notes) {
     if (input.folder && !path2.startsWith(input.folder)) continue;
-    if (tag && !note.tags.split(" ").filter(Boolean).includes(tag)) continue;
+    if (tag && !noteHasTag(note.tags, tag)) continue;
     if (after !== void 0 && note.mtimeMs < after) continue;
     if (before !== void 0 && note.mtimeMs >= before) continue;
     if (input.minSizeBytes !== void 0 && note.sizeBytes < input.minSizeBytes) continue;
@@ -2498,6 +2571,7 @@ function queryNotes(ctx2, input) {
     }
     hits.push({ hit, note });
   }
+  if (hits.length === 0 && input.tag) assertTagExists(ctx2.notes, input.tag);
   const dir = input.order === "desc" ? -1 : 1;
   hits.sort((a, b) => {
     switch (input.sort) {
@@ -2620,19 +2694,77 @@ async function readNote(ctx2, input) {
   };
 }
 
+// src/tools/read_notes.ts
+import { z as z18 } from "zod";
+var DEFAULT_BUDGET_BYTES = 16384;
+var ReadNotesInput = z18.object({
+  items: z18.array(ReadNoteInput).min(1).max(20).describe(
+    "Notes to read, 1\u201320, each with the same options as read_note (path plus at most one of section, block, or lines)."
+  ),
+  budgetBytes: z18.number().int().min(256).max(65536).default(DEFAULT_BUDGET_BYTES).describe(
+    "Cap on the total note text returned across all items (UTF-8 bytes). When exceeded, each item is truncated to a fair share."
+  )
+});
+async function readNotes(ctx2, input) {
+  const budget = input.budgetBytes;
+  const results = await Promise.all(
+    input.items.map((item) => readNote(ctx2, item).catch((err) => toItemError(item.path, err)))
+  );
+  const entries = results.filter((r) => !("error" in r)).map((r) => ({ r, size: r.bytesReturned, alloc: 0 }));
+  allocate(entries, budget);
+  const cut = new Map(
+    entries.map((e) => [e.r, truncateItem(e.r, e.alloc)])
+  );
+  const notes2 = results.map((r) => cut.get(r) ?? r);
+  const bytesUsed = [...cut.values()].reduce((sum, r) => sum + r.bytesReturned, 0);
+  return { notes: notes2, budgetBytes: budget, bytesUsed };
+}
+function toItemError(path2, err) {
+  const { message, code } = err;
+  if (message.startsWith("{")) return { path: path2, ...JSON.parse(message) };
+  if (message.startsWith("Path outside vault")) return { path: path2, error: "outside_vault" };
+  if (code === "ENOENT") return { path: path2, error: "not_found" };
+  return { path: path2, error: "read_failed", message };
+}
+function allocate(entries, budget) {
+  let pending = entries.filter((e) => e.size > 0);
+  let remaining = budget;
+  for (const e of entries) e.alloc = e.size;
+  if (entries.reduce((sum, e) => sum + e.size, 0) <= budget) return;
+  while (pending.length > 0) {
+    const share = Math.floor(remaining / pending.length);
+    const fits = pending.filter((e) => e.size <= share);
+    if (fits.length === 0) {
+      const extra = remaining - share * pending.length;
+      for (const [k, e] of pending.entries()) e.alloc = share + (k < extra ? 1 : 0);
+      return;
+    }
+    for (const e of fits) remaining -= e.size;
+    pending = pending.filter((e) => e.size > share);
+  }
+}
+function truncateItem(r, maxBytes) {
+  if (r.bytesReturned <= maxBytes) return r;
+  const buf = Buffer.from(r.content, "utf8");
+  let end = maxBytes;
+  while (end > 0 && (buf.readUInt8(end) & 192) === 128) end--;
+  const content = buf.toString("utf8", 0, end);
+  return { ...r, content, bytesReturned: end, truncated: true };
+}
+
 // src/tools/rename_heading.ts
 import { readFile as readFile11 } from "fs/promises";
 import { join as join5 } from "path";
-import { z as z18 } from "zod";
-var RenameHeadingInput = z18.object({
-  path: z18.string().describe("Vault-relative path of the note containing the heading."),
-  oldHeading: z18.string().min(1).describe(
+import { z as z19 } from "zod";
+var RenameHeadingInput = z19.object({
+  path: z19.string().describe("Vault-relative path of the note containing the heading."),
+  oldHeading: z19.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: z18.string().min(1).refine((s) => !/[\n[\]|#]/.test(s), {
+  newHeading: z19.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: z18.string().optional().describe(
+  prevHash: z19.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."
   )
 });
@@ -2755,17 +2887,17 @@ async function renameHeading(ctx2, rawInput) {
 
 // src/tools/replace_in_note.ts
 import { readFile as readFile12 } from "fs/promises";
-import { z as z19 } from "zod";
-var ReplaceInNoteInput = z19.object({
-  path: z19.string().describe("Vault-relative path to the note."),
-  find: z19.string().min(1).max(1e3).describe("Text or pattern to find (max 1000 chars; bounds regex-mode pattern size)."),
-  replace: z19.string().describe("Replacement text. Supports $1, $2, \u2026 backreferences in regex mode."),
-  regex: z19.boolean().default(false).describe("Treat find as a regular expression."),
-  caseSensitive: z19.boolean().default(false).describe("Case-sensitive matching."),
-  wholeWord: z19.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
-  limit: z19.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
-  dryRun: z19.boolean().default(false).describe("If true, report matches without writing anything."),
-  prevHash: z19.string().optional().describe(
+import { z as z20 } from "zod";
+var ReplaceInNoteInput = z20.object({
+  path: z20.string().describe("Vault-relative path to the note."),
+  find: z20.string().min(1).max(1e3).describe("Text or pattern to find (max 1000 chars; bounds regex-mode pattern size)."),
+  replace: z20.string().describe("Replacement text. Supports $1, $2, \u2026 backreferences in regex mode."),
+  regex: z20.boolean().default(false).describe("Treat find as a regular expression."),
+  caseSensitive: z20.boolean().default(false).describe("Case-sensitive matching."),
+  wholeWord: z20.boolean().default(false).describe("Match whole words only (\\b word-boundary)."),
+  limit: z20.number().int().min(1).optional().describe("Maximum number of replacements. Omit to replace all."),
+  dryRun: z20.boolean().default(false).describe("If true, report matches without writing anything."),
+  prevHash: z20.string().optional().describe(
     "Optional compare-and-swap guard: the contentHash from a prior read. Fails with hash_conflict if the note changed since."
   )
 });
@@ -2850,12 +2982,12 @@ async function replaceInNote(ctx2, input) {
 // src/tools/undo_write.ts
 import { mkdir as mkdir6, readFile as readFile13, rm as rm3 } from "fs/promises";
 import { dirname as dirname4 } from "path";
-import { z as z20 } from "zod";
-var UndoWriteInput = z20.object({
-  seq: z20.number().int().min(1).optional().describe(
+import { z as z21 } from "zod";
+var UndoWriteInput = z21.object({
+  seq: z21.number().int().min(1).optional().describe(
     "Journal entry to revert (from list_writes). Defaults to the most recent undoable write."
   ),
-  force: z20.boolean().default(false).describe(
+  force: z21.boolean().default(false).describe(
     "Restore even if a file changed after the journaled write. The clobbered state is journaled first, so nothing is lost. Defaults to false \u2014 conflicts are refused."
   )
 });
@@ -3012,6 +3144,7 @@ function safeMeta(args) {
   }
   if (typeof a.query === "string") out.queryLen = a.query.length;
   if (Array.isArray(a.where)) out.whereCount = a.where.length;
+  if (Array.isArray(a.items)) out.itemsCount = a.items.length;
   return out;
 }
 function resultBytes(r) {
@@ -3161,6 +3294,11 @@ async function run(ctx2, name, args) {
       const result = await readNote(ctx2, input);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
+    case "read_notes": {
+      const input = ReadNotesInput.parse(args);
+      const result = await readNotes(ctx2, input);
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
     case "list_notes": {
       const input = ListNotesInput.parse(args);
       const entries = listNotes(ctx2, input);
@@ -4908,7 +5046,10 @@ var ALL_TOOLS = [
         },
         limit: { type: "number", description: "Max results (1\u201350, default 10)." },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag." },
+        tag: {
+          type: "string",
+          description: 'Restrict to notes with this tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        },
         excerptLength: {
           type: "number",
           description: "Max characters of match context per hit (20\u20132000, default 120)."
@@ -4945,7 +5086,10 @@ var ALL_TOOLS = [
           }
         },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag (# optional)." },
+        tag: {
+          type: "string",
+          description: 'Restrict to notes with this tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        },
         modifiedAfter: {
           type: "string",
           description: "Only notes modified at or after this ISO 8601 date/time."
@@ -4994,7 +5138,10 @@ var ALL_TOOLS = [
           description: "lexical = keyword search (default). semantic = meaning-based over local embeddings (needs SEEKSTONE_SEMANTIC=1 and a fetched model). hybrid = exact-title lookups go lexical, everything else semantic."
         },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag." }
+        tag: {
+          type: "string",
+          description: 'Restrict to notes with this tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        }
       },
       required: ["query"]
     }
@@ -5038,6 +5185,59 @@ var ALL_TOOLS = [
       required: ["path"]
     }
   },
+  {
+    name: "read_notes",
+    annotations: READ_ONLY_ANNOTATIONS,
+    description: "Read up to 20 notes (or spans of them) in one call instead of repeated read_note calls, e.g. the top hits from search, query_notes, list_notes, or get_backlinks. Each item takes the same options as read_note and returns the same fields, in request order. budgetBytes (default 16384) caps the total note text: when the notes exceed it, each is cut to a fair share, marked truncated: true, and keeps noteBytes, so read the rest with read_note. A failing item (missing path, unknown section) returns its own error without failing the batch. contentHash is always the whole file's hash, usable as prevHash.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        items: {
+          type: "array",
+          description: "Notes to read, 1\u201320. Same options as read_note.",
+          items: {
+            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)."
+              },
+              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"]
+          }
+        },
+        budgetBytes: {
+          type: "number",
+          description: "Cap on total note text returned across all items, in UTF-8 bytes (256\u201365536, default 16384)."
+        }
+      },
+      required: ["items"]
+    }
+  },
   {
     name: "list_notes",
     annotations: READ_ONLY_ANNOTATIONS,
@@ -5046,7 +5246,10 @@ var ALL_TOOLS = [
       type: "object",
       properties: {
         folder: { type: "string", description: "Vault-relative folder prefix." },
-        tag: { type: "string", description: "Filter by tag (# prefix optional)." },
+        tag: {
+          type: "string",
+          description: 'Filter by tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        },
         limit: { type: "number", description: "Max results (1\u2013500, default 100)." }
       },
       required: []
@@ -5542,7 +5745,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.20.2" : "0.0.0-dev";
+var VERSION = true ? "0.21.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}